More api documentation

Author: BenjaminDannegard

libraries/WiFiS3/src/Modem.h

@@ -15,6 +15,13 @@
 
 #define DO_NOT_CHECK_CMD "NO_CMD_CHECK"
 
+/**
+ * @brief A class that provides methods to interact with a modem.
+ * 
+ * This class is responsible for providing an interface to communicate with
+ * a modem through serial communication. It includes methods for initialization, 
+ * sending and receiving data, and handling modem configurations.
+ */
 class ModemClass {
 
 public:
@@ -32,6 +39,10 @@ class ModemClass {
    * @param `_serial` is a pointer to the UART object that will be used for communication with the modem.
    */
   ModemClass(UART * _serial);
+
+  /**
+   * @brief Destructor for ModemClass.
+   */
   ~ModemClass();
 
   /**
@@ -48,23 +59,17 @@ class ModemClass {
 
 
   /**
- * @brief Sends a formatted command string to a device and stores the response.
- *
- * This function formats a command string using the provided format and arguments, 
- * sends it to a device, and waits for a response, which is stored in the `str` string.
- *
- * @param cmd A string representing the command to be sent to the device.
- * @param str A reference to a string that will hold the device's response.
- * @param fmt A format string for constructing the command.
- * 
- * @return `true` if the command was successfully sent and a response was received, 
- *         `false` otherwise.
- */
-  /**
-   * @brief Sends a command to the modem and waits for a response.
+   * @brief Sends a formatted command string to a device and stores the response.
+   *
+   * This function formats a command string using the provided format and arguments, 
+   * sends it to a device, and waits for a response, which is stored in the `str` string.
+   *
+   * @param `cmd` A string representing the command to be sent to the device.
+   * @param `str` A reference to a string that will hold the device's response.
+   * @param `fmt` A format string for constructing the command.
    * 
-   * @param It takes a command string `cmd`, a string `str` where the response will be stored 
-   * and a format string `fmt` along with additional arguments.
+   * @return `true` if the command was successfully sent and a response was received, 
+   * `false` otherwise.
    */
   bool write(const std::string &cmd, std::string &str, const char * fmt, ...);
 
@@ -85,20 +90,30 @@ class ModemClass {
    */
   bool passthrough(const uint8_t *data, size_t size);
 
+  /**
+   * @brief Disables automatic trimming of results for one operation.
+   * 
+   * This function disables the automatic trimming of results for one operation. 
+   * After it is called, the results will not be trimmed automatically until 
+   * the function is called again.
+   */
   void avoid_trim_results() {
     /* one shot - it works only 1 time the it is necessary to call again this
        funtion */
     trim_results = false;
   }
 
-
   /**
    * @brief Enables a specific mode of reading where the size of the data
    * to be read is considered for processing.
    */
   void read_using_size() {
     read_by_size = true;
   } 
+
+  /**
+   * @brief Flag indicating whether the system has been initialized.
+   */
   bool beginned;
 
   /* Calling this function with no argument will enable debug message to be printed

libraries/WiFiS3/src/StringHelpers.h

@@ -44,10 +44,10 @@ void trim(std::string &s);
  * 
  * @param `res` is a reference to a vector of strings where the resulting tokens 
  * will be stored.
- * `str` is the string to be split. This string will be modified as it is 
+ * @param `str` is the string to be split. This string will be modified as it is 
  * split.
- * `delimiter` is the delimiter string that separates the tokens in `str`.
- * `_trim` is a boolean flag indicating whether to trim whitespace from each 
+ * @param `delimiter` is the delimiter string that separates the tokens in `str`.
+ * @param `_trim` is a boolean flag indicating whether to trim whitespace from each 
  * token. If true, leading and trailing whitespace will be removed from each token. Defaults to true.
  */
 void split(std::vector<std::string> &res, std::string &str, const std::string &delimiter, bool _trim = true);
@@ -63,10 +63,10 @@ void split(std::vector<std::string> &res, std::string &str, const std::string &d
  *
  * @param `str` is a reference to the string from which the substring will be removed. 
  * The string is modified if the substring is removed.
- * `what` is the substring to be removed from the beginning of `str`.
+ * @param `what` is the substring to be removed from the beginning of `str`.
  * 
  * @return `true` if the substring was found and removed from the beginning of 
- *         the string, `false` otherwise.
+ * the string, `false` otherwise.
  */
 bool removeAtBegin(std::string &str, const std::string &what);
 

libraries/WiFiS3/src/WiFi.h

@@ -86,7 +86,7 @@ class CWifi {
      *
      * @param `ssid` The SSID (network name) of the Access Point.
      * 
-     * @return 1 if the Access Point is successfully started. 0 if the Access Point initialization failed.
+     * @return `1` if the Access Point is successfully started. `0` if the Access Point initialization failed.
      */
     uint8_t beginAP(const char *ssid);
     uint8_t beginAP(const char *ssid);
@@ -100,7 +100,7 @@ class CWifi {
      * @param `ssid` The SSID (name) of the Wi-Fi Access Point.
      * @param `channel` The channel on which the Access Point will operate.
      * 
-     * @return 1 if the Access Point is successfully started. 0 if the Access Point failed to start.
+     * @return `1` if the Access Point is successfully started. `0` if the Access Point failed to start.
      */
     uint8_t beginAP(const char *ssid, uint8_t channel);
 
@@ -114,7 +114,7 @@ class CWifi {
      * @param `passphrase` The passphrase for securing the Access Point. If empty, the 
      * network will be open (no password).
      * 
-     * @return 1 if the Access Point is successfully started. 0 if the Access Point failed to start.
+     * @return `1` if the Access Point is successfully started. `0` if the Access Point failed to start.
      */
     uint8_t beginAP(const char *ssid, const char* passphrase);
 
@@ -128,70 +128,82 @@ class CWifi {
      * @param `passphrase` The passphrase for securing the Access Point. If empty, the network will be open.
      * @param `channel` The Wi-Fi channel on which the Access Point will operate (1-14, depending on region).
      * 
-     * @return WL_AP_LISTENING if the Access Point is successfully started. WL_AP_FAILED if the Access Point failed to start.
+     * @return `WL_AP_LISTENING` if the Access Point is successfully started. `WL_AP_FAILED` if the Access Point failed to start.
      */
     uint8_t beginAP(const char *ssid, const char* passphrase, uint8_t channel);
 
 
-    /* Change IP configuration settings disabling the DHCP client
-        *
-        * param local_ip:  Static IP configuration
-        */
+    /**
+     * @brief Change IP configuration settings disabling the DHCP client
+     *
+     * @param `local_ip` The static IP address to assign to the device.
+     */
     void config(IPAddress local_ip);
 
-    /* Change IP configuration settings disabling the DHCP client
-        *
-        * param local_ip:  Static IP configuration
-   * param dns_server:     IP configuration for DNS server 1
-        */
+    /**
+     * @brief Configures the network settings for the Wi-Fi connection with a specified DNS server.
+     *
+     * Sets the device's IP configuration using the specified local IP address and DNS server.
+     * The gateway and subnet mask are set to default values based on the provided local IP.
+     *
+     * @param `local_ip` The static IP address to assign to the device.
+     * @param `dns_server` The primary DNS server to use for domain name resolution.
+     */
     void config(IPAddress local_ip, IPAddress dns_server);
 
-    /* Change IP configuration settings disabling the DHCP client
-        *
-        * param local_ip:  Static IP configuration
-   * param dns_server:     IP configuration for DNS server 1
-        * param gateway :  Static gateway configuration
-        */
+    /**
+     * @brief Configures the network settings for the Wi-Fi connection with a specified gateway and DNS server.
+     *
+     *
+     * @param `local_ip` The static IP address to assign to the device.
+     * @param `dns_server` The primary DNS server to use for domain name resolution.
+     * @param `gateway` The Static gateway used for configuration.
+     */
     void config(IPAddress local_ip, IPAddress dns_server, IPAddress gateway);
 
-    /* Change IP configuration settings disabling the DHCP client
-        *
-        * param local_ip:  Static IP configuration
-   * param dns_server:     IP configuration for DNS server 1
-        * param gateway:   Static gateway configuration
-        * param subnet:    Static Subnet mask
-        */
+    /**
+     * @brief Configures the network settings for the Wi-Fi connection with a specified subnet mask, gateway, and DNS server.
+     *
+     *
+     * @param `local_ip` The static IP address to assign to the device.
+     * @param `dns_server` The primary DNS server to use for domain name resolution.
+     * @param `gateway` The static gateway used for configuration.
+     * @param `subnet` The static subnet mask to use for the network.
+     */
     void config(IPAddress local_ip, IPAddress dns_server, IPAddress gateway, IPAddress subnet);
 
-    /* Change DNS IP configuration
+    /**
+     * @brief Sets the primary DNS server for the Wi-Fi connection.
      *
-     * param dns_server1: IP configuration for DNS server 1
+     * @param `dns_server1` The primary DNS server to use for domain name resolution.
      */
     void setDNS(IPAddress dns_server1);
 
-    /* Change DNS IP configuration
-     *
-     * param dns_server1: IP configuration for DNS server 1
-     * param dns_server2: IP configuration for DNS server 2
+    /**
+     * @brief Sets the primary and secondary DNS servers for the Wi-Fi connection.
      *
+     * @param `dns_server1` sets the IP configuration for DNS server 1
+     * @param `dns_server2` sets the IP configuration for DNS server 2
      */
     void setDNS(IPAddress dns_server1, IPAddress dns_server2);
 
-
-    /* Set the hostname used for DHCP requests
-     *
-     * param name: hostname to set
+    /**
+     * @brief Sets the hostname for for DHCP requests.
      *
+     * @param `name` sets the hostname.
      */
     void setHostname(const char* name);
 
-    /*
-     * Disconnect from the network
+    /**
+     * @brief Disconnects from the current Wi-Fi network.
      *
-     * return: one value of wl_status_t enum
+     * @return `1` if the disconnection was successful, `0` otherwise.
      */
     int disconnect(void);
 
+    /**
+     * @brief Resets and disables the Wi-Fi module.
+     */
     void end(void);
 
     /*

libraries/WiFiS3/src/WiFiClient.h

@@ -30,6 +30,17 @@
 #include "FifoBuffer.h"
 #include <memory>
 
+
+/**
+ * @brief Represents a Wi-Fi client that connects to a remote server over a Wi-Fi network.
+ * 
+ * The `WiFiClient` class allows for network communication over Wi-Fi, providing methods 
+ * for establishing connections, sending and receiving data, and managing the client’s 
+ * socket state. This class is used to manage client connections in a Wi-Fi network, 
+ * either for communication or for network data transfer.
+ * 
+ * It inherits from the `Client` class, providing basic socket communication functionality.
+ */
 class WiFiClient : public Client {
 
 public:
@@ -52,6 +63,10 @@ class WiFiClient : public Client {
    * @param `c` is the `WiFiClient` object to copy.
    */
   WiFiClient(const WiFiClient& c);
+
+  /**
+   * @brief Destructor for the WiFiClient class.
+   */
   ~WiFiClient();
 
   /**
@@ -153,10 +168,40 @@ class WiFiClient : public Client {
    */
   virtual uint8_t connected();
 
+  /**
+   * @brief Implicit conversion operator to `bool`.
+   * 
+   * Converts the `WiFiClient` object to a `bool` value indicating whether the client 
+   * is connected or not.
+   * 
+   * @return `true` if the client socket is open and valid, `false` otherwise.
+   */
   virtual operator bool() {
     return _sock != -1;
   }
+
+  /**
+   * @brief Equality operator for comparing two `WiFiClient` objects.
+   * 
+   * Compares the current `WiFiClient` object with another `WiFiClient` object
+   * to determine if they represent the same socket connection.
+   * 
+   * @param The `WiFiClient` object to compare with.
+   * @return `true` if both `WiFiClient` objects represent the same socket, 
+   * `false` otherwise.
+   */
   virtual bool operator==(const WiFiClient&);
+
+  /**
+   * @brief Inequality operator for comparing two `WiFiClient` objects.
+   * 
+   * Compares the current `WiFiClient` object with another `WiFiClient` object
+   * to determine if they represent different socket connections.
+   * 
+   * @param `whs` is the `WiFiClient` object to compare with.
+   * @return `true` if both WiFiClient objects represent different sockets, 
+   * `false` if they represent the same socket.
+   */
   virtual bool operator!=(const WiFiClient& whs)
   {
       return !this->operator==(whs);
@@ -185,8 +230,20 @@ class WiFiClient : public Client {
     _connectionTimeout = timeout;
   }
 
+  /**
+   * @brief Declares `WiFiServer` as a friend class.
+   * 
+   * This allows the `WiFiServer` class to access private and protected members 
+   * of the `WiFiClient` class.
+   */
   friend class WiFiServer;
 
+  /**
+   * @brief Inherits the `write` method from the `Print` class.
+   * 
+   * This allows the `WiFiSSLClient` class to use the `write` method defined in the 
+   * `Print` class.
+   */
   using Print::write;
 
 protected:

libraries/WiFiS3/src/WiFiFileSystem.h

@@ -24,6 +24,12 @@
 #include "WiFiCommands.h"
 #include "Modem.h"
 
+/**
+ * @brief Class that handles the WiFi file system operations.
+ * 
+ * This class provides functionality for managing files on a WiFi-connected 
+ * device, including mounting, reading, writing, and configuring the file system. 
+ */
 class WiFiFileSystem {
 
 public: