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 {