🎨 Add doxygen across new v2 classes

Author: brentru

Doxyfile

@@ -828,6 +828,17 @@ void Wippersnapper_V2::haltErrorV2(String error,
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief    Publishes a signal message to the broker.
+    @param    which_payload
+              The type of signal payload to publish.
+    @param    payload
+              The payload to publish.
+    @returns  True if the signal message published successfully,
+              False otherwise.
+*/
+/**************************************************************************/
 bool Wippersnapper_V2::PublishSignal(pb_size_t which_payload, void *payload) {
   size_t szMessageBuf;
   wippersnapper_signal_DeviceToBroker MsgSignal =

src/Wippersnapper_V2.cpp

@@ -244,7 +244,7 @@ class Wippersnapper_V2 {
 #ifdef ARDUINO_ARCH_ESP32
   ws_ledc *_ledcV2 = nullptr; ///< Pointer to LEDC object
 #endif
-  bool got_checkin_response;
+  bool got_checkin_response; ///< True if a checkin response was received, False otherwise.
 
 private:
   void _initV2();
@@ -261,8 +261,7 @@ class Wippersnapper_V2 {
   Adafruit_MQTT_Subscribe *_subscribeThrottle;
 
 protected:
-  // TODO: Do we need this?
-  ws_status_t _statusV2 = WS_IDLE;
+  ws_status_t _statusV2 = WS_IDLE; ///< Wippersnapper status
 
   uint32_t _last_mqtt_connectV2 = 0; /*!< Previous time when client connected to
                                           Adafruit IO, in milliseconds. */

src/Wippersnapper_V2.h

@@ -16,6 +16,12 @@
 #define WS_CHECKIN_MODEL_H
 #include "Wippersnapper_V2.h"
 
+/**************************************************************************/
+/*!
+    @brief  Provides an interface for creating, encoding, and parsing
+            messages from checkin.proto.
+*/
+/**************************************************************************/
 class CheckinModel {
 public:
   CheckinModel();

src/components/checkin/model.h

@@ -32,6 +32,14 @@ struct DigitalIOPin {
 
 class DigitalIOModel;    // Forward declaration
 class DigitalIOHardware; // Forward declaration
+
+/**************************************************************************/
+/*!
+    @brief  Routes messages using the digitalio.proto API to the
+            appropriate hardware and model classes, controls and tracks
+            the state of the hardware's digital I/O pins.
+*/
+/**************************************************************************/
 class DigitalIOController {
 public:
   DigitalIOController();

src/components/digitalIO/controller.h

@@ -16,6 +16,11 @@
 #define WS_DIGITALIO_HARDWARE_H
 #include "Wippersnapper_V2.h"
 
+/**************************************************************************/
+/*!
+    @brief  Interface for interacting with hardware's digital I/O pin API.
+*/
+/**************************************************************************/
 class DigitalIOHardware {
 public:
   DigitalIOHardware();
@@ -26,7 +31,6 @@ class DigitalIOHardware {
   bool GetValue(uint8_t pin_name);
   void deinit(uint8_t pin_name);
   bool IsStatusLEDPin(uint8_t pin_name);
-
 private:
 };
 #endif // WS_DIGITALIO_HARDWARE_H

src/components/digitalIO/hardware.h

@@ -16,6 +16,12 @@
 #define WS_DIGITALIO_MODEL_H
 #include "Wippersnapper_V2.h"
 
+/**************************************************************************/
+/*!
+    @brief  Provides an interface for creating, encoding, and parsing
+            messages from digitalio.proto.
+*/
+/**************************************************************************/
 class DigitalIOModel {
 public:
   DigitalIOModel();
@@ -39,7 +45,6 @@ class DigitalIOModel {
   wippersnapper_digitalio_DigitalIOEvent *GetDigitalIOEventMsg() {
     return &_msg_dio_event;
   }
-
 private:
   wippersnapper_digitalio_DigitalIOAdd _msg_dio_add;
   wippersnapper_digitalio_DigitalIORemove _msg_dio_remove;

src/components/digitalIO/model.h

@@ -17,6 +17,12 @@
 #include "Wippersnapper_V2.h"
 #include "protos/sensor.pb.h"
 
+/**************************************************************************/
+/*!
+    @brief  Provides an interface for creating, encoding, and parsing
+            messages from sensor.proto.
+*/
+/**************************************************************************/
 class SensorModel {
 public:
   SensorModel();

src/components/sensor/model.h

@@ -1,7 +1,17 @@
 #include "ws_manager.h"
 
+/**************************************************************************/
+/*!
+    @brief    Constructor for Wippersnapper_Manager
+*/
+/**************************************************************************/
 Wippersnapper_Manager::Wippersnapper_Manager() : ws_instance(nullptr) {}
 
+/**************************************************************************/
+/*!
+    @brief    Destructor for Wippersnapper_Manager
+*/
+/**************************************************************************/
 Wippersnapper_Manager::~Wippersnapper_Manager() {
   if (ws_instance) {
     delete ws_instance;
@@ -11,6 +21,11 @@ Wippersnapper_Manager::~Wippersnapper_Manager() {
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief    Performs the connect() function in Wippersnapper*.cpp
+*/
+/**************************************************************************/
 void Wippersnapper_Manager::connect() {
   if (_api_version == 2) {
     WS_DEBUG_PRINTLN("api v2 instance::connect()");
@@ -23,6 +38,11 @@ void Wippersnapper_Manager::connect() {
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief    Performs the provision() function in Wippersnapper*.cpp
+*/
+/**************************************************************************/
 void Wippersnapper_Manager::provision() {
   if (_api_version == 2) {
     WS_DEBUG_PRINTLN("api v2 instance::provision()");
@@ -35,6 +55,13 @@ void Wippersnapper_Manager::provision() {
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief    Checks the API version by reading the state of a pin
+    @param    pinNum
+              The pin number to read
+*/
+/**************************************************************************/
 void Wippersnapper_Manager::checkAPIVersion(int pinNum) {
   // Check if pin D12 is high
   pinMode(pinNum, INPUT_PULLUP);
@@ -50,6 +77,11 @@ void Wippersnapper_Manager::checkAPIVersion(int pinNum) {
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief    Performs the run() function in Wippersnapper*.cpp
+*/
+/**************************************************************************/
 void Wippersnapper_Manager::run() {
   if (_api_version == 2) {
     ws_instance_v2->runV2();

src/ws_manager.cpp

@@ -6,24 +6,30 @@ typedef Wippersnapper_ESP32 Wippersnapper_WiFi;
 #include "network_interfaces/Wippersnapper_ESP32_V2.h"
 typedef Wippersnapper_ESP32V2 Wippersnapper_WiFiV2;
 
+/****************************************************************************/
+/*!
+    @brief  Helper class to manage the WipperSnapper API versions dynamically
+            at runtime.
+*/
+/****************************************************************************/
 class Wippersnapper_Manager {
 public:
   Wippersnapper_Manager();
   ~Wippersnapper_Manager();
 
-  // API version check
+  // API version checks
   void checkAPIVersion(int pinNum);
   int getAPIVersion() { return _api_version; }
+
+  // High-level functions (called from demo sketch ino)
   void provision();
   void connect();
   void run();
 
 protected:
-  // Wippersnapper *ws_instance;
-  Wippersnapper_WiFi *ws_instance;
-  Wippersnapper_WiFiV2 *ws_instance_v2;
-
+  Wippersnapper_WiFi *ws_instance; ///< Instance of Wippersnapper API v1
+  Wippersnapper_WiFiV2 *ws_instance_v2; ///< Instance of Wippersnapper API v2
 private:
   int _api_version;
 };
-#endif                   // WIPPERSNAPPER_MANAGER_H
+#endif // WIPPERSNAPPER_MANAGER_H