QPID-1294 (Johnathan Robie) Improved doxygen generation.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk@711702 13f79535-47bb-0310-9956-ffa450edef68

6 files changed, 210 insertions, 2 deletions

diff --git a/qpid/cpp/docs/api/user.doxygen.in b/qpid/cpp/docs/api/user.doxygen.in
index ee0860f8b4..788bef8fe5 100644
--- a/qpid/cpp/docs/api/user.doxygen.in
+++ b/qpid/cpp/docs/api/user.doxygen.in
@@ -25,13 +25,13 @@
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = Qpid
+PROJECT_NAME           = "Qpid C++ Client API"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0
+# PROJECT_NUMBER         = 0
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
diff --git a/qpid/cpp/rubygen/framing.0-10/Session.rb b/qpid/cpp/rubygen/framing.0-10/Session.rb
index 299c45679f..16aae8c802 100644
--- a/qpid/cpp/rubygen/framing.0-10/Session.rb
+++ b/qpid/cpp/rubygen/framing.0-10/Session.rb
@@ -30,6 +30,8 @@ class CppGen
     }
   end
 
+  
+  # Generates a doxygen comment for AmqpMethod m.
   def doxygen(m)
     doxygen_comment {
       genl m.doc
diff --git a/qpid/cpp/src/qpid/client/LocalQueue.h b/qpid/cpp/src/qpid/client/LocalQueue.h
index 2b878b2939..30ea00612d 100644
--- a/qpid/cpp/src/qpid/client/LocalQueue.h
+++ b/qpid/cpp/src/qpid/client/LocalQueue.h
@@ -37,7 +37,37 @@ namespace client {
  * local queue until you retrieve them.
  *
  * \ingroup clientapi
+ *
+ * \details Using a Local Queue
+ *
+ * <pre>
+ * LocalQueue local_queue;
+ * subscriptions.subscribe(local_queue, string("message_queue"));
+ * for (int i=0; i&lt;10; i++) {
+ *   Message message = local_queue.get();
+ *   std::cout &lt;&lt; message.getData() &lt;&lt; std::endl;
+ * }
+ * </pre>
+ * 
+ * <h2>Getting Messages</h2>
+ *
+ * <ul><li>
+ * <p>get()</p>
+ * <pre>Message message = local_queue.get();</pre>
+ * <pre>// Specifying timeouts (TIME_SEC, TIME_MSEC, TIME_USEC, TIME_NSEC)
+ *#include <qpid/sys/Time.h>
+ *Message message;
+ *local_queue.get(message, 5*sys::TIME_SEC);</pre></li></ul>
+ * 
+ * <h2>Checking size</h2>
+ * <ul><li>
+ * <p>empty()</p>
+ * <pre>if (local_queue.empty()) { ... }</pre></li>
+ * <li><p>size()</p>
+ * <pre>std::cout &lt;&lt; local_queue.size();</pre></li>
+ * </ul>
  */
+
 class LocalQueue {
   public:
     /** Create a local queue. Subscribe the local queue to a remote broker
diff --git a/qpid/cpp/src/qpid/client/Message.h b/qpid/cpp/src/qpid/client/Message.h
index 18efdd20f7..3f932efd8b 100644
--- a/qpid/cpp/src/qpid/client/Message.h
+++ b/qpid/cpp/src/qpid/client/Message.h
@@ -33,7 +33,77 @@ namespace client {
  * A message sent to or received from the broker.
  *
  * \ingroup clientapi
+ * \details 
+ * 
+ * <h2>Getting and setting message contents</h2>
+ *
+ * <ul>
+ * <li> 
+ * <p>getData()</p>
+ * <pre>std::cout &lt;&lt; "Response: " &lt;&lt; message.getData() &lt;&lt; std::endl;</pre>
+ * </li>
+ * <li>
+ * <p>setData()</p>
+ * <pre>message.setData("That's all, folks!");</pre></li>
+ * <li>
+ * <p>appendData()</p>
+ * <pre>message.appendData(" ... let's add a bit more ...");</pre></li>
+ * </ul>
+ * 
+ * <h2>Getting and Setting Delivery Properties</h2>
+ * 
+ * <ul>
+ * <li>
+ * <p>getDeliveryProperties()</p>
+ * <pre>message.getDeliveryProperties().setRoutingKey("control");</pre>
+ * <pre>message.getDeliveryProperties().setDeliveryMode(PERSISTENT);</pre>
+ * <pre>message.getDeliveryProperties().setPriority(9);</pre>
+ * <pre>message.getDeliveryProperties().setTtl(100);</pre></li>
+ * 
+ * <li>
+ * <p>hasDeliveryProperties()</p>
+ * <pre>if (! message.hasDeliveryProperties()) {
+ *  ...
+ *}</pre></li>
+ * </ul>
+ * 
+ * <h2>Getting and Setting Message Properties</h2>
+ * 
+ * <ul>
+ * <li>
+ * <p>getMessageProperties()</p>
+ * <pre>
+ *request.getMessageProperties().setReplyTo(ReplyTo("amq.direct", response_queue.str()));
+ * </pre>
+ * <pre>
+ *routingKey = request.getMessageProperties().getReplyTo().getRoutingKey();
+ *exchange = request.getMessageProperties().getReplyTo().getExchange();
+ * </pre>
+ * <pre>message.getMessageProperties().setContentType("text/plain");</pre>
+ * <pre>message.getMessageProperties().setContentEncoding("text/plain");</pre>
+ * </li>
+ * <li>
+ * <p>hasMessageProperties()</p>
+ * <pre>request.getMessageProperties().hasReplyTo();</pre>
+ * </li>
+ * </ul>
+ * 
+ * <h2>Getting and Setting Application Headers</h2>
+ * 
+ * <ul>
+ * <li>
+ * <p>getHeaders()</p>
+ * <pre>
+ *message.getHeaders().getString("control");
+ * </pre>
+ * <pre>
+ *message.getHeaders().setString("control","continue");
+ * </pre></li>
+ * </ul>
+ * 
+ * 
  */
+
 class Message : public framing::TransferContent 
 {
 public:
diff --git a/qpid/cpp/src/qpid/client/MessageListener.h b/qpid/cpp/src/qpid/client/MessageListener.h
index 76e1d17445..75aad6521b 100644
--- a/qpid/cpp/src/qpid/client/MessageListener.h
+++ b/qpid/cpp/src/qpid/client/MessageListener.h
@@ -35,7 +35,54 @@ namespace client {
      * Another way to receive messages is by using a LocalQueue.
      * 
      * \ingroup clientapi
+     * \details 
+     *
+     * <h2>Using a MessageListener</h2>
+     * 
+     * <ul>
+     * <li>
+     * <p>The received() function is called when a message arrives:</p>
+     * <pre>virtual void received(Message&amp; message)=0;</pre>
+     * </li>
+     * <li>
+     * <p>Derive your own listener, implement the received() function:</p>
+     * <pre>
+     * class Listener : public MessageListener {
+     *  private:
+     *    SubscriptionManager&amp; subscriptions;
+     *  public:
+     *    Listener(SubscriptionManager&amp; subscriptions);
+     *    virtual void received(Message&amp; message);
+     * };
+     * 
+     * Listener::Listener(SubscriptionManager&amp; subs) : subscriptions(subs)
+     * {}
+     * 
+     * void Listener::received(Message&amp; message) {
+     *   std::cout &lt;&lt; "Message: " &lt;&lt; message.getData() &lt;&lt; std::endl;
+     *   if (message.getData() == "That's all, folks!") {
+     *       std::cout &lt;&lt; "Shutting down listener for " &lt;&lt; message.getDestination()
+     *                &lt;&lt; std::endl;
+     *       subscriptions.cancel(message.getDestination());
+     *   }
+     * }
+     *</pre>
+     * <pre>
+     * SubscriptionManager subscriptions(session);
+     * 
+     * // Create a listener and subscribe it to the queue named "message_queue"
+     * Listener listener(subscriptions);
+     * subscriptions.subscribe(listener, "message_queue");
+     * 
+     * // Receive messages until the subscription is cancelled
+     * // by Listener::received()
+     * subscriptions.run();
+     * </pre>
+     * </li>
+     * </ul>
+     * 
      */
+
     class MessageListener{
     public:
         virtual ~MessageListener();
diff --git a/qpid/cpp/src/qpid/client/SubscriptionManager.h b/qpid/cpp/src/qpid/client/SubscriptionManager.h
index 393349a6af..58d880fa83 100644
--- a/qpid/cpp/src/qpid/client/SubscriptionManager.h
+++ b/qpid/cpp/src/qpid/client/SubscriptionManager.h
@@ -43,6 +43,65 @@ namespace client {
  * delivered.
  *  
  * \ingroup clientapi
+ *
+ * \details
+ * 
+ * <h2>Subscribing and canceling subscriptions</h2>
+ *
+ * <ul>
+ * <li> 
+ * <p>subscribe()</p>
+ * <pre> SubscriptionManager subscriptions(session);
+ * Listener listener(subscriptions);
+ * subscriptions.subscribe(listener, myQueue);</pre>
+ * <pre> SubscriptionManager subscriptions(session);
+ * LocalQueue local_queue;
+ * subscriptions.subscribe(local_queue, string("message_queue"));</pre></li>
+ * <li>
+ * <p>cancel()</p>
+ * <pre>subscriptions.cancel();</pre></li>
+ * </ul>
+ * 
+ * <h2>Waiting for messages (and returning)</h2>
+ *
+ * <ul>
+ * <li> 
+ * <p>run()</p>
+ * <pre> // Give up control to receive messages
+ * subscriptions.run();</pre></li>
+ * <li>
+ * <p>stop()</p>
+ * <pre>.// Use this code in a listener to return from run()
+ * subscriptions.stop();</pre></li>
+ * <li>
+ * <p>setAutoStop()</p>
+ * <pre>.// Return from subscriptions.run() when last subscription is cancelled
+ *.subscriptions.setAutoStop(true);
+ *.subscriptons.run();
+ * </pre></li>
+ * <li>
+ * <p>Ending a subscription in a listener</p>
+ * <pre>
+ * void Listener::received(Message&amp; message) {
+ * 
+ *  if (message.getData() == "That's all, folks!") {
+ *       subscriptions.cancel(message.getDestination());
+ *   }
+ * }
+ * </pre>
+ * </li>
+ * </ul>
+ * 
+ * 
+ * <h2>Setting Accept Mode, Acquire Mode, Ack Policy</h2>
+ * 
+ * <p>setAcceptMode()</p>
+ * <pre>subscriptions.setAcceptMode(true);</pre>
+ * <p>setAcquireMode()</p>
+ * <pre>subscriptions.setAcquireMode(false);</pre>
+ * 
+ * 
+ * 
  */
 class SubscriptionManager : public sys::Runnable
 {