Improve documentation: sort sources into doxygen modules

analytics/AnalyticsManager.h

@@ -24,6 +24,12 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //================================================================================
 
+/**
+ * @defgroup analytics Analytics Framework
+ *
+ * @brief Framework for data analytics at various points within DCDB.
+ */
+
 #ifndef PROJECT_ANALYTICSMANAGER_H
 #define PROJECT_ANALYTICSMANAGER_H
 
@@ -44,7 +50,11 @@
 
 using namespace std;
 
-// Struct of values required to load analyzer dynamic libraries.
+/**
+ * Struct of values required to load analyzer dynamic libraries.
+ *
+ * @ingroup analytics
+ */
 typedef struct {
     std::string id;
     void*	DL;
@@ -56,9 +66,12 @@ typedef struct {
 typedef std::vector<an_dl_t> an_pluginVector_t;
 
 /**
- * Management class for the entire data analytics framework
+ * @brief Management class for the entire data analytics framework
+ *
+ * @details Allows to load, configure, start and generally manage plugins
+ *          developed with the data analytics framework.
  *
- * Allows to load, configure, start and generally manage plugins developed with the data analytics framework.
+ * @ingroup analytics
  */
 class AnalyticsManager {
 

analytics/analyzers/aggregator/AggregatorAnalyzer.h

@@ -32,6 +32,11 @@
 #include <math.h>
 #include <algorithm>
 
+/**
+ * @brief Aggregator analyzer plugin.
+ *
+ * @ingroup aggregator
+ */
 class AggregatorAnalyzer : virtual public AnalyzerTemplate<AggregatorSensorBase> {
 
 public:

analytics/analyzers/aggregator/AggregatorConfigurator.h

@@ -30,6 +30,11 @@
 #include "../../includes/AnalyzerConfiguratorTemplate.h"
 #include "AggregatorAnalyzer.h"
 
+/**
+ * @brief Configurator for the aggregator plugin.
+ *
+ * @ingroup aggregator
+ */
 class AggregatorConfigurator : virtual public AnalyzerConfiguratorTemplate<AggregatorAnalyzer, AggregatorSensorBase> {
 
 public:

analytics/analyzers/aggregator/AggregatorSensorBase.h

@@ -24,11 +24,23 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //================================================================================
 
+/**
+ * @defgroup aggregator Aggregator analyzer plugin.
+ * @ingroup analyzer
+ *
+ * @brief Aggregator analyzer plugin.
+ */
+
 #ifndef PROJECT_AGGREGATORSENSORBASE_H
 #define PROJECT_AGGREGATORSENSORBASE_H
 
 #include "sensorbase.h"
 
+/**
+ * @brief Sensor base for aggregator plugin
+ *
+ * @ingroup aggregator
+ */
 class AggregatorSensorBase : public SensorBase {
 
 public:

analytics/analyzers/aggregator/JobAggregatorAnalyzer.h

@@ -30,6 +30,11 @@
 #include "AggregatorAnalyzer.h"
 #include "../../includes/JobAnalyzerTemplate.h"
 
+/**
+ * @brief Aggregator for job data.
+ *
+ * @ingroup aggregator
+ */
 class JobAggregatorAnalyzer : public AggregatorAnalyzer, public JobAnalyzerTemplate<AggregatorSensorBase> {
 public:
 

analytics/analyzers/aggregator/JobAggregatorConfigurator.h

@@ -30,6 +30,11 @@
 #include "JobAggregatorAnalyzer.h"
 #include "../../includes/JobAnalyzerConfiguratorTemplate.h"
 
+/**
+ * @brief Configurator for job aggregator plugin.
+ *
+ * @ingroup aggregator
+ */
 class JobAggregatorConfigurator : public JobAnalyzerConfiguratorTemplate<JobAggregatorAnalyzer, AggregatorSensorBase> {
 
 public:

analytics/includes/AnalyzerConfiguratorInterface.h

@@ -35,11 +35,14 @@
 #include "globalconfiguration.h"
 
 /**
- * Interface to configurators for data analyzer plugins
+ * @brief Interface to configurators for data analyzer plugins
  *
- * This interface is the one exposed outside of the .dll library containing a plugin. Classes implementing this
- * interface must perform configuration and instantiation of Analyzers objects, which are made accessible externally.
+ * @details This interface is the one exposed outside of the .dll library
+ *          containing a plugin. Classes implementing this interface must
+ *          perform configuration and instantiation of Analyzers objects, which
+ *          are made accessible externally.
  *
+ * @ingroup analyzer
  */
 class AnalyzerConfiguratorInterface {
 

analytics/includes/AnalyzerConfiguratorTemplate.h

@@ -45,10 +45,12 @@
 #define CFG_VAL	boost::property_tree::iptree&
 
 /**
- * Template that implements a standard AnalyzerConfiguratorInterface.
+ * @brief Template that implements a standard AnalyzerConfiguratorInterface.
  *
- * Users should employ this template whenever possible, and create their own configurators only when strictly
- * necessary.
+ * @details Users should employ this template whenever possible, and create
+ *          their own configurators only when strictly necessary.
+ *
+ * @ingroup analyzer
  */
 template <class Analyzer, class SBase = SensorBase>
 class AnalyzerConfiguratorTemplate : public AnalyzerConfiguratorInterface {

analytics/includes/AnalyzerInterface.h

@@ -24,6 +24,12 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //================================================================================
 
+/**
+ * @defgroup analyzer Analyzer Plugins
+ * @ingroup analytics
+ *
+ * @brief Analyzer for the analytics plugin.
+ */
 #ifndef PROJECT_ANALYZERINTERFACE_H
 #define PROJECT_ANALYZERINTERFACE_H
 
@@ -46,14 +52,19 @@ typedef struct {
 } restResponse_t;
 
 /**
- * Interface to data analyzers
+ * @brief Interface to data analyzers
+ *
+ * @details This interface supplies methods to instantiate, start and retrieve
+ *          data from analyzers, which are "modules" that* implement data
+ *          analytics models and are loaded by DCDB data analytics plugins. For
+ *          it to be used in the DCDB data analytics framework, the analyzer
+ *          must comply to this interface.
  *
- * This interface supplies methods to instantiate, start and retrieve data from analyzers, which are "modules" that
- * implement data analytics models and are loaded by DCDB data analytics plugins. For it to be used in the DCDB
- * data analytics framework, the analyzer must comply to this interface.
+ *          An analyzer acts on "units", which are logical entities represented
+ *          by certain inputs and outputs. An unit can be, for example, a node,
+ *          a CPU or a rack in a HPC system.
  *
- * An analyzer acts on "units", which are logical entities represented by certain inputs and outputs. An unit can be,
- * for example, a node, a CPU or a rack in a HPC system.
+ * @ingroup analyzer
  */
 class AnalyzerInterface {
 public:

analytics/includes/AnalyzerTemplate.h

@@ -40,11 +40,15 @@
 using namespace std;
 
 /**
- * Template that implements features needed by Analyzers and complying to AnalyzerInterface.
+ * @brief Template that implements features needed by Analyzers and complying
+ *        to AnalyzerInterface.
  *
- * The template accepts any class derived from SensorBase, allowing users to add their own attributes to input and output
- * sensors. This template also employs UnitTemplates, which are instantiated according to the input sensor type.
+ * @details The template accepts any class derived from SensorBase, allowing
+ *          users to add their own attributes to input and output sensors. This
+ *          template also employs UnitTemplates, which are instantiated
+ *          according to the input sensor type.
  *
+ * @ingroup analyzer
  */
 template <typename S>
 class AnalyzerTemplate : public AnalyzerInterface {

analytics/includes/JobAnalyzerConfiguratorTemplate.h

@@ -31,10 +31,13 @@
 #include "JobAnalyzerTemplate.h"
 
 /**
- * Template that implements a configurator for Job analyzer plugins.
+ * @brief Template that implements a configurator for Job analyzer plugins.
  *
- * This template expands the standard AnalyzerConfiguratorTemplate, with very few changes to accomodate the different
- * design of job analyzers.
+ * @details This template expands the standard AnalyzerConfiguratorTemplate,
+ *          with very few changes to accomodate the different design of job
+ *          analyzers.
+ *
+ * @ingroup analyzer
  */
 template <class Analyzer, class SBase = SensorBase>
 class JobAnalyzerConfiguratorTemplate : virtual public AnalyzerConfiguratorTemplate<Analyzer, SBase> {

analytics/includes/JobAnalyzerTemplate.h

@@ -30,10 +30,13 @@
 #include "AnalyzerTemplate.h"
 
 /**
- * Template that implements features needed by Job Analyzers and complying to AnalyzerInterface.
+ * @brief Template that implements features needed by Job Analyzers and
+ *        complying to AnalyzerInterface.
  *
- * This template is derived from AnalyzerTemplate, and is adjusted to simplify job-related computations.
+ * @details This template is derived from AnalyzerTemplate, and is adjusted to
+ *          simplify job-related computations.
  *
+ * @ingroup analyzer
  */
 template <typename S>
 class JobAnalyzerTemplate : virtual public AnalyzerTemplate<S> {

analytics/includes/QueryEngine.h

@@ -47,11 +47,14 @@ typedef vector<reading_t>* (*QueryEngineCallback)(const string&, const uint64_t,
 typedef vector<qeJobData>* (*QueryEngineJobCallback)(const uint32_t, const uint64_t, const uint64_t, vector<qeJobData>*, const bool, const bool);
 
 /**
- * Class that grants query access to local and remote sensors
+ * @brief Class that grants query access to local and remote sensors
  *
- * This class provides an abstraction layer to where the data analytics framework is executed: access interface to
- * sensor data is the same on dcdbpusher and collectagent.
- * This class is implemented according to the Singleton design pattern.
+ * @details This class provides an abstraction layer to where the data analytics
+ *          framework is executed: access interface to sensor data is the same
+ *          on dcdbpusher and collectagent.
+ *          This class is implemented according to the Singleton design pattern.
+ *
+ * @ingroup analytics
  */
 class QueryEngine {
 

analytics/includes/UnitGenerator.h

@@ -37,11 +37,13 @@
 using namespace std;
 
 /**
- * Helper template to generate Analyzer Units
+ * @brief Helper template to generate Analyzer Units
  *
- * This template decouples the unit-related configuration logic from AnalyerConfiguratorTemplate, so that users can
- * override such template without losing access to the unit system.
+ * @details This template decouples the unit-related configuration logic from
+ *          AnalyerConfiguratorTemplate, so that users can override such
+ *          template without losing access to the unit system.
  *
+ * @ingroup analyzer
  */
 template <class SBase=SensorBase>
 class UnitGenerator {

analytics/includes/UnitInterface.h

@@ -34,9 +34,12 @@
 typedef enum inputMode_t { SELECTIVE = 1, ALL = 2, ALL_RECURSIVE = 3 } inputMode_t;
 
 /**
- * Interface for Units used by Analyzers to perform data analytics.
+ * @brief Interface for Units used by Analyzers to perform data analytics.
  *
- * An Unit represents a logical entity on which an Analyzer operates, and is identified by its name, inputs and outputs.
+ * @details An Unit represents a logical entity on which an Analyzer operates,
+ *          and is identified by its name, inputs and outputs.
+ *
+ * @ingroup analyzer
  */
 class UnitInterface {
 

analytics/includes/UnitTemplate.h

@@ -30,11 +30,14 @@
 #include "UnitInterface.h"
 
 /**
- * Template that implements features needed to use Units in Analyzers.
+ * @brief Template that implements features needed to use Units in Analyzers.
  *
- * The template accepts any class derived from SensorBase, allowing users to add their own attributes to input and output
- * sensors. Users should employ this template in their plugins if possible, and change it only if absolutely necessary.
+ * @details The template accepts any class derived from SensorBase, allowing
+ *          users to add their own attributes to input and output sensors. Users
+ *          should employ this template in their plugins if possible, and change
+ *          it only if absolutely necessary.
  *
+ * @ingroup analyzer
  */
 template <class S=SensorBase>
 class UnitTemplate : public UnitInterface {

collectagent/CARestAPI.h

@@ -32,6 +32,11 @@
 #include "analyticscontroller.h"
 #include "mqttchecker.h"
 
+/**
+ * @brief Class providing a RESTful API to collect agent via network (HTTPs only).
+ *
+ * @ingroup ca
+ */
 class CARestAPI : public RESTHttpsServer {
 public:
     CARestAPI(serverSettings_t settings,

collectagent/analyticscontroller.h

@@ -42,12 +42,16 @@
 using namespace std;
 
 /**
-* Class implementing a wrapper around the AnalyticsManager
+* @brief Class implementing a wrapper around the AnalyticsManager
 * 
-* This class provides a wrapper around many features required for the instantiation of the Analytics Manager - namely
-* the instantiation of a SensorNavigator, the creation of a dedicated thread pool, and the insertion of generated
-* sensor values into the Cassandra datastore. Most of these features were already available in DCDBPusher to handle
-* regular sensors, but they had to be ported over to the CollectAgent.
+* @details This class provides a wrapper around many features required for the
+*          instantiation of the Analytics Manager - namely the instantiation of
+*          a SensorNavigator, the creation of a dedicated thread pool, and the
+*          insertion of generated sensor values into the Cassandra datastore.
+*          Most of these features were already available in DCDBPusher to handle
+*          regular sensors, but they had to be ported over to the CollectAgent.
+*
+* @ingroup ca
 */
 class AnalyticsController {
 

collectagent/collectagent.cpp

@@ -24,6 +24,25 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //================================================================================
 
+/**
+ * @defgroup ca Collect Agent
+ *
+ * @brief MQTT message broker in between pusher and storage backend.
+ *
+ * @details Collect Agent is a intermediary between one or multiple Pusher
+ *          instances and one storage backend. It runs a reduced custom MQTT
+ *          message server. Collect Agent receives data from Pusher
+ *          via MQTT messages and stores them in the storage via libdcdb.
+ */
+
+/**
+ * @file collectagent.cpp
+ *
+ * @brief Main function for the DCDB Collect Agent.
+ *
+ * @ingroup ca
+ */
+
 #include <cstdlib>
 #include <signal.h>
 #include <unistd.h>

collectagent/configuration.h

@@ -42,7 +42,11 @@
 
 using namespace std;
 
-// Wrapper class for Cassandra-specific settings
+/**
+ * Wrapper class for Cassandra-specific settings
+ *
+ * @ingroup ca
+ */
 class cassandra_t {
 public:
     cassandra_t() {}
@@ -58,7 +62,9 @@ public:
 };
 
 /**
- * Class responsible of reading the collectagent global configuration.
+ * @brief Class responsible for reading collect agent specific configuration.
+ *
+ * @ingroup ca
  */
 class Configuration : public GlobalConfiguration {
 

collectagent/sensorcache.h

@@ -36,6 +36,11 @@ using namespace DCDB;
 
 typedef std::map<SensorId, CacheEntry> sensorCache_t;
 
+/**
+ * @brief
+ *
+ * @ingroup ca
+ */
 class SensorCache {
 public:
 	SensorCache(uint64_t maxHistory=60000000000);
@@ -90,7 +95,7 @@ public:
 	/**
 	* @brief        Removes all obsolete entries from the cache
 	*
-	*				All entries in the cache whose latest sensor reading is older than "now" - t nanoseconds are
+	* @details      entries in the cache whose latest sensor reading is older than "now" - t nanoseconds are
 	*				removed.
 	*
 	* @param t		The threshold in nanoseconds for entries that must be removed

collectagent/simplemqttserver.h

@@ -24,6 +24,13 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //================================================================================
 
+/**
+ * @defgroup mqttserver Simple MQTT server
+ * @ingroup ca
+ *
+ * @brief Simplified custom MQTT message server.
+ */
+
 #include <stdint.h>
 #include <pthread.h>
 #include <sys/types.h>
@@ -49,12 +56,19 @@
 
 //#define SimpleMQTTVerbose 100
 
+/**
+ * Define the MQTT connection queue length
+ *
+ * @ingroup mqttserver
+ */
 #ifndef SimpleMQTTConnectionsQueueLength
 #define SimpleMQTTConnectionsQueueLength 4
 #endif
 
 /*
  * Define the maximum backlog size for listen().
+ *
+ * @ingroup mqttserver
  */
 #ifndef SimpleMQTTBacklog
 #define SimpleMQTTMaxBacklog 100
@@ -62,6 +76,8 @@
 
 /*
  * Define the standard wait time for poll() calls.
+ *
+ * @ingroup mqttserver
  */
 #ifndef SimpleMQTTPollTimeout
 #define SimpleMQTTPollTimeout 100
@@ -69,6 +85,8 @@
 
 /*
  * Define the standard size for the buffer used in read() calls.
+ *
+ * @ingroup mqttserver
  */
 #ifndef SimpleMQTTReadBufferSize
 #define SimpleMQTTReadBufferSize 1024
@@ -76,6 +94,7 @@
 
 /*
  * Enable verbose output of the MQTT server.
+ *
  */
 //#define SimpleMQTTVerbose
 
@@ -83,11 +102,11 @@
 typedef int (*SimpleMQTTMessageCallback)(SimpleMQTTMessage*);
 #include "simplemqttserverthread.h"
 
-/*
- * SimpleMQTTServer Class Definition
- *
- * Usage:
+/**
+ * @brief %SimpleMQTTServer Class Definition
  *
+ * @details Usage:
+ * @code
  * // Create a simple MQTT server instance listening on localhost, port 1883 (default):
  * SimpleMQTTServer s();
  *
@@ -96,7 +115,9 @@ typedef int (*SimpleMQTTMessageCallback)(SimpleMQTTMessage*);
  *
  * s.start();    // Start server
  * s.stop();     // Stop server
+ * @endcode
  *
+ * @ingroup mqttserver
  */
 class SimpleMQTTServer
 {

collectagent/simplemqttservermessage.h

@@ -24,6 +24,13 @@
 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 //================================================================================
 
+/**
+ * @file simplemqttservermessage.h
+ *
+ * @brief Class for receiving a simple MQTT message.
+ *
+ * @ingroup mqttserver
+ */
 #ifndef SIMPLEMQTTMESSAGE_H_
 #define SIMPLEMQTTMESSAGE_H_
 

collectagent/simplemqttserverthread.h

@@ -30,6 +30,11 @@
 #include "logging.h"
 #include <vector>
 
+/**
+ * @brief Simple MQTT server thread.
+ *
+ * @ingroup mqttserver
+ */
 class SimpleMQTTServerThread
 {
 protected:
@@ -50,6 +55,11 @@ public:
   ~SimpleMQTTServerThread();
 };
 
+/**
+ * @brief Simple MQTT server message thread.
+ *
+ * @ingroup mqttserver
+ */
 class SimpleMQTTServerMessageThread : SimpleMQTTServerThread
 {
 protected:
@@ -77,6 +87,11 @@ public:
   ~SimpleMQTTServerMessageThread();
 };
 
+/**
+ * @brief Simple MQTT server accept thread.
+ *
+ * @ingroup mqttserver
+ */
 class SimpleMQTTServerAcceptThread : SimpleMQTTServerThread
 {
 protected:

common/include/RESTHttpsServer.h

@@ -25,50 +25,14 @@
 //================================================================================
 
 
+
 /**
- * General RESTful API https server leveraging Boost::Beast to provide common
- * functionality for different REST API servers. Intended as parent class for
- * concrete REST API implementations.
- *
- * Code partially copied from the boost beast synchronous https server example:
- * https://www.boost.org/doc/libs/develop/libs/beast/example/http/server/sync-ssl/http_server_sync_ssl.cpp
- */
-/**
- * Example/Howto set up an endpoint in a derived class:
- *
- * 1. Implement a handler function that obeys the required handler signature:
- *    <code>
- *    void handle_get_example(http::response<http::string_body>& res, \
- *                            queries_t& queries) {
- *        //Implement here the logic for the endpoint taking into account the
- *        //queries as required.
- *        //TODO
- *        std::string result;
- *        if(queries.at("number") == "true") {
- *            result = "a number string\n";
- *        } else {
- *            result = "a string string\n";
- *        }
- *        //Set the response accordingly at the end. Result must have string
- *        //format!
- *        res.body() = res;
- *        res.result(http::status::ok);
- *    }
- *    </code>
- *
- * 2. Add a new endpoint by specifying its path, supported REST method and
- *    corresponding handler function:
- *    <code>
- *    addEndpoint("/endpoints/example", {http::verb::get, \
- *                                       std::bind(handle_get_example, \
- *                                                 std::placeholders::_1, \
- *                                                 std::placeholders::_2)});
- *    </code>
+ * @defgroup server Https Server
+ * @ingroup common
  *
- * 3. Document your endpoints (expected queries etc.) somewhere.
- *
- * 4. Enjoy.
+ * @brief Definitions for a common HttpsServer base class.
  */
+
 #ifndef COMMON_INCLUDE_RESTHTTPSSERVER_H_
 #define COMMON_INCLUDE_RESTHTTPSSERVER_H_
 
@@ -91,7 +55,9 @@
 /******************************************************************************/
 
 /**
- * Enum to distinguish different permissions
+ * @brief Enum to distinguish different permissions
+ *
+ * @ingroup server
  */
 enum permission {
     GET     = 0, /**< Permission to make GET requests */
@@ -105,6 +71,9 @@ namespace http = boost::beast::http;
 namespace ssl  = boost::asio::ssl;
 using     tcp  = boost::asio::ip::tcp;
 
+/**
+ * TODO how to document using directives to get them recognized by doxygen?
+ */
 using userAttributes_t = std::pair<std::string, std::bitset<NUM_PERMISSIONS>>;
 using userBase_t       = std::unordered_map<std::string, userAttributes_t>;
 
@@ -115,6 +84,8 @@ using apiEndpoint_t        = std::pair<http::verb, apiEndpointHandler_t>;
 using apiEndpoints_t       = std::unordered_map<std::string, apiEndpoint_t>;
 
 /**
+ * @ingroup server
+ *
  * @brief Utility method for RestAPI implementations: retrieve the value
  *        for a key from queries.
  *
@@ -134,6 +105,8 @@ inline std::string getQuery(const std::string& key, queries_t& queries) {
 }
 
 /**
+ * @ingroup server
+ *
  * @brief Utility method for RestAPI implementations: test if a plugin query
  *        was given. Prepares the response accordingly to continue execution on
  *        success or immediately return on failure.
@@ -157,6 +130,47 @@ inline bool hasPlugin(const std::string& plugin, http::response<http::string_bod