chore: add doc comments for public methods

include/OTA.h

@@ -22,7 +22,7 @@ namespace ESPAdmin
         static Logger _logger;
         static bool _aborted;
         static esp_https_ota_handle_t _otaHandle;
-        static void task(void *pvParameters);
+        static void _task(void *pvParameters);
     };
 }
 

src/ESPAdmin.cpp

@@ -2,6 +2,13 @@
 
 namespace ESPAdmin
 {
+  /**
+   * Initializes the ESPAdmin library with the provided options.
+   *
+   * @param options The initialization options for the ESPAdmin library.
+   *
+   * @throws None
+   */
   void begin(InitOptions options)
   {
     options.resetDelayMs = DEFAULT_INT(options.resetDelayMs, 7000);

src/HTTP.cpp

@@ -4,6 +4,15 @@ namespace ESPAdmin
 {
     Logger HTTP::_logger("HTTP");
 
+    /**
+     * Retrieves data from the server using an HTTP GET request.
+     *
+     * @param path The path to append to the base URL for the GET request.
+     *
+     * @return The response data obtained from the server.
+     *
+     * @throws ErrorType If there are errors during the HTTP GET request.
+     */
     String HTTP::get(const String &path)
     {
         char response[Store::options.httpMaxResponseSize] = "";
@@ -59,6 +68,17 @@ namespace ESPAdmin
         return String(response);
     }
 
+    /**
+     * Sends an HTTP POST request to the specified path with the given content and content type.
+     *
+     * @param path The path to append to the base URL for the POST request.
+     * @param content The content to send in the request body.
+     * @param contentType The content type of the request body.
+     *
+     * @return The response data obtained from the server.
+     *
+     * @throws ErrorType If there are errors during the HTTP POST request.
+     */
     String HTTP::post(const String &path, const String &content, const String &contentType)
     {
         char response[Store::options.httpMaxResponseSize] = "";

src/Logger.cpp

@@ -6,6 +6,13 @@ namespace ESPAdmin
     {
     }
 
+    /**
+     * Logs an informational message.
+     *
+     * @param format The format string for the message.
+     *
+     * @throws None
+     */
     void Logger::info(const char *format, ...) const
     {
         va_list args;
@@ -18,6 +25,14 @@ namespace ESPAdmin
         _log(ANSI_COLOR_BLUE, "info", buffer);
     }
 
+    /**
+     * Logs an error message with the given format and arguments.
+     *
+     * @param format The format string for the error message.
+     * @param ... The arguments for the format string.
+     *
+     * @throws None
+     */
     void Logger::error(const char *format, ...) const
     {
         va_list args;
@@ -30,6 +45,14 @@ namespace ESPAdmin
         _log(ANSI_COLOR_RED, "error", buffer);
     }
 
+    /**
+     * Logs a warning message with the given format and arguments.
+     *
+     * @param format The format string for the warning message.
+     * @param ... The arguments for the format string.
+     *
+     * @throws None
+     */
     void Logger::warn(const char *format, ...) const
     {
         va_list args;
@@ -42,6 +65,14 @@ namespace ESPAdmin
         _log(ANSI_COLOR_YELLOW, "warn", buffer);
     }
 
+    /**
+     * Logs a success message with the given format and arguments.
+     *
+     * @param format The format string for the success message.
+     * @param ... The arguments for the format string.
+     *
+     * @throws None
+     */
     void Logger::success(const char *format, ...) const
     {
         va_list args;

src/MQTT.cpp

@@ -6,6 +6,11 @@ namespace ESPAdmin
 
     esp_mqtt_client_handle_t MQTT::_client;
 
+    /**
+     * Connects to an MQTT broker using the provided configuration.
+     *
+     * @throws None
+     */
     void MQTT::connect()
     {
         const String uriWS = Store::get(STORE_MQTT_URI_WS);
@@ -96,11 +101,26 @@ namespace ESPAdmin
         }
     }
 
+    /**
+     * Disconnects the MQTT client from the broker.
+     *
+     * @throws None
+     */
     void MQTT::disconnect()
     {
         esp_mqtt_client_disconnect(_client);
     }
 
+    /**
+     * Publishes a message to a specified MQTT topic.
+     *
+     * @param topic The topic to publish the message to.
+     * @param message The message to publish.
+     * @param qos The quality of service level for the message.
+     * @param retain Whether the message should be retained by the broker.
+     *
+     * @throws None
+     */
     void MQTT::publish(const String &topic, const String &message, unsigned qos, bool retain)
     {
         if (Store::mqttConnected)
@@ -110,6 +130,17 @@ namespace ESPAdmin
         }
     }
 
+    /**
+     * Publishes a message to a specified MQTT topic.
+     *
+     * @param topic The topic to publish the message to.
+     * @param message The message to publish.
+     * @param len The length of the message.
+     * @param qos The quality of service level for the message.
+     * @param retain Whether the message should be retained by the broker.
+     *
+     * @throws None
+     */
     void MQTT::publish(const String &topic, const char *message, int len, unsigned qos, bool retain)
     {
         if (Store::mqttConnected)
@@ -119,6 +150,14 @@ namespace ESPAdmin
         }
     }
 
+    /**
+     * Subscribes to a specified MQTT topic with the given quality of service level.
+     *
+     * @param topic The topic to subscribe to.
+     * @param qos The quality of service level for the subscription.
+     *
+     * @throws None
+     */
     void MQTT::subscribe(const String &topic, unsigned qos)
     {
         if (Store::mqttConnected)

src/NVS.cpp

@@ -4,6 +4,13 @@ namespace ESPAdmin
 {
     Logger NVS::_logger("NVS");
 
+    /**
+     * Initializes the NVS module and opens a namespace for reading and writing.
+     *
+     * @param _namespace The name of the namespace to open.
+     *
+     * @throws None.
+     */
     void NVS::begin(const char *_namespace)
     {
         esp_err_t err = nvs_flash_init();
@@ -31,6 +38,15 @@ namespace ESPAdmin
         }
     }
 
+    /**
+     * Retrieves a string value from the NVS (Non-Volatile Storage) with the given key.
+     *
+     * @param key The key of the string value to retrieve.
+     *
+     * @return The retrieved string value if it exists, an empty string otherwise.
+     *
+     * @throws None
+     */
     String NVS::getString(const char *key) const
     {
         size_t required_size;
@@ -47,6 +63,14 @@ namespace ESPAdmin
         return String(value);
     }
 
+    /**
+     * Sets a string value in the NVS (Non-Volatile Storage) with the given key.
+     *
+     * @param key The key of the string value to set.
+     * @param value The string value to set. If nullptr, an empty string will be set.
+     *
+     * @throws None.
+     */
     void NVS::setString(const char *key, const char *value) const
     {
         esp_err_t err = nvs_set_str(_handler, key, value == nullptr ? "" : value);
@@ -59,6 +83,11 @@ namespace ESPAdmin
         }
     }
 
+    /**
+     * Clears all the data stored in the NVS (Non-Volatile Storage) by erasing all the keys and committing the changes.
+     *
+     * @throws None
+     */
     void NVS::clear() const
     {
         nvs_erase_all(_handler);

src/OTA.cpp

@@ -6,6 +6,15 @@ namespace ESPAdmin
     bool OTA::_aborted = false;
     esp_https_ota_handle_t OTA::_otaHandle;
 
+    /**
+     * Starts the OTA (Over-The-Air) update process for the device.
+     *
+     * @param downloadURL The URL from which to download the binary file.
+     *
+     * @return None.
+     *
+     * @throws None.
+     */
     void OTA::start(const String &downloadURL)
     {
         esp_http_client_config_t httpConfig = {
@@ -30,16 +39,25 @@ namespace ESPAdmin
         }
         else
         {
-            xTaskCreatePinnedToCore(task, "ota_start", Store::options.otaTaskStackSize, nullptr, Store::options.otaTaskPriority, nullptr, 1);
+            xTaskCreatePinnedToCore(_task, "ota_start", Store::options.otaTaskStackSize, nullptr, Store::options.otaTaskPriority, nullptr, 1);
         }
     }
 
+    /**
+     * Abort OTA process.
+     *
+     * @param None.
+     *
+     * @return None.
+     *
+     * @throws None.
+     */
     void OTA::abort()
     {
         _aborted = true;
     }
 
-    void OTA::task(void *)
+    void OTA::_task(void *)
     {
         int imageReadPrev = 0;
 

src/Report.cpp

@@ -4,6 +4,13 @@ namespace ESPAdmin
 {
     Logger Report::_logger("Report");
 
+    /**
+     * Sends a custom report message to the server and publishes it to MQTT.
+     *
+     * @param reportMessage The report message to be sent.
+     *
+     * @throws None
+     */
     void Report::send(const ReportMessage &reportMessage)
     {
         String message;
@@ -38,6 +45,13 @@ namespace ESPAdmin
         MQTT::publish("/report/custom", message, 1, false);
     }
 
+    /**
+     * Sends a connection status message to the server and publishes it to MQTT.
+     *
+     * @param status The status message to be sent.
+     *
+     * @throws None
+     */
     void Report::sendStatus(const String &status)
     {
         String message;
@@ -51,6 +65,14 @@ namespace ESPAdmin
         MQTT::publish("/report/status", message, 1, true);
     }
 
+    /**
+     * Sends an update status message to the server and publishes it to MQTT.
+     *
+     * @param updateMessage The update message object.
+     * @param status The status of the update.
+     *
+     * @throws None
+     */
     void Report::sendUpdateStatus(UpdateMessage &updateMessage, const String &status)
     {
         if (status == "started")
@@ -97,6 +119,14 @@ namespace ESPAdmin
         }
     }
 
+    /**
+     * Sends an update progress message to the server and publishes it to MQTT.
+     *
+     * @param updateMessage The update message object.
+     * @param progress The progress of the update in %.
+     *
+     * @throws None
+     */
     void Report::sendUpdateProgress(UpdateMessage &updateMessage, int progress)
     {
         String mqttMessage;

src/Store.cpp

@@ -14,6 +14,13 @@ namespace ESPAdmin
 
     InitOptions Store::options;
 
+    /**
+     * Initializes the Store with the provided initialization options.
+     *
+     * @param options The initialization options for the Store.
+     *
+     * @throws None
+     */
     void Store::begin(const InitOptions options)
     {
         _NVS.begin(_namespace);
@@ -23,11 +30,30 @@ namespace ESPAdmin
         _getSettings();
     }
 
+    /**
+     * Retrieves a string value from the NVS (Non-Volatile Storage) using the provided key.
+     *
+     * @param key The key of the string value to retrieve.
+     *
+     * @return The retrieved string value if it exists, an empty string otherwise.
+     *
+     * @throws None
+     */
     String Store::get(StoreKey key)
     {
         return _NVS.getString(String(key).c_str());
     }
 
+    /**
+     * Sets a string value in the NVS (Non-Volatile Storage) with the given key.
+     *
+     * @param key The key of the string value to set.
+     * @param value The string value to set. If nullptr, an empty string will be set.
+     *
+     * @return None
+     *
+     * @throws None.
+     */
     void Store::set(StoreKey key, const char *value)
     {
         _NVS.setString(String(key).c_str(), value);