From ff41ae6f61af44e6a365241074a78204993d4818 Mon Sep 17 00:00:00 2001 From: Christopher Beard Date: Mon, 7 Oct 2024 11:49:36 -0400 Subject: [PATCH] Doc[BMQA] re-wrap data member comments Signed-off-by: Christopher Beard --- src/groups/bmq/bmqa/bmqa_closequeuestatus.h | 16 ++-- .../bmq/bmqa/bmqa_configurequeuestatus.h | 10 +-- src/groups/bmq/bmqa/bmqa_message.h | 18 ++--- .../bmq/bmqa/bmqa_messageeventbuilder.h | 15 ++-- src/groups/bmq/bmqa/bmqa_messageiterator.h | 18 ++--- src/groups/bmq/bmqa/bmqa_messageproperties.h | 31 ++++---- src/groups/bmq/bmqa/bmqa_mocksession.h | 75 ++++++++----------- src/groups/bmq/bmqa/bmqa_openqueuestatus.h | 10 +-- src/groups/bmq/bmqa/bmqa_session.h | 7 +- 9 files changed, 82 insertions(+), 118 deletions(-) diff --git a/src/groups/bmq/bmqa/bmqa_closequeuestatus.h b/src/groups/bmq/bmqa/bmqa_closequeuestatus.h index affb8123f..d13f5275a 100644 --- 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::BoolType BoolType; // CREATORS diff --git a/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h b/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h index 5b2fa6ed7..698f2e6e3 100644 --- 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 index b8c7dd63f..b3d8fc211 100644 --- 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 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 index c9cc54073..a3238747b 100644 --- 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 d_guidGenerator_sp; // GUID generator object. + bsl::shared_ptr 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 index d3855bf5e..5c1d31570 100644 --- 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 index b41cecf5c..eb4078548 100644 --- 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 index 918a50cf8..5ac9f7562 100644 --- 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 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 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 index 36d04234d..41eaf52bb 100644 --- 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: diff --git a/src/groups/bmq/bmqa/bmqa_session.h b/src/groups/bmq/bmqa/bmqa_session.h index d6d7861c6..6e1423b1e 100644 --- a/src/groups/bmq/bmqa/bmqa_session.h +++ b/src/groups/bmq/bmqa/bmqa_session.h @@ -640,13 +640,10 @@ struct SessionImpl { /// The allocator to use bslma::Allocator* d_allocator_p; - /// Session options as provided by - /// the application. + /// Session options as provided by the application. bmqt::SessionOptions d_sessionOptions; - /// Event handler, if any, to use - /// for notifying application of - /// events. + /// Event handler, if any, to use for notifying application of events. bslma::ManagedPtr d_eventHandler_mp; /// GUID generator object.