Convert mqba documentation to Doxygen format

This patch makes three changes:

  1. First, it converts the BDE-style component documentation into
     Doxygen `@file` documentation.  See the commit message in commit
     f3ca1d2 for more details on this.

  2. Next, it converts stray BDE-style documentation that was not
     automatically converted to Doxygen format when we open-sourced.
     Most of these are the documentation for member variables, but in
     some cases, overloads were not correctly converted either.

  3. Finally, it makes minor changes to non-Doxygen comments, like file
     header comments or include comments, which were not correctly
     updated in the past.

Signed-off-by: Patrick M. Niedzielski <[email protected]>

src/groups/mqb/mqba/mqba_adminsession.h

@@ -17,20 +17,17 @@
 #ifndef INCLUDED_MQBA_ADMINSESSION
 #define INCLUDED_MQBA_ADMINSESSION
 
-//@PURPOSE: Provide a session for interaction with BlazingMQ broker admin
-// clients.
-//
-//@CLASSES:
-//  mqba::AdminSession     : mechanism representing a session with an admin
-//  mqba::AdminSessionState: VST representing the state of a session
-//
-//@DESCRIPTION: This component provides a mechanism, 'mqba::AdminSession', that
-// allows BlazingMQ broker to send and receive messages from an admin connected
-// to the broker.  'mqba::AdminSessionState' is a value semantic type holding
-// the state associated to an 'mqba::Session'.
+/// @file mqba_adminsession.h
+///
+/// @brief Provide a session for interaction with BlazingMQ broker admin
+/// clients.
+///
+/// This component provides a mechanism, @bbref{mqba::AdminSession}, that
+/// allows BlazingMQ broker to send and receive messages from an admin
+/// connected to the broker.  @bbref{mqba::AdminSessionState} is a value
+/// semantic type holding the state associated to an 'mqba::Session'.
 
 // MQB
-
 #include <mqbi_dispatcher.h>
 #include <mqbi_queue.h>
 #include <mqbnet_session.h>
@@ -85,21 +82,19 @@ struct AdminSessionState {
 
   public:
     // PUBLIC DATA
+
+    /// Allocator to use.
     bslma::Allocator* d_allocator_p;
-    // Allocator to use.
 
+    /// Dispatcher client data associated to this session.
     mqbi::DispatcherClientData d_dispatcherClientData;
-    // Dispatcher client data associated to
-    // this session.
 
+    /// Pool of shared pointers to blobs to use.
     BlobSpPool* d_blobSpPool_p;
-    // Pool of shared pointers to blob to
-    // use.
 
+    /// Builder for schema messages.  To be used only in client dispatcher
+    /// thread.
     bmqp::SchemaEventBuilder d_schemaEventBuilder;
-    // Builder for schema messages.  To be
-    // used only in client dispatcher
-    // thread.
 
   private:
     // NOT IMPLEMENTED
@@ -136,43 +131,36 @@ class AdminSession : public mqbnet::Session, public mqbi::DispatcherClient {
 
   private:
     // DATA
+
+    /// This object is used to avoid executing a callback if the session has
+    /// been destroyed: this is *ONLY* to be used with the callbacks that will
+    /// be called from outside of the dispatcher's thread.
     bmqu::SharedResource<AdminSession> d_self;
-    // This object is used to avoid
-    // executing a callback if the session
-    // has been destroyed: this is *ONLY* to
-    // be used with the callbacks that will
-    // be called from outside of the
-    // dispatcher's thread.
 
+    /// Show whether the session is running.
     bool d_running;
-    // Show whether the session is running.
 
+    /// Negotiation message received from the remote peer.
     bmqp_ctrlmsg::NegotiationMessage d_negotiationMessage;
-    // Negotiation message received from the
-    // remote peer.
 
+    /// Raw pointer to the right field in `d_negotiationMessage` (depending on
+    /// whether it's a `client` or a `broker`).
     bmqp_ctrlmsg::ClientIdentity* d_clientIdentity_p;
-    // Raw pointer to the right field in
-    // 'd_negotiationMessage' (depending
-    // whether it's a 'client' or a
-    // 'broker').
 
+    /// Short identifier for this session.
     bsl::string d_description;
-    // Short identifier for this session.
 
+    /// Channel associated to this session.
     bsl::shared_ptr<bmqio::Channel> d_channel_sp;
-    // Channel associated to this session.
 
+    /// The state associated to this session.
     AdminSessionState d_state;
-    // The state associated to this session.
 
+    /// Pointer to the event scheduler to use (held, not owned).
     bdlmt::EventScheduler* d_scheduler_p;
-    // Pointer to the event scheduler to
-    // use (held, not owned)
 
+    /// The callback to invoke on received admin command.
     mqbnet::Session::AdminCommandEnqueueCb d_adminCb;
-    // The callback to invoke on received
-    // admin command.
 
   private:
     // NOT IMPLEMENTED

src/groups/mqb/mqba/mqba_application.h

@@ -17,21 +17,21 @@
 #ifndef INCLUDED_MQBA_APPLICATION
 #define INCLUDED_MQBA_APPLICATION
 
-//@PURPOSE: Provide an Application class to control object lifetime/creation.
-//
-//@CLASSES:
-//  mqba::Application: BlazingMQ broker application top level component
-//
-//@DESCRIPTION: This component defines a mechanism, 'mqba::Application',
-// responsible for instantiating and destroying the top-level BlazingMQ objects
-// used by the BlazingMQ broker.
+/// @file mqba_application.h
+///
+/// @brief Provide an `Application` class to control object lifetime/creation.
+///
+/// This component defines a mechanism, @bbref{mqba::Application}, responsible
+/// for instantiating and destroying the top-level BlazingMQ objects used by
+/// the BlazingMQ broker.
 
 // MQB
 #include <mqba_commandrouter.h>
 #include <mqbcmd_messages.h>
 #include <mqbconfm_messages.h>
 #include <mqbi_cluster.h>
 
+// BMQ
 #include <bmqma_countingallocatorstore.h>
 
 // BDE
@@ -110,41 +110,37 @@ class Application {
         BlobSpPool;
 
     // Data members
+
+    /// Allocator store to spawn new allocators for sub components.
     bmqma::CountingAllocatorStore d_allocators;
-    // Allocator store to spawn new allocators
-    // for sub-components
 
+    /// Event scheduler (held not owned to use, sharde with all interested
+    /// components.
     bdlmt::EventScheduler* d_scheduler_p;
-    // Event scheduler (held not owned) to use,
-    // shared with all interested components.
 
+    /// Thread pool for admin commands execution.
     bdlmt::ThreadPool d_adminExecutionPool;
-    // Thread pool for admin commands
-    // execution.
 
+    /// Thread pool for routed admin commands execution.  Ensuring rerouted
+    /// commands always execute on their own dedicated thread prevents a case
+    /// where two nodes are simultaneously waiting for each other to process a
+    /// routed command, but cannot make progress because the calling thread is
+    /// blocked ("deadlock").  Note that rerouted commands never route again.
     bdlmt::ThreadPool d_adminRerouteExecutionPool;
-    // Thread pool for routed admin commands execution.
-    // Ensuring rerouted commands always execute on their
-    // own dedicated thread prevents a case where two nodes
-    // are simultaneously waiting for each other to process
-    // a routed command, but cannot make process because
-    // the calling thread is blocked ("deadlock").
-    // Note that rerouted commands never route again.
 
     bdlbb::PooledBlobBufferFactory d_bufferFactory;
 
     BlobSpPool d_blobSpPool;
 
     bdlma::ConcurrentPool d_pushElementsPool;
 
+    /// Stat context of the counting allocators, if used.
     bmqst::StatContext* d_allocatorsStatContext_p;
-    // Stat context of the counting allocators,
-    // if used
 
     PluginManagerMp d_pluginManager_mp;
 
+    /// Statistics controller component.
     StatControllerMp d_statController_mp;
-    // Statistics controller component
 
     ConfigProviderMp d_configProvider_mp;
 
@@ -156,8 +152,8 @@ class Application {
 
     DomainManagerMp d_domainManager_mp;
 
+    /// Allocator to use.
     bslma::Allocator* d_allocator_p;
-    // Allocator to use
 
   private:
     // PRIVATE MANIPULATORS