Docs[BMQ] bde -> doxygen conversion fixes (#443)

* Doc[BMQT] minor bde -> doxygen docs * Doc[BMQA] minor bde -> doxygen docs * Doc[BMQA] re-wrap data member comments * Doc[BMQT] re-wrap data member comments * Apply suggestions from code review --------- Signed-off-by: Christopher Beard <[email protected]> Signed-off-by: Chris Beard <[email protected]> Co-authored-by: Evgeny Malygin <[email protected]>
bloomberg · Oct 7, 2024 · 6190b97 · 6190b97
1 parent 14fec0d
commit 6190b97
Show file tree

Hide file tree

Showing 15 changed files with 219 additions and 242 deletions.
diff --git a/src/groups/bmq/bmqa/bmqa_closequeuestatus.h b/src/groups/bmq/bmqa/bmqa_closequeuestatus.h
@@ -62,18 +62,15 @@ namespace bmqa {
 class CloseQueueStatus {
   private:
     // DATA
+
+    /// QueueId associated with the open queue operation
     QueueId d_queueId;
-    // queueId associated with the open
-    // queue operation
 
+    /// Result code of the operation (success, failure)
     bmqt::CloseQueueResult::Enum d_result;
-    // Result code of the operation
-    // (success, failure)
 
+    /// Optional string with a human readable description of the error, if any
     bsl::string d_errorDescription;
-    // Optional string with a human
-    // readable description of the error,
-    // if any
 
   public:
     // TRAITS

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

diff --git a/src/groups/bmq/bmqa/bmqa_message.h b/src/groups/bmq/bmqa/bmqa_message.h
@@ -101,30 +101,25 @@ class MessageProperties;
 ///                      `bmqa::MessageIterator.nextMessage()`.
 struct MessageImpl {
     // PUBLIC DATA
+
+    /// Pointer to the Event this message is associated with
     bmqimp::Event* d_event_p;
-    // Pointer to the Event this message is
-    // associated with
 
+    /// May point to a bmqimp::Event (in case this Message is a clone)
     bsl::shared_ptr<bmqimp::Event> d_clonedEvent_sp;
-    // May point to a bmqimp::Event (in case
-    // this Message is a clone)
 
+    /// QueueId this message is associated with
     bmqa::QueueId d_queueId;
-    // QueueId this message is associated
-    // with
 
+    /// CorrelationId this message is associated with
     bmqt::CorrelationId d_correlationId;
-    // CorrelationId this message is
-    // associated with
 
+    /// SubscriptionHandle this message is associated with
     bmqt::SubscriptionHandle d_subscriptionHandle;
-    // SubscriptionHandle this message is
-    // associated with
 
 #ifdef BMQ_ENABLE_MSG_GROUPID
+    /// Optional GroupId this message is associated with
     bsl::string d_groupId;
-    // Optional Group Id this message is
-    // associated with
 #endif
 };
 
@@ -136,11 +131,12 @@ struct MessageImpl {
 class MessageConfirmationCookie {
   private:
     // DATA
+
+    /// QueueID associated to this cookie
     bmqa::QueueId d_queueId;
-    // QueueID associated to this cookie
 
+    /// GUID associated to this cookie
     bmqt::MessageGUID d_guid;
-    // GUID associated to this cookie
 
   public:
     // CREATORS

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,18 +64,18 @@ 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;
 
+    /// 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;
-    // Position of 'd_message' in the underlying
-    // message event.
 };
 
 // =====================

diff --git a/src/groups/bmq/bmqa/bmqa_messageproperties.h b/src/groups/bmq/bmqa/bmqa_messageproperties.h
@@ -96,9 +96,9 @@ class MessageProperties {
   private:
     // PRIVATE CONSTANTS
 
-    // Constant representing the maximum size of a
-    // `bmqp::MessageProperties` object, so that the below AlignedBuffer
-    // is big enough.
+    /// Constant representing the maximum size of a
+    /// `bmqp::MessageProperties` object, so that the below AlignedBuffer
+    /// is big enough.
     static const int k_MAX_SIZEOF_BMQP_MESSAGEPROPERTIES = 184;
 
     // PRIVATE TYPES
@@ -107,18 +107,15 @@ 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
+    /// reinterpret_cast to that variable.
     mutable bmqp::MessageProperties* d_impl_p;
-    // 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.
 
+    /// Buffer containing the implementation object, maximally aligned.
     ImplBuffer d_buffer;
-    // Buffer containing the implementation
-    // object, maximally aligned.
 
     bslma::Allocator* d_allocator_p;
 
@@ -128,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