QPID-2087: Some amplification of doxygen for SubscriptionSettings

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

1 files changed, 35 insertions, 4 deletions

diff --git a/qpid/cpp/include/qpid/client/SubscriptionSettings.h b/qpid/cpp/include/qpid/client/SubscriptionSettings.h
index 4d64119d3a..b4cb302b56 100644
--- a/qpid/cpp/include/qpid/client/SubscriptionSettings.h
+++ b/qpid/cpp/include/qpid/client/SubscriptionSettings.h
@@ -49,13 +49,44 @@ struct SubscriptionSettings
     ) : flowControl(flow), acceptMode(accept), acquireMode(acquire), autoAck(autoAck_), completionMode(completion), exclusive(false) {}
 
     FlowControl flowControl;    ///@< Flow control settings. @see FlowControl
+    /**
+     * The acceptMode determines whether the broker should expect
+     * delivery of messages to be acknowledged by the client
+     * indicating that it accepts them. A value of
+     * ACCEPT_MODE_EXPLICIT means that messages must be accepted
+     * (note: this may be done automatically by the library - see
+     * autoAck - or through an explicit call be the application - see
+     * Subscription::accept()) before they can be dequeued. A value of
+     * ACCEPT_MODE_NONE means that the broker can dequeue a message as
+     * soon as it is acquired.
+     */
     AcceptMode acceptMode;      ///@< ACCEPT_MODE_EXPLICIT or ACCEPT_MODE_NONE
+    /**
+     * The acquireMode determines whether messages are locked for the
+     * subscriber when delivered, and thus are not delivered to any
+     * other subscriber unless this subscriber releases them. 
+     * 
+     * The default is ACQUIRE_MODE_PRE_ACQUIRED meaning that the
+     * subscriber expects to have been given that message exclusively
+     * (i.e. the message will not be given to any other subscriber
+     * unless released explicitly or by this subscribers session
+     * failing without having accepted the message).
+     * 
+     * Delivery of message in ACQUIRE_MODE_NOT_ACQUIRED mode means the
+     * message will still be available for other subscribers to
+     * receive. The application can if desired acquire a (set of)
+     * messages through an explicit acquire call - see
+     * Subscription::acquire().
+     */
     AcquireMode acquireMode;    ///@< ACQUIRE_MODE_PRE_ACQUIRED or ACQUIRE_MODE_NOT_ACQUIRED
 
-    /** Automatically acknowledge (accept) batches of autoAck
-     *  messages. 0 means no automatic acknowledgement. This has no
-     *  effect for messsages received for a subscription with
-     *  ACCEPT_MODE_NODE.*/
+    /**
+     * Configures the frequency at which messages are automatically
+     * accepted (e.g. a value of 5 means that messages are accepted in
+     * batches of 5). A value of 0 means no automatic acknowledgement
+     * will occur and the application will itself be responsible for
+     * accepting messages.
+     */
     unsigned int autoAck;
     /**
      * In windowing mode, completion of a message will cause the