Doxy/Clang

Author: brentru

src/components/gps/hardware.cpp

@@ -56,8 +56,8 @@ void GPSHardware::I2cReadDiscard() {
 
 /*!
  * @brief Handles a GPSConfig message from the protobuf stream.
- * @param stream
- *        Pointer to a pb_istream_t object.
+ * @param gps_config
+ *        Pointer to a wippersnapper_gps_GPSConfig message.
  * @returns True if the message was handled successfully, False otherwise.
  */
 bool GPSHardware::Handle_GPSConfig(wippersnapper_gps_GPSConfig *gps_config) {

src/components/gps/hardware.h

@@ -36,26 +36,36 @@
 class Wippersnapper_V2; ///< Forward declaration
 class UARTHardware;     ///< Forward declaration
 
+/**
+ * @brief Type of interface used by GPS.
+ */
 enum GpsInterfaceType {
   GPS_IFACE_NONE,    ///< No interface/undefined
   GPS_IFACE_UART_HW, ///< UART hardware interface
   GPS_IFACE_UART_SW, ///< UART software interface
   GPS_IFACE_I2C      ///< I2C interface
-}; ///< Type of interface used by GPS
+};
 
+/**
+ * @brief Type of GPS driver used.
+ */
 enum GpsDriverType {
   GPS_DRV_NONE,        ///< No driver/undefined
   GPS_DRV_MTK,         ///< MediaTek GPS driver
   GPS_DRV_UBLOX,       ///< u-blox GPS driver
   GPS_DRV_GENERIC_NMEA ///< Generic NMEA GPS driver
-}; ///< Type of GPS driver used
+};
 
+/**
+ * @brief NMEA sentence ring buffer (FIFO).
+ */
 typedef struct {
-  char sentences[MAX_NMEA_SENTENCES][MAX_LEN_NMEA_SENTENCE];
-  int head;
-  int tail;
-  int maxlen;
-} nmea_buffer_t; ///< NMEA sentence ring buffer structure
+  char sentences[MAX_NMEA_SENTENCES]
+                [MAX_LEN_NMEA_SENTENCE]; ///< Array of NMEA sentences
+  int head;                              ///< Index of the head of the buffer
+  int tail;                              ///< Index of the tail of the buffer
+  int maxlen; ///< Maximum number of sentences the buffer can hold
+} nmea_buffer_t;
 
 /*!
     @brief  Low-level hardware interface for WipperSnapper's generic GPS
@@ -93,7 +103,6 @@ class GPSHardware {
   void ReadDiscardBuffer();
   void PollStoreSentences();
   bool ParseNMEASentence(char *sentence);
-  void HandleNmeaChar(char incoming);
   // Datetime getters
   uint8_t GetHour();
   uint8_t GetMinute();

src/components/gps/model.cpp

@@ -51,7 +51,7 @@ wippersnapper_gps_GPSConfig *GPSModel::GetGPSConfigMsg() {
 
 /*!
  * @brief Creates a new GPSEvent message and initializes it.
- * @NOTE: This function will clear an existing GPSEvent message. Only call when
+ * This function will clear an existing GPSEvent message. Only call when
  * you are creating a NEW gps event, not modifying an existing one.
  */
 void GPSModel::CreateGPSEvent() {
@@ -113,6 +113,21 @@ GPSModel::CreateGpsDatetime(uint8_t hour, uint8_t minute, uint8_t seconds,
   return datetime;
 }
 
+/*!
+ * @brief Adds an RMC response to the GPSEvent message.
+ * @param datetime A wippersnapper_gps_GPSDateTime message representing the
+ * date and time.
+ * @param fix_status The fix status (1 = valid, 0 = invalid).
+ * @param lat Latitude in decimal degrees.
+ * @param lat_dir Pointer to a string representing latitude direction ("N" or
+ * "S").
+ * @param lon Longitude in decimal degrees.
+ * @param lon_dir Pointer to a string representing longitude direction ("E" or
+ * "W").
+ * @param speed Speed over ground in knots.
+ * @param angle Course/heading angle in degrees.
+ * @returns True if the RMC response was added successfully, False otherwise.
+ */
 bool GPSModel::AddGpsEventRMC(wippersnapper_gps_GPSDateTime datetime,
                               uint8_t fix_status, float lat, char *lat_dir,
                               float lon, char *lon_dir, float speed,
@@ -154,6 +169,23 @@ bool GPSModel::AddGpsEventRMC(wippersnapper_gps_GPSDateTime datetime,
   return true;
 }
 
+/*!
+ * @brief Adds a GGA response to the GPSEvent message.
+ * @param datetime A wippersnapper_gps_GPSDateTime message representing the
+ * date and time.
+ * @param fix_status The fix status (1 = valid, 0 = invalid).
+ * @param lat Latitude in decimal degrees.
+ * @param lat_dir Pointer to a string representing latitude direction ("N" or
+ * "S").
+ * @param lon Longitude in decimal degrees.
+ * @param lon_dir Pointer to a string representing longitude direction ("E" or
+ * "W").
+ * @param num_sats Number of satellites in use.
+ * @param hdop Horizontal dilution of precision.
+ * @param alt Altitude in meters above mean sea level.
+ * @param geoid_height Geoid height in meters.
+ * @returns True if the GGA response was added successfully, False otherwise.
+ */
 bool GPSModel::AddGpsEventGGA(wippersnapper_gps_GPSDateTime datetime,
                               uint8_t fix_status, float lat, char *lat_dir,
                               float lon, char *lon_dir, uint8_t num_sats,
@@ -194,6 +226,12 @@ bool GPSModel::AddGpsEventGGA(wippersnapper_gps_GPSDateTime datetime,
   return true;
 }
 
+/*!
+ * @brief Processes an NMEA sentence and adds it to the GPSEvent message.
+ * @param sentence Pointer to the NMEA sentence string.
+ * @param drv Pointer to the GPSHardware driver instance.
+ * @returns True if the sentence was processed successfully, False otherwise.
+ */
 bool GPSModel::ProcessNMEASentence(char *sentence, GPSHardware *drv) {
   // Check for prefix: $GP or $GN
   if (strncmp(sentence, "$GP", 3) != 0 && strncmp(sentence, "$GN", 3) != 0)

src/components/uart/drivers/drvUartBase.h

@@ -29,7 +29,7 @@ class drvUartBase {
 public:
   /*!
       @brief    Instantiates a UART device.
-      @param    HardwareSerial
+      @param    hw_serial
                 Pointer to a HardwareSerial instance.
       @param    driver_name
                 The name of the driver.

src/components/uart/drivers/drvUartUs100.h

@@ -31,9 +31,21 @@
 
 class UARTDevice {
 public:
+  /*!
+      @brief    Instantiates a UARTDevice object.
+      @param    serial
+                Pointer to a Stream instance (HardwareSerial or SoftwareSerial).
+  */
   UARTDevice(Stream *serial) { _serial_dev = serial; }
+  /*!
+      @brief    Destructor for a UARTDevice object.
+  */
   ~UARTDevice() { /* no-op destructor */ }
 
+  /*!
+      @brief    Creates the Adafruit_GenericDevice instance.
+      @returns  True if created successfully, False otherwise.
+  */
   bool CreateDevice() {
     if (_generic_dev != nullptr) {
       return false; // already initialized
@@ -42,12 +54,32 @@ class UARTDevice {
     return _generic_dev->begin();
   }
 
+  /*!
+      @brief    Destroys the Adafruit_GenericDevice instance.
+      @param   thiz
+                Pointer to the UARTDevice instance.
+      @param   buffer
+                Pointer to the buffer containing data to write.
+        @param   len
+                Number of bytes to write.
+      @returns  True if written successfully, False otherwise.
+  */
   static bool uart_write(void *thiz, const uint8_t *buffer, size_t len) {
     UARTDevice *dev = (UARTDevice *)thiz;
     dev->_serial_dev->write(buffer, len);
     return true;
   }
 
+  /*!
+      @brief    Reads data from the UART device.
+      @param    thiz
+                Pointer to the UARTDevice instance.
+      @param    buffer
+                Pointer to the buffer to store read data.
+      @param    len
+                Number of bytes to read.
+      @returns  True if read successfully, False otherwise.
+  */
   static bool uart_read(void *thiz, uint8_t *buffer, size_t len) {
     UARTDevice *dev = (UARTDevice *)thiz;
     uint16_t timeout = 100;
@@ -63,6 +95,10 @@ class UARTDevice {
     return true;
   }
 
+  /*!
+      @brief    Gets the GenericDevice instance.
+      @returns  Pointer to the Adafruit_GenericDevice instance.
+  */
   Adafruit_GenericDevice *getGenericDevice() { return _generic_dev; }
 
 private:

src/components/uart/model.h

@@ -16,7 +16,7 @@
 #define WS_UART_MODEL_H
 #include "Wippersnapper_V2.h"
 #include <Adafruit_Sensor.h>
-#define MAX_UART_INPUT_EVENTS 15
+#define MAX_UART_INPUT_EVENTS 15 ///< Maximum number of UART input events
 
 /*!
     @brief  Provides an interface for creating, encoding, and parsing