docs(reporters): Add documentation for reporters

Add documentation for reporters, related classes ReporterModel and ReporterAgent, and the associated calls in the schedulers

include/kami/agent.h

@@ -125,7 +125,7 @@ namespace kami {
      * implement the `step()` function, to execute a single time step for each
      * agent.
      *
-     * @see `StagedAgent`
+     * @see `ReporterAgent`, `StagedAgent`
      */
     class LIBKAMI_EXPORT Agent {
     private:

include/kami/model.h

@@ -40,6 +40,8 @@ namespace kami {
 
     /**
      * @brief An abstract for generic models
+     *
+     * @see `ReporterModel`
      */
     class LIBKAMI_EXPORT Model : public std::enable_shared_from_this<Model> {
 

include/kami/random.h

@@ -73,10 +73,27 @@ namespace kami {
          * @returns returns vector of agents successfully stepped
          */
         std::unique_ptr<std::vector<AgentID>>
-        step(std::shared_ptr<Model> model, std::unique_ptr<std::vector<AgentID>> agent_list) override;
+        step(
+                std::shared_ptr<Model> model,
+                std::unique_ptr<std::vector<AgentID>> agent_list
+        ) override;
 
+        /**
+         * @brief Execute a single time step for a `ReporterModel`
+         *
+         * @details This method will randomize the list of Agents provided
+         * then execute the `Agent::step()` method for every Agent listed.
+         *
+         * @param model a reference copy of the `ReporterModel`
+         * @param agent_list list of agents to execute the step
+         *
+         * @returns returns vector of agents successfully stepped
+         */
         std::unique_ptr<std::vector<AgentID>>
-        step(std::shared_ptr<ReporterModel> model, std::unique_ptr<std::vector<AgentID>> agent_list) override;
+        step(
+                std::shared_ptr<ReporterModel> model,
+                std::unique_ptr<std::vector<AgentID>> agent_list
+        ) override;
 
         /**
          * @brief Set the RNG

include/kami/reporter.h

@@ -45,7 +45,17 @@ namespace kami {
 
     class ReporterModel;
 
-    class LIBKAMI_EXPORT ReporterAgent : public Agent {
+    /**
+     * @brief A superclass for all reporting agents
+     *
+     * @details All reporting agents should subclass the `ReportingAgent` class. At a minimum,
+     * subclasses must implement the `step()` function, to execute a single time step for each
+     * agent.
+     *
+     * @see `Agent`, `StagedAgent`
+     */
+    class LIBKAMI_EXPORT ReporterAgent
+            : public Agent {
     public:
         /**
          * @brief Collect the current state of the agent
@@ -84,7 +94,13 @@ namespace kami {
         int _step_counter = 0;
     };
 
-    class LIBKAMI_EXPORT ReporterModel : public Model {
+    /**
+     * @brief An abstract for generic models with a reporting capability
+     *
+     * @see `Model`
+     */
+    class LIBKAMI_EXPORT ReporterModel
+            : public Model {
     public:
         /**
          * @brief Constructor
@@ -150,7 +166,12 @@ namespace kami {
         unsigned int _step_count{};
     };
 
-    class LIBKAMI_EXPORT Reporter : public std::enable_shared_from_this<Reporter> {
+    /**
+     * @brief A `Reporter` is a module that works with `ReporterAgent` and `ReporterModel`
+     * to collect information about the state of the model for later analysis
+     */
+    class LIBKAMI_EXPORT Reporter
+            : public std::enable_shared_from_this<Reporter> {
     public:
         /**
          * @brief Constructor

include/kami/scheduler.h

@@ -60,6 +60,18 @@ namespace kami {
          */
         virtual std::unique_ptr<std::vector<AgentID>> step(std::shared_ptr<Model> model) = 0;
 
+        /**
+         * @brief Execute a single time step for a `ReporterModel`
+         *
+         * @details This method will step through the list of Agents in the
+         * scheduler's internal queue and then execute the `Agent::step()`
+         * method for every Agent assigned to this scheduler in the order
+         * assigned.
+         *
+         * @param model a reference copy of the `ReporterModel`
+         *
+         * @returns returns vector of agents successfully stepped
+         */
         virtual std::unique_ptr<std::vector<AgentID>> step(std::shared_ptr<ReporterModel> model) = 0;
 
         /**
@@ -76,10 +88,29 @@ namespace kami {
          * @returns returns vector of agents successfully stepped
          */
         virtual std::unique_ptr<std::vector<AgentID>>
-        step(std::shared_ptr<Model> model, std::unique_ptr<std::vector<AgentID>> agent_list) = 0;
+        step(
+                std::shared_ptr<Model> model,
+                std::unique_ptr<std::vector<AgentID>> agent_list
+        ) = 0;
 
+        /**
+         * @brief Execute a single time step for a `ReporterModel`
+         *
+         * @details This method will step through the list of Agents in the
+         * scheduler's internal queue and then execute the `Agent::step()`
+         * method for every Agent assigned to this scheduler in the order
+         * assigned.
+         *
+         * @param model a reference copy of the `ReporterModel`
+         * @param agent_list list of agents to execute the step
+         *
+         * @returns returns vector of agents successfully stepped
+         */
         virtual std::unique_ptr<std::vector<AgentID>>
-        step(std::shared_ptr<ReporterModel> model, std::unique_ptr<std::vector<AgentID>> agent_list) = 0;
+        step(
+                std::shared_ptr<ReporterModel> model,
+                std::unique_ptr<std::vector<AgentID>> agent_list
+        ) = 0;
 
     protected:
         /**

include/kami/sequential.h

@@ -63,6 +63,18 @@ namespace kami {
          */
         std::unique_ptr<std::vector<AgentID>> step(std::shared_ptr<Model> model) override;
 
+        /**
+         * @brief Execute a single time step for a `ReporterModel`
+         *
+         * @details This method will step through the list of Agents in the
+         * scheduler's internal queue and then execute the `Agent::step()`
+         * method for every Agent assigned to this scheduler in the order
+         * assigned.
+         *
+         * @param model a reference copy of the `ReporterModel`
+         *
+         * @returns returns vector of agents successfully stepped
+         */
         std::unique_ptr<std::vector<AgentID>> step(std::shared_ptr<ReporterModel> model) override;
 
         /**
@@ -79,10 +91,29 @@ namespace kami {
          * @returns returns vector of agents successfully stepped
          */
         std::unique_ptr<std::vector<AgentID>>
-        step(std::shared_ptr<Model> model, std::unique_ptr<std::vector<AgentID>> agent_list) override;
+        step(
+                std::shared_ptr<Model> model,
+                std::unique_ptr<std::vector<AgentID>> agent_list
+        ) override;
 
+        /**
+         * @brief Execute a single time step for a `ReporterModel`
+         *
+         * @details This method will step through the list of Agents in the
+         * scheduler's internal queue and then execute the `Agent::step()`
+         * method for every Agent assigned to this scheduler in the order
+         * assigned.
+         *
+         * @param model a reference copy of the `ReporterModel`
+         * @param agent_list list of agents to execute the step
+         *
+         * @returns returns vector of agents successfully stepped
+         */
         std::unique_ptr<std::vector<AgentID>>
-        step(std::shared_ptr<ReporterModel> model, std::unique_ptr<std::vector<AgentID>> agent_list) override;
+        step(
+                std::shared_ptr<ReporterModel> model,
+                std::unique_ptr<std::vector<AgentID>> agent_list
+        ) override;
     };
 
 }  // namespace kami