Doc[BMQA] re-wrap data member comments

Signed-off-by: Christopher Beard <[email protected]>
bloomberg · Oct 7, 2024 · ff41ae6 · ff41ae6
1 parent 940c90a
commit ff41ae6
Show file tree

Hide file tree

Showing 9 changed files with 82 additions and 118 deletions.
diff --git a/src/groups/bmq/bmqa/bmqa_closequeuestatus.h b/src/groups/bmq/bmqa/bmqa_closequeuestatus.h
@@ -63,17 +63,13 @@ class CloseQueueStatus {
   private:
     // DATA
 
-    /// queueId associated with the open
-    /// queue operation
+    /// queueId associated with the open queue operation
     QueueId d_queueId;
 
-    /// Result code of the operation
-    /// (success, failure)
+    /// Result code of the operation (success, failure)
     bmqt::CloseQueueResult::Enum d_result;
 
-    /// Optional string with a human
-    /// readable description of the error,
-    /// if any
+    /// Optional string with a human readable description of the error, if any
     bsl::string d_errorDescription;
 
   public:
@@ -82,9 +78,9 @@ class CloseQueueStatus {
 
     // TYPES
 
-    /// Use of an `UnspecifiedBool` to prevent implicit conversions to
-    /// integral values, and comparisons between different classes which
-    /// have boolean operators.
+    // Use of an `UnspecifiedBool` to prevent implicit conversions to
+    // integral values, and comparisons between different classes which
+    // have boolean operators.
     typedef bsls::UnspecifiedBool<CloseQueueStatus>::BoolType BoolType;
 
     // CREATORS

diff --git a/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h b/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h
@@ -62,17 +62,13 @@ class ConfigureQueueStatus {
   private:
     // DATA
 
-    /// queueId associated with the open
-    /// queue operation
+    /// queueId associated with the open queue operation
     QueueId d_queueId;
 
-    /// Status code of the operation
-    /// (success, failure)
+    /// Status code of the operation (success, failure)
     bmqt::ConfigureQueueResult::Enum d_result;
 
-    /// Optional string with a human
-    /// readable description of the error,
-    /// if any
+    /// Optional string with a human readable description of the error, if any
     bsl::string d_errorDescription;
 
   public:

diff --git a/src/groups/bmq/bmqa/bmqa_message.h b/src/groups/bmq/bmqa/bmqa_message.h
@@ -102,30 +102,24 @@ class MessageProperties;
 struct MessageImpl {
     // PUBLIC DATA
 
-    /// Pointer to the Event this message is
-    /// associated with
+    /// Pointer to the Event this message is associated with
     bmqimp::Event* d_event_p;
 
-    /// May point to a bmqimp::Event (in case
-    /// this Message is a clone)
+    /// May point to a bmqimp::Event (in case this Message is a clone)
     bsl::shared_ptr<bmqimp::Event> d_clonedEvent_sp;
 
-    /// QueueId this message is associated
-    /// with
+    /// QueueId this message is associated with
     bmqa::QueueId d_queueId;
 
-    /// CorrelationId this message is
-    /// associated with
+    /// CorrelationId this message is associated with
     bmqt::CorrelationId d_correlationId;
 
-    /// SubscriptionHandle this message is
-    /// associated with
+    /// SubscriptionHandle this message is associated with
     bmqt::SubscriptionHandle d_subscriptionHandle;
 
 #ifdef BMQ_ENABLE_MSG_GROUPID
+    /// Optional Group Id this message is associated with
     bsl::string d_groupId;
-    // Optional Group Id this message is
-    // associated with
 #endif
 };
 

diff --git a/src/groups/bmq/bmqa/bmqa_messageeventbuilder.h b/src/groups/bmq/bmqa/bmqa_messageeventbuilder.h
@@ -284,30 +284,31 @@ namespace bmqa {
 /// to expose them publicly).
 struct MessageEventBuilderImpl {
     // PUBLIC DATA
-    MessageEvent d_msgEvent;  // This is needed so that 'getMessageEvent()' can
-                              // return a const ref.
 
-    Message d_msg;  // This is needed so that 'startMessage()' can
-                    // return a ref.
+    // This is needed so that 'getMessageEvent()' can return a const ref.
+    MessageEvent d_msgEvent;
+
+    // This is needed so that 'startMessage()' can return a ref.
+    Message d_msg;
 
-    bsl::shared_ptr<bmqp::MessageGUIDGenerator> d_guidGenerator_sp;
     // GUID generator object.
+    bsl::shared_ptr<bmqp::MessageGUIDGenerator> d_guidGenerator_sp;
 
-    int d_messageCountFinal;
     // The final number of messages in the current 'd_msgEvent' cached on
     // switching this MessageEvent from WRITE to READ mode.
     // This cached value exists because we are not able to access the
     // underlying PutEventBuilder once downgraded to READ.
     // CONTRACT: the stored value is correct every moment when in READ mode,
     // and the value is not guaranteed to be correct when in WRITE mode.
+    int d_messageCountFinal;
 
-    int d_messageEventSizeFinal;
     // The final message event size of the current 'd_msgEvent' cached on
     // switching this MessageEvent from WRITE to READ mode.
     // This cached value exists because we are not able to access the
     // underlying PutEventBuilder once downgraded to READ.
     // CONTRACT: the stored value is correct every moment when in READ mode,
     // and the value is not guaranteed to be correct when in WRITE mode.
+    int d_messageEventSizeFinal;
 };
 
 // =========================

diff --git a/src/groups/bmq/bmqa/bmqa_messageiterator.h b/src/groups/bmq/bmqa/bmqa_messageiterator.h
@@ -64,17 +64,17 @@ namespace bmqa {
 /// without publicly exposing private members.
 struct MessageIteratorImpl {
     // PUBLIC DATA
-    bmqimp::Event* d_event_p;  // Raw pointer to the event
 
-    bmqa::Message d_message;  // A 'Message', representing a view to the
-                              // current message pointing at by this iterator.
-                              // This is so that 'message' can return a 'const
-                              // Message&' to clearly indicate the lifetime of
-                              // the Message, and so that we only create one
-                              // such object per MessageIterator.
+    /// Raw pointer to the event
+    bmqimp::Event* d_event_p;
 
-    /// Position of 'd_message' in the underlying
-    /// message event.
+    /// A 'Message', representing a view to the current message pointing at by
+    /// this iterator.  This is so that 'message' can return a 'const Message&'
+    /// to clearly indicate the lifetime of the Message, and so that we only
+    /// create one such object per MessageIterator.
+    bmqa::Message d_message;
+
+    /// Position of 'd_message' in the underlying message event.
     int d_messageIndex;
 };
 

diff --git a/src/groups/bmq/bmqa/bmqa_messageproperties.h b/src/groups/bmq/bmqa/bmqa_messageproperties.h
@@ -108,17 +108,13 @@ class MessageProperties {
   private:
     // DATA
 
-    /// Pointer to the implementation object
-    /// in 'd_buffer', providing a shortcut
-    /// type safe cast to that object.  This
-    /// variable *must* *be* the first
-    /// member of this class, as other
-    /// components in bmqa package may
+    /// Pointer to the implementation object in 'd_buffer', providing a
+    /// shortcut type safe cast to that object. This variable *must* *be* the
+    /// first member of this class, as other components in bmqa package may
     /// reinterpret_cast to that variable.
     mutable bmqp::MessageProperties* d_impl_p;
 
-    /// Buffer containing the implementation
-    /// object, maximally aligned.
+    /// Buffer containing the implementation object, maximally aligned.
     ImplBuffer d_buffer;
 
     bslma::Allocator* d_allocator_p;
@@ -129,21 +125,20 @@ class MessageProperties {
     /// Maximum number of properties that can appear in a `bmqa::Message`.
     static const int k_MAX_NUM_PROPERTIES = 255;
 
+    /// Maximum length of all the properties (including their names, values
+    /// and the wire protocol overhead).  Note that this value is just under
+    /// 64 MB.
     static const int k_MAX_PROPERTIES_AREA_LENGTH = (64 * 1024 * 1024) - 8;
-    // Maximum length of all the properties (including their names, values
-    // and the wire protocol overhead).  Note that this value is just under
-    // 64 MB.
 
     /// Maximum length of a property name.
     static const int k_MAX_PROPERTY_NAME_LENGTH = 4095;
 
-    static const int k_MAX_PROPERTY_VALUE_LENGTH =
-        67104745;  // ~64 MB
-                   // Maximum length of a property value.  Note that this value
-                   // is just under 64 MB.  Also note that this value is
-                   // calculated assuming that there is only one property and
-                   // property's name has maximum allowable length, and also
-                   // takes into consideration the protocol overhead.
+    /// ~64 MB
+    /// Maximum length of a property value.  Note that this value is just under
+    /// 64 MB.  Also note that this value is calculated assuming that there is
+    /// only one property and property's name has maximum allowable length, and
+    /// also takes into consideration the protocol overhead.
+    static const int k_MAX_PROPERTY_VALUE_LENGTH = 67104745;
 
   public:
     // TRAITS

diff --git a/src/groups/bmq/bmqa/bmqa_mocksession.h b/src/groups/bmq/bmqa/bmqa_mocksession.h
@@ -650,14 +650,18 @@ struct MockSessionUtil {
     /// Struct representing parameters for a push message.
     struct PushMessageParams {
         // PUBLIC DATA
-        bdlbb::Blob d_payload;  // Payload of message
 
-        QueueId d_queueId;  // Queue Id for this message
+        /// Payload of message
+        bdlbb::Blob d_payload;
 
-        bmqt::MessageGUID d_guid;  // GUID for message
+        /// Queue Id for this message
+        QueueId d_queueId;
+
+        /// GUID for message
+        bmqt::MessageGUID d_guid;
 
-        MessageProperties d_properties;  // Optionally specified properties for
-                                         // message
+        /// Optionally specified properties for message
+        MessageProperties d_properties;
 
         // CREATORS
 
@@ -787,10 +791,10 @@ class MockSession : public AbstractSession {
   private:
     // CONSTANTS
 
-    // Constant representing the maximum size of a `mwcc::TwoKeyHashMap`
-    // object, so that the below AlignedBuffer is big enough.  No `mwc`
-    // headers can be included in `bmq` public headers, to prevent build
-    // time dependency.
+    /// Constant representing the maximum size of a `mwcc::TwoKeyHashMap`
+    /// object, so that the below AlignedBuffer is big enough.  No `mwc`
+    /// headers can be included in `bmq` public headers, to prevent build
+    /// time dependency.
     static const int k_MAX_SIZEOF_MWCC_TWOKEYHASHMAP = 256;
 
     // PRIVATE TYPES
@@ -825,8 +829,8 @@ class MockSession : public AbstractSession {
         /// Queue associated with this job
         QueueImplSp d_queue;
 
-        /// Type of queue event associated with
-        /// this job (OPEN,CONFIGURE, or CLOSE)
+        /// Type of queue event associated with this job (OPEN, CONFIGURE, or
+        /// CLOSE)
         bmqt::SessionEventType::Enum d_type;
 
         /// Status of the queue operation
@@ -887,39 +891,31 @@ class MockSession : public AbstractSession {
         /// Flags associated with this call
         bsls::Types::Uint64 d_flags;
 
-        /// QueueOptions associated with this
-        /// call
+        /// QueueOptions associated with this call
         bmqt::QueueOptions d_queueOptions;
 
-        /// Timeout interval associated with
-        /// this call
+        /// Timeout interval associated with this call
         bsls::TimeInterval d_timeout;
 
-        // Callback to be invoked upon emission
-        // of an async openQueue (if callback
-        // was provided)
+        /// Callback to be invoked upon emission of an async openQueue (if
+        /// callback was provided)
         OpenQueueCallback d_openQueueCallback;
 
-        /// Callback to be invoked upon emission
-        /// of an async configureQueue (if
+        /// Callback to be invoked upon emission of an async configureQueue (if
         /// callback was provided)
         ConfigureQueueCallback d_configureQueueCallback;
 
-        /// Callback to be invoked upon emission
-        /// of an async closeQueue (if callback
-        /// was provided)
+        /// Callback to be invoked upon emission of an async closeQueue (if
+        /// callback was provided)
         CloseQueueCallback d_closeQueueCallback;
 
-        /// The result of an open queue
-        /// operation
+        /// The result of an open queue operation
         bmqa::OpenQueueStatus d_openQueueResult;
 
-        /// The result of a configure queue
-        /// operation
+        /// The result of a configure queue operation
         bmqa::ConfigureQueueStatus d_configureQueueResult;
 
-        /// The result of a close queue
-        /// operation
+        /// The result of a close queue operation
         bmqa::CloseQueueStatus d_closeQueueResult;
 
         /// Events to be emitted on this call
@@ -928,12 +924,10 @@ class MockSession : public AbstractSession {
         /// Event to be returned on this call
         Event d_returnEvent;
 
-        /// MessageEvent associated with this
-        /// call
+        /// MessageEvent associated with this call
         MessageEvent d_messageEvent;
 
-        /// MessageConfirmationCookie associated
-        /// with this call
+        /// MessageConfirmationCookie associated with this call
         MessageConfirmationCookie d_cookie;
 
         /// Allocator
@@ -1017,12 +1011,10 @@ class MockSession : public AbstractSession {
     /// Buffer factory
     bdlbb::PooledBlobBufferFactory d_blobBufferFactory;
 
-    /// Event handler (set only in
-    /// asynchronous mode)
+    /// Event handler (set only in asynchronous mode)
     bslma::ManagedPtr<SessionEventHandler> d_eventHandler_mp;
 
-    /// sequence of method calls that are
-    /// expected
+    /// sequence of method calls that are expected
     mutable CallQueue d_calls;
 
     /// events waiting to be emitted
@@ -1031,12 +1023,10 @@ class MockSession : public AbstractSession {
     /// GUIDS of unconfirmed messages
     bsl::unordered_set<bmqt::MessageGUID> d_unconfirmedGUIDs;
 
-    /// Aligned buffer of two key hash map
-    /// uri, corrid to queues
+    /// Aligned buffer of two key hash map uri, corrid to queues
     TwoKeyHashMapBuffer d_twoKeyHashMapBuffer;
 
-    /// Currently installed failure callback
-    /// that is invoked if methods are
+    /// Currently installed failure callback that is invoked if methods are
     /// called incorrectly or out of order.
     FailureCb d_failureCb;
 
@@ -1052,8 +1042,7 @@ class MockSession : public AbstractSession {
     /// protects all public methods
     mutable bslmt::Mutex d_mutex;
 
-    /// Top level stat context for this
-    /// mocked Session.
+    /// Top level stat context for this mocked Session.
     mwcst::StatContext d_rootStatContext;
 
     /// Stats for all queues

diff --git a/src/groups/bmq/bmqa/bmqa_openqueuestatus.h b/src/groups/bmq/bmqa/bmqa_openqueuestatus.h
@@ -63,17 +63,13 @@ class OpenQueueStatus {
   private:
     // DATA
 
-    /// queueId associated with the open
-    /// queue operation
+    /// queueId associated with the open queue operation
     QueueId d_queueId;
 
-    /// Result code of the operation
-    /// (success, failure)
+    /// Result code of the operation (success, failure)
     bmqt::OpenQueueResult::Enum d_result;
 
-    /// Optional string with a human
-    /// readable description of the error,
-    /// if any
+    /// Optional string with a human readable description of the error, if any
     bsl::string d_errorDescription;
 
   public: