enhance docs for recently refactored components (+cleanup, naming, etc.)

include/kbf_http_client.h

@@ -18,7 +18,7 @@ namespace kbf::http {
      */
     class Client {
     public:
-        static constexpr kbf::Tag TAG = "kbf::http::AsyncClient";
+        static constexpr const char *TAG = "kbf::http::AsyncClient";
         Client();
 
         /**

include/kbf_net.h

@@ -5,25 +5,22 @@
 
 #include <esp_netif.h>
 
-/**
- * Networking functions.
- */
 namespace kbf::net {
-    /** Tag used for logging. */
+    /** @brief Tag used for logging. */
     static constexpr const char *TAG = "kbf::net";
 
     /**
-     * Stores a MAC address.
+     * @brief Stores a MAC address.
      */
-    class Mac { // TODO maybe move this somewhere else, as it's not WiFi specific (also setMac and getMac)
+    class MAC {
     public:
-        explicit Mac(const uint8_t addr[6]);
+        explicit MAC(const uint8_t addr[6]);
 
-        /** MAC address as uint8_t[6] */
+        /** @brief MAC address as uint8_t[6] */
         uint8_t addr[6]{};
 
         /**
-         * Returns the MAC address as std::string.
+         * @brief Returns the MAC address as std::string.
          *
          * @return the address in "aa:bb:cc:dd:ee:ff" format
          */
@@ -31,38 +28,38 @@ namespace kbf::net {
     };
 
     /**
-     * Sets the base MAC address of the device.
+     * @brief Sets the base MAC address of the device.
      *
      * @note This function must be called before the WiFi driver is initialized,
      *       i.e. before kbf::wifi::init().
      *
      * @param MAC address to use
      */
-    void setMac(const Mac &mac);
+    void setMac(const MAC &mac);
 
     /**
-     * Gets the base MAC address of the device.
+     * @brief Gets the base MAC address of the device.
      *
      * @return MAC address in use
      */
-    Mac getMac();
+    MAC getMac();
 
     /**
-     * Stores an IP address.
+     * @brief Stores an IPv4 address.
      */
     class IP {
     public:
         IP() : addr{0} {};
 
         /**
-         * Instantiate from esp_ip4_addr.
+         * @brief Instantiate from esp_ip4_addr.
          *
          * @param addr esp_ip4_addr
          */
         explicit IP(esp_ip4_addr addr) : addr(addr.addr) {};
 
         /**
-         * Returns the IP address as a std::string.
+         * @brief Returns the IPv4 address as a std::string.
          *
          * @return the address in "123.123.123.123" format
          */

include/kbf_nvs.h

@@ -2,28 +2,21 @@
 #define KBF_NVS_H
 
 #include <string>
-#include <memory>
 #include <atomic>
 
 #include <esp_log.h>
 #include <nvs_flash.h>
 
 using std::string;
-using std::shared_ptr;
 
-/**
- * Non-Volatile Storage access functions.
- */
 namespace kbf::nvs {
-    static std::atomic<bool> initialized = {false};
-
     /**
-     * Non-Volatile Storage read / write functions.
+     * @brief Non-Volatile Storage read / write functions.
      */
     class NVS {
     public:
         /**
-         * Constructor. Calls init() if it hasn't been called yet.
+         * @brief Constructor. Calls init() if it hasn't been called yet.
          *
          * @param name NVS namespace name; default is "storage"
          */
@@ -32,7 +25,7 @@ namespace kbf::nvs {
         ~NVS();
 
         /**
-         * Reads a numeric value from NVS.
+         * @brief Reads a numeric value from NVS.
          *
          * @tparam T value type
          * @param key name
@@ -43,7 +36,7 @@ namespace kbf::nvs {
         bool read(const string &key, T &value);
 
         /**
-         * Writes a numeric value to NVS.
+         * @brief Writes a numeric value to NVS.
          *
          * @tparam T value type
          * @param key name
@@ -52,7 +45,7 @@ namespace kbf::nvs {
         template<typename T>
         void write(const string &key, T &value);
 
-        /** NVS namespace name */
+        /** @brief NVS namespace name */
         const string name;
 
     private:
@@ -60,7 +53,7 @@ namespace kbf::nvs {
     };
 
     /**
-     * Initializes NVS. Will be called from NVS class ctor if it hasn't been called yet.
+     * @brief Initializes NVS. Will be called from NVS class ctor if it hasn't been called yet.
      */
     void init();
 

include/kbf_wifi.h

@@ -9,22 +9,19 @@
 
 using std::string;
 
-/**
- * WiFi functions
- */
 namespace kbf::wifi {
     /**
-     * WiFi station (STA) mode.
+     * @brief WiFi station (STA) mode.
      */
     class STA { // TODO turn this into singleton? doesn't make sense to have multiple instances
     public:
-        /** Tag used for logging. */
+        /** @brief Tag used for logging. */
         static constexpr const char *TAG = "kbf::wifi::STA";
 
         /**
-         * Initializes the WiFi hardware.
+         * @brief Initializes the WiFi hardware.
          *
-         * @note Note that WiFi requires NVS. If NVS hasn't been initialized yet, this ctor will call kbf::nvs::init()
+         * @note WiFi requires NVS. If NVS hasn't been initialized yet, this constructor will call kbf::nvs::init()
          * and try again.
          */
         STA();
@@ -32,7 +29,7 @@ namespace kbf::wifi {
         ~STA();
 
         /**
-         * Initiates connection to an AP.
+         * @brief Initiates connection to an AP.
          *
          * @param ssid SSID of AP
          * @param password Password
@@ -41,14 +38,12 @@ namespace kbf::wifi {
         void connect(const string &ssid, const string &password, int maxRetryAttempts = 3);
 
         /**
-         * Disconnects from the AP.
-         *
-         * @warning not yet implemented
+         * @brief Disconnects from the AP.
          */
         void disconnect();
 
         /**
-         * Called when the connection to the AP was successful.
+         * @brief Called when the connection to the AP was successful.
          *
          * @note Connection may be useless until an IP address is assigned by the AP. See onIp().
          * @see onIp()
@@ -56,12 +51,12 @@ namespace kbf::wifi {
         void (*onConnect)(){};
 
         /**
-         * Called once an IP address is assigned by the AP. The connection should be ready to use at this point.
+         * @brief Called once an IP address is assigned by the AP. The connection should be ready to use at this point.
          */
         void (*onIp)(){};
 
         /**
-         * Called before reconnect attempts.
+         * @brief Called before reconnect attempts.
          *
          * Reconnect is attempted after disconnect events if retryMax hasn't been reached yet.
          *
@@ -74,10 +69,11 @@ namespace kbf::wifi {
         bool (*onReconnecting)(int attempt, int max){};
 
         /**
-         * Called if disconnected and retryMax has been reached.
+         * @brief Called if disconnected and retryMax has been reached.
          */
         void (*onDisconnect)(){};
 
+        /** @brief Returns the IP address for the connection. */
         [[nodiscard]] const kbf::net::IP &ip() const { return m_ip; };
 
     private:

src/kbf.cpp

@@ -3,7 +3,7 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
-static kbf::Tag TAG = "kbf";
+static constexpr const char *TAG = "kbf";
 
 void kbf::sleep(uint32_t milliseconds) {
     vTaskDelay(milliseconds / portTICK_PERIOD_MS);

src/kbf_net.cpp

@@ -9,7 +9,7 @@
 
 #include "kbf_assert.h"
 
-std::string kbf::net::Mac::str() const {
+std::string kbf::net::MAC::str() const {
     using std::setw;
     std::stringstream ss;
     ss << std::hex << std::setfill('0') << setw(2) << std::right << std::uppercase
@@ -22,23 +22,23 @@ std::string kbf::net::Mac::str() const {
     return ss.str();
 }
 
-kbf::net::Mac::Mac(const uint8_t addr[6]) {
+kbf::net::MAC::MAC(const uint8_t addr[6]) {
     // TODO look up some (syntax) magic for array initialization
     for (int i = 0; i < 6; i++) {
         this->addr[i] = addr[i];
     }
 }
 
-void kbf::net::setMac(const Mac &mac) {
+void kbf::net::setMac(const MAC &mac) {
     ESP_LOGI(TAG, "setting base MAC address to %s", mac.str().c_str());
     CHECK(esp_base_mac_addr_set(mac.addr));
 }
 
-kbf::net::Mac kbf::net::getMac() {
+kbf::net::MAC kbf::net::getMac() {
     uint8_t addr[6]{};
     CHECK(esp_base_mac_addr_get(addr));
 
-    auto mac = Mac(addr);
+    auto mac = MAC(addr);
     ESP_LOGI(TAG, "read base MAC address: %s", mac.str().c_str());
     return mac;
 }

src/kbf_nvs.cpp

@@ -7,6 +7,8 @@
 
 static constexpr const char *TAG = "kbf::nvs";
 
+static std::atomic<bool> initialized = {false};
+
 void kbf::nvs::init() {
     ESP_LOGI(TAG, "init()");
 

test/test_net.cpp

@@ -5,7 +5,7 @@
 TEST_CASE("MAC address functions", "[kbf_net]") {
     uint8_t addr[] = {0, 0, 11, 128, 176, 255};
 
-    auto mac = kbf::net::Mac(addr);
+    auto mac = kbf::net::MAC(addr);
     TEST_ASSERT_EQUAL_STRING_MESSAGE("00:00:0B:80:B0:FF", mac.str().c_str(), "ctor / str()");
 
     kbf::net::setMac(mac);