From 0067a0b8a9ab140fb44224fba3adb5ffd0541a15 Mon Sep 17 00:00:00 2001
From: Jens True <jens.chr.true@gmail.com>
Date: Sat, 12 Dec 2020 17:48:36 +0100
Subject: [PATCH] More doxygen comments added.

---
 src/main.cpp | 41 ++++++++++++++++++++++++++++++++---------
 1 file changed, 32 insertions(+), 9 deletions(-)

diff --git a/src/main.cpp b/src/main.cpp
index 5b8d3f6..aa8c2ef 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -17,17 +17,21 @@
 LoggerNode LN; ///<Instance of the LoggerNode library
 
 #include "DHTesp.h"
-DHTesp dht; ///< DHT instance 
+DHTesp dht; ///< Instance of the DHT temperature controller. 
 
 
-#define OUTPUT_SET(x)  digitalWrite(CONFIG_IO_RELAY, x ? LOW : HIGH)
-unsigned int timer = 0;
-unsigned int next_timer_update = 0;
+#define OUTPUT_SET(x)  digitalWrite(CONFIG_IO_RELAY, x ? LOW : HIGH)  ///< Macro for controlling the output state.
+unsigned int timer = 0;   ///< Remaining time when counting down.
+unsigned int next_timer_update = 0; ///< Timer used to control when the timer value should be pushed to the server
+
 HomieNode powerNode("power", "Power", "switch");
 HomieNode temperatureNode("temperature", "Temperature", "temperature");
 
 /** Power state handler 
- * Handes event on the power state MQTT node
+ * Handles event on the power state MQTT node
+ * \param[in] range Currently unused
+ * \param[in] value New value of the power state. (Either "on" or off")
+ * \return False if input is invalid. Otherwise true.
  */
 bool powerStateHandler(const HomieRange& range, const String& value)
 {
@@ -53,7 +57,11 @@ bool powerStateHandler(const HomieRange& range, const String& value)
 }
 
 /**
- * Handler for events on the powerTimer node
+ * \brief powerTimer event handler.
+ * Handler for events on the powerTimer node.
+ * \param[in] range Currently unused.
+ * \param[in] value New value for the timer in minutes. ASCII representation of an integer from 1 to 120.
+ * \return False if input is invalid. Otherwise true.
  */
 bool powerTimerHandler(const HomieRange& range, const String& value)
 {
@@ -70,10 +78,11 @@ bool powerTimerHandler(const HomieRange& range, const String& value)
     return true;
 }
 
-
+/**
+ * setupHandler. Comply with Homie interface
+ */
 void setupHandler()
 {
-
   pinMode(CONFIG_IO_RELAY, OUTPUT);
   OUTPUT_SET(false);
   powerNode.setProperty("state").send("off");
@@ -82,6 +91,9 @@ void setupHandler()
   dht.setup(CONFIG_IO_DHT11, DHTesp::DHT11); // Connect DHT sensor to GPIO 17
 }
 
+/**
+ * Handle timer updates from the main event loop
+ */
 void loopHandleTimer() 
 {
   if(timer)
@@ -104,6 +116,9 @@ void loopHandleTimer()
   }
 }
 
+/**
+ * Handle periodic temperature measurements from the main event loop
+ */
 void loopHandleTemperature() 
 {
   static unsigned long lastTemperatureSent = 0;
@@ -119,7 +134,8 @@ void loopHandleTemperature()
 }
 
 /**
- * Main event loop
+ * Main event loop. Part of the Homie API. This runs while the device is active and connected.
+ * 
  * \callgraph
  */
 void loopHandler()
@@ -128,6 +144,10 @@ void loopHandler()
   loopHandleTemperature();
 }
 
+/**
+ * Arduino style setup() routine.
+ * Configure the Homie framework by adding the two nodes "power" and "temperature"
+ */
 void setup()
 {
 
@@ -151,6 +171,9 @@ void setup()
     Homie.setup();
 }
 
+/**
+ * Arduino main loop. Forwarded to Homie framework
+ */
 void loop()
 {
     Homie.loop();