From d0389a179aaed94c236aacc29f2f57f1bf08da85 Mon Sep 17 00:00:00 2001
From: Cameron Goddard <camerongoddard@me.com>
Date: Sun, 14 Apr 2024 00:07:02 -0400
Subject: [PATCH] add docstrings to header files

---
 src/ControlTasks/RadioControlTask.hpp | 62 +++++++++++++++++++++++++--
 src/Monitors/GPSMonitor.hpp           | 37 +++++++++++++++-
 src/Monitors/IMUMonitor.hpp           | 22 ++++++++++
 src/Monitors/TempMonitor.hpp          | 11 +++++
 4 files changed, 127 insertions(+), 5 deletions(-)

diff --git a/src/ControlTasks/RadioControlTask.hpp b/src/ControlTasks/RadioControlTask.hpp
index 07e3146..6f9ed03 100644
--- a/src/ControlTasks/RadioControlTask.hpp
+++ b/src/ControlTasks/RadioControlTask.hpp
@@ -8,21 +8,77 @@ class RadioControlTask
 {
 public:
     RadioControlTask();
+
+    /**
+     * @brief Executes the actions of the current radio state, as defined in the state machine
+     */
     void execute();
 
 private:
-    RFM96 radio = new Module(constants::radio::radio_cs_pin, constants::radio::radio_di0_pin,
-                             constants::radio::radio_rst_pin, constants::radio::radio_busy_pin);
-    int16_t code;
+    /**
+     * @brief Sets up the radio module
+     */
     void init();
+
+    /**
+     * Resets the transmit window start time and picks a new slot
+     */
     void downlinkSettings();
+
+    /**
+     * @brief Wrapper around RadioLib's transmit() to provide metadata (TODO: Redundant?)
+     */
     bool transmit(uint8_t *packet, uint8_t size);
+
+    /**
+     * @brief Attempts to receive a 3 byte command (TODO: Redundant?)
+     */
     bool receive();
+
+    /**
+     * @brief Transmits either a normal report packet or a callsign packet
+     *
+     * @return True on successful transmit, false otherwise
+     */
     bool executeDownlink();
+
+    /**
+     * @brief Constructs and downlinks a normal report
+     *
+     * @return True on successful transmit, false otherwise
+     */
     bool normalReportDownlink();
+
+    /**
+     * @brief Maps a floating point value to a bounded 8 bit integer
+     *
+     * @param value The value to map
+     * @param min The minimum value of the mapped integer
+     * @param max The maximum value of the mapped integer
+     * @return The mapped 8 bit integer
+     */
     uint8_t map_range(float value, int min, int max);
+
+    /**
+     * @brief Parses and processes uplinked commands
+     */
     void processUplink();
+
+    /**
+     * @brief The radio module instance
+     */
+    RFM96 radio = new Module(constants::radio::radio_cs_pin, constants::radio::radio_di0_pin,
+                             constants::radio::radio_rst_pin, constants::radio::radio_busy_pin);
+
+    /**
+     * @brief The received command
+     */
     uint8_t *received;
+
+    /**
+     * @brief RadioLib status code
+     */
+    int16_t code;
 };
 
 #endif
diff --git a/src/Monitors/GPSMonitor.hpp b/src/Monitors/GPSMonitor.hpp
index f3e7fd2..8870d92 100644
--- a/src/Monitors/GPSMonitor.hpp
+++ b/src/Monitors/GPSMonitor.hpp
@@ -9,16 +9,49 @@ class GPSMonitor
 {
 public:
     GPSMonitor();
-    void init();
+
+    /**
+     * @brief Reads in a character from the software serial
+     */
     void execute();
-    bool check_GPGGA();
 
 private:
+    /**
+     * @brief Software serial instance to communicate with the GPS receiver
+     */
     SoftwareSerial ss = SoftwareSerial(constants::gps::rx_pin, constants::gps::tx_pin);
+
+    /**
+     * Begins the software serial instance and configures the GPS receiver
+     */
+    void init();
+
+    /**
+     * @brief Appends another character to a GPS message under construction
+     *
+     * @param c The character to add
+     */
     bool encode(char c);
 
+    /**
+     * @brief Checks to see if the first 5 characters match those of the expected
+     * full GPS message
+     */
+    bool check_GPGGA();
+
+    /**
+     * @brief Buffer that holds the current constructed GPS message
+     */
     char term_buffer[constants::gps::buffer_size];
+
+    /**
+     * @brief The number of characters in the current term
+     */
     uint8_t char_count = 0;
+
+    /**
+     * @brief The number of terms in the GPS message
+     */
     uint8_t term_count = 0;
 
     //     const char *gpsStream =
diff --git a/src/Monitors/IMUMonitor.hpp b/src/Monitors/IMUMonitor.hpp
index 958b190..e6d3b1f 100644
--- a/src/Monitors/IMUMonitor.hpp
+++ b/src/Monitors/IMUMonitor.hpp
@@ -10,14 +10,36 @@ class IMUMonitor
 {
 public:
     IMUMonitor();
+
+    /**
+     * @brief Initializes the IMU once and reads IMU data every time after
+     */
     void execute();
 
 private:
+    /**
+     * @brief Initializes the IMU
+     */
     void init();
+
+    /**
+     * @brief Transitions to a normal state (TODO: Unnecessary?)
+     */
     void transition_to_normal();
+
+    /**
+     * @brief Transitions to a abnormal state (TODO: Unnecessary?)
+     */
     void transition_to_abnormal_init();
+
+    /**
+     * @brief Reads IMU data
+     */
     void capture_imu_values();
 
+    /**
+     * @brief The current state of the sensor
+     */
     sensor_mode_type mode;
 };
 
diff --git a/src/Monitors/TempMonitor.hpp b/src/Monitors/TempMonitor.hpp
index 1d3c20b..fd321a1 100644
--- a/src/Monitors/TempMonitor.hpp
+++ b/src/Monitors/TempMonitor.hpp
@@ -8,10 +8,21 @@ class TempMonitor
 {
 public:
     TempMonitor();
+
+    /**
+     * @brief Reads data from the temperature sensor
+     */
     void execute();
 
 private:
+    /**
+     * @brief Whether or not the sensor has been initialized (TODO: Unnecessary)
+     */
     bool initialized = false;
+
+    /**
+     * @brief Buffer to store data read from the sensor
+     */
     unsigned int data[2];
 };