From 3def5d8d855d94ece6b514f57cf6b532dac960cd Mon Sep 17 00:00:00 2001
From: Robin Mueller <muellerr@irs.uni-stuttgart.de>
Date: Wed, 11 Dec 2024 13:01:48 +0100
Subject: [PATCH] add docs

---
 .../devicehandlers/FreshDeviceHandlerBase.h   | 74 ++++++++++++++++++-
 1 file changed, 71 insertions(+), 3 deletions(-)

diff --git a/src/fsfw/devicehandlers/FreshDeviceHandlerBase.h b/src/fsfw/devicehandlers/FreshDeviceHandlerBase.h
index f69113ff..643ffd9f 100644
--- a/src/fsfw/devicehandlers/FreshDeviceHandlerBase.h
+++ b/src/fsfw/devicehandlers/FreshDeviceHandlerBase.h
@@ -25,6 +25,33 @@ struct DhbConfig {
   uint32_t msgQueueDepth = 10;
 };
 
+/**
+ * @brief
+ * This is a base class which can be used for handler classes which drive physical devices.
+ *
+ * @details
+ * This class performs some boilerplate tasks to make it compatible to the FSFW ecosystem.
+ * For example, it adds all required interfaces and helpers which are required for the majority
+ * of physical devices:
+ *
+ * - SystemObject to become  globally addressable
+ * - HasModesIF and the ModeHelper: Expose modes. It is expected that most device handlers
+ *   use the default device handler modes OFF, ON and NORMAL at the very least.
+ * - HasHealthIF, HealthHelper and a FDIR object: Physical devices can break down or require
+ *   power cycling as the most common FDIR reaction. The FDHB implements the necessary interface
+ *   and is also composed of a FDIR object which can set the health state to FAULTY or
+ *   NEEDS_RECOVERY to cause FDIR reactions.
+ * - ModeTreeChildIF: Many device handlers are part of a mode tree.
+ * - HasActionsIF and the ActionHelper: Most device handlers expose executable commands, for example
+ *   to re-configure the physical device or to poll data from the physical device.
+ * - ReceivesParameterMessagesIF and the ParameterHelper: Most device handlers have tweakable
+ *   parameters.
+ *
+ * This class is used to extending it in a concrete device handler class and then implementing
+ * all abstract methods. The abstract methods provide adaption points for users which were
+ * deemed sufficient for most use-cases. The behaviour of the base-class can also be further
+ * configured by implementing other virtual functions.
+ */
 class FreshDeviceHandlerBase : public SystemObject,
                                public DeviceHandlerIF,
                                public HasModesIF,
@@ -40,7 +67,20 @@ class FreshDeviceHandlerBase : public SystemObject,
   ~FreshDeviceHandlerBase() override;
 
   /**
+   * @brief
    * Periodic helper executed function, implemented by child class.
+   *
+   * @details
+   * This will be called by the default performOperation call. This is the main adaption point
+   * for the actual device handling logic. It is expected that the following common tasks are
+   * performed in this method:
+   *
+   * 1. Performing periodic polling of the physical device in NORMAL mode. This is usually required
+   *    to poll housekeeping data from the device periodically.
+   * 2. Handle on-going mode transitions if the mode transitions can only be handled asynchronously.
+   *    This might also involve communication with the phsyical device and power switch
+   *    handling/polling for transition to OFF or ON/NORMAL.
+   * 3. Perform other periodic tasks which always need to be done irrespective of mode.
    */
   virtual void performDeviceOperation(uint8_t opCode) = 0;
 
@@ -120,15 +160,43 @@ class FreshDeviceHandlerBase : public SystemObject,
   ReturnValue_t initializeLocalDataPool(localpool::DataPool& localDataPoolMap,
                                         LocalDataPoolManager& poolManager) override = 0;
 
-  // Mode abstract functions
+  /**
+   * HasModesIF implementation to check the validity of a mode command.
+   * @param mode
+   * @param submode
+   * @param msToReachTheMode
+   * @return
+   */
   ReturnValue_t checkModeCommand(Mode_t mode, Submode_t submode,
                                  uint32_t* msToReachTheMode) override = 0;
   // Health Overrides.
   ReturnValue_t setHealth(HealthState health) override;
-  // Action override. Forward to user.
+
+  /**
+   * This is called when an ActionMessage to execute an action is received.
+   * @param actionId
+   * @param commandedBy
+   * @param data
+   * @param size
+   * @return
+   */
   ReturnValue_t executeAction(ActionId_t actionId, MessageQueueId_t commandedBy,
                               const uint8_t* data, size_t size) override = 0;
-  // Executable overrides.
+  /**
+   * This is the default periodic operation handler.
+   *
+   * Currently, it performs the following tasks:
+   *
+   *  1. Handle the message queue and all message types covered by the base class as specified
+   *     in the class documentation. It uses the composed helper classes for this.
+   *  2. Poll the FDIR instance to check for failures. The FDIR works by checking all events
+   *     received by the FDHB. An FDIR reaction sets the health state of the FDHB, which might
+   *     in turn trigger FDIR reactions.
+   *  3. Call the performDeviceOperation user hook.
+   *  4. Handle periodic housekeeping data generation.
+   * @param opCode
+   * @return
+   */
   virtual ReturnValue_t performOperation(uint8_t opCode) override;
   ReturnValue_t initializeAfterTaskCreation() override;
 
-- 
2.43.0