From 12bc29e98f418a0d96d7c74e6df108dca2767e28 Mon Sep 17 00:00:00 2001 From: "Patrick M. Niedzielski" Date: Tue, 4 Feb 2025 23:54:22 +0000 Subject: [PATCH] Docs[mqbcfg]: Complete conversion of mqbcfg documentation from BDE style to Doxygen style (#575) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Convert mqbcfg documentation to Doxygen format This patch makes two changes: 1. First, it converts the BDE-style component documentation into Doxygen `@file` documentation. 2. Next, it converts stray BDE-style documentation that was not automatically converted to Doxygen format when we open-sourced. This patch continues the work from commit d47304d. Signed-off-by: Patrick M. Niedzielski * Migrate mqbcfg docs directory into a Doxygen file This patch removes the old `doc/*.txt` file and migrates some information in it into a file Doxygen can read. The information not migrated is: 1. the table of contents for this package, which can be auto-generated from each component’s documentation, and 2. the hierarchical synopsis. This continues the changes made in commit 8c8af57. Signed-off-by: Patrick M. Niedzielski --------- Signed-off-by: Patrick M. Niedzielski --- src/groups/mqb/mqbcfg/README.dox | 9 ++++++ src/groups/mqb/mqbcfg/doc/mqbcfg.txt | 28 ------------------- src/groups/mqb/mqbcfg/mqbcfg_brokerconfig.h | 16 +++++------ .../mqbcfg_tcpinterfaceconfigvalidator.h | 19 ++++++------- 4 files changed, 25 insertions(+), 47 deletions(-) create mode 100644 src/groups/mqb/mqbcfg/README.dox delete mode 100644 src/groups/mqb/mqbcfg/doc/mqbcfg.txt diff --git a/src/groups/mqb/mqbcfg/README.dox b/src/groups/mqb/mqbcfg/README.dox new file mode 100644 index 0000000000..d690ff7a3a --- /dev/null +++ b/src/groups/mqb/mqbcfg/README.dox @@ -0,0 +1,9 @@ +/** +@dir mqbcfg + +@brief The `MQBCFG` (BlazingMQ Broker Config) package provide broker +configuration schema and message component. + +This package provides the schema of the configuration used by the broker, as +well as the generated corresponding messages component. +*/ diff --git a/src/groups/mqb/mqbcfg/doc/mqbcfg.txt b/src/groups/mqb/mqbcfg/doc/mqbcfg.txt deleted file mode 100644 index 596eaff16c..0000000000 --- a/src/groups/mqb/mqbcfg/doc/mqbcfg.txt +++ /dev/null @@ -1,28 +0,0 @@ - mqbcfg.txt - -@PURPOSE: Provide broker configuration schema and message component. - -@MNEMONIC: BlazingMQ Broker Config (mqbcfg) - -@DESCRIPTION: This package provides the schema of the configuration used by the -broker, as well as the generated corresponding messages component. - - -/Hierarchical Synopsis -/--------------------- - The 'mqbcfg' package currently has 3 components having 2 levels of physical - dependency. The list below shows the hierarchical ordering of the components. -.. - 1. mqbcfg_messages - 2. mqbcfg_brokerconfig - 2. mqbcfg_tcpinterfaceconfigvalidator -.. - -/Component Synopsis -/------------------ -: 'mqbcfg_messages': -: BMQBroker generated configuration messages. -: 'mqbcfg_brokerconfig' -: Provide global access to broker configuration. -: 'mqbcfg_tcpinterfaceconfigvalidator' -: Provide validation logic for `appConfig/networkInterfaces/tcpInterface/listeners` in the broker configuration. diff --git a/src/groups/mqb/mqbcfg/mqbcfg_brokerconfig.h b/src/groups/mqb/mqbcfg/mqbcfg_brokerconfig.h index 6c3e88fbbc..502685795f 100644 --- a/src/groups/mqb/mqbcfg/mqbcfg_brokerconfig.h +++ b/src/groups/mqb/mqbcfg/mqbcfg_brokerconfig.h @@ -17,14 +17,13 @@ #ifndef INCLUDED_MQBCFG_BROKERCONFIG #define INCLUDED_MQBCFG_BROKERCONFIG -//@PURPOSE: Provide global access to broker configuration. -// -//@CLASSES: -// mqbcfg::BrokerConfig: mechanism to set and get the broker configuration. -// -//@DESCRIPTION: This component defines a mechanism, 'mqbcfg::BrokerConfig', -// that provides a safe way of setting and getting a pointer to the global -// broker configuration. +/// @file mqbcfg_brokerconfig.h +/// +/// @brief Provide global access to broker configuration. +/// +/// This component defines a mechanism, @bbref{mqbcfg::BrokerConfig}, that +/// provides a safe way of setting and getting a pointer to the global broker +/// configuration. // BDE #include @@ -39,6 +38,7 @@ class AppConfig; // struct BrokerConfig // =================== +/// Mechanism to set and get the broker configuration. struct BrokerConfig { // NOT IMPLEMENTED BrokerConfig() BSLS_CPP11_DELETED; diff --git a/src/groups/mqb/mqbcfg/mqbcfg_tcpinterfaceconfigvalidator.h b/src/groups/mqb/mqbcfg/mqbcfg_tcpinterfaceconfigvalidator.h index c3f7905013..3c41a14877 100644 --- a/src/groups/mqb/mqbcfg/mqbcfg_tcpinterfaceconfigvalidator.h +++ b/src/groups/mqb/mqbcfg/mqbcfg_tcpinterfaceconfigvalidator.h @@ -24,21 +24,17 @@ BSLS_IDENT_PRAGMA_ONCE #include -/// PURPOSE: This component provdies a class to validate TcpInterfaceConfig -/// settings in the broker config. +/// @file mqbcfg_tcpinterfaceconfigvalidator.h /// -/// CLASSES: -/// mqbcfg::TcpInterfaceConfigValidator: A predicate object that validates the -/// TCP interfaces in the broker config -/// -/// DESCRIPTION: +/// @brief This component provdies a class to validate `TcpInterfaceConfig` +/// settings in the broker config. namespace BloombergLP { namespace mqbcfg { -/// @brief This class is a functor that validates the -/// `appConfig/networkInterfaces/tcpInterface/listeners` property of the broker -/// config. +/// This class is a predicate object that validates the +/// `appConfig`/`networkInterfaces`/`tcpInterface`/`listeners` property of the +/// broker config. class TcpInterfaceConfigValidator { private: // PRIVATE STATIC FUNCTIONS @@ -50,6 +46,7 @@ class TcpInterfaceConfigValidator { public: // TYPES + /// Codes to indicate the reason for a validation failure. enum ErrorCode { /// Indicates a config is valid. Guaranteed to equal zero. @@ -64,7 +61,7 @@ class TcpInterfaceConfigValidator { // ACCESSORS - /// @brief Validate the TCP interface configuration. + /// Validate the TCP interface configuration. /// /// The TCP interface configuration is invalid unless: /// 1. The names of each network interface is unique