Added API tags

Author: BenjaminDannegard

libraries/WiFiS3/src/Modem.h

@@ -19,43 +19,47 @@ class ModemClass {
 
 public:
   /** 
-   * Initializes an instance of the `ModemClass` class with
+   * @param Initializes an instance of the `ModemClass` class with
    * specific transmit (tx) and receive (rx) pins for communication.
    */
   ModemClass(int tx, int rx);
   ModemClass(UART * _serial);
   ~ModemClass();
 
   /**
-   * Initializes the modem communication with a specified baud rate. By default,
-   * the baud rate is set to 115200. Call function after creating an instance of the 
+   * @brief Initializes the modem communication with a specified baud rate.
+   * 
+   * @param The baud rate is set to 115200. Call function after creating an instance of the 
    * `ModemClass` to set up the communication parameters before sending or receiving data.
    */
   void begin(int badurate = 115200);
 
   /** 
-   * Shutts down the modem communication and releases any resources that were allocated during the 
-   * communication process.
+   * @brief Shutts down the modem communication and releases any
+   * resources that were allocated during the communication process.
    */
   void end();
 
   /**
-   * Sends a command to the modem and waits for a response.
-   * It takes a command string `cmd`, a string `str` where the response will be stored 
+   * @brief Sends a command to the modem and waits for a response.
+   * 
+   * @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.
    */
   bool write(const std::string &cmd, std::string &str, const char * fmt, ...);
 
   /**
-   * Used to send a command to the modem without waiting for a response.
-   * It takes a command string `cmd`, a string `str` where the response will be stored,
+   * @brief Used to send a command to the modem without waiting for a response.
+   * 
+   * @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.
    */
   void write_nowait(const std::string &cmd, std::string &str, const char * fmt, ...);
 
   /**
-   * Sends binary data directly to the modem without any processing or interpretation.
-   * It takes a pointer to the binary `data` and the `size` of the data as arguments.
+   * @brief Sends binary data directly to the modem without any processing or interpretation.
+   * 
+   * @param It takes a pointer to the binary `data` and the `size` of the data as arguments.
    * Used for sending raw binary commands or data to the modem for operations that 
    * require direct communication without any additional formatting or parsing.
    */
@@ -69,8 +73,8 @@ class ModemClass {
 
 
   /**
-   * When this function is called, it enables a specific mode of reading 
-   * where the size of the data to be read is considered for processing.
+   * @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;
@@ -93,7 +97,7 @@ class ModemClass {
   }
 
   /**
-   * Used to disable debugging output for the modem communication.
+   * @brief Used to disable debugging output for the modem communication.
    */
   void noDebug() {
     _serial_debug = nullptr;
@@ -106,8 +110,9 @@ class ModemClass {
   #endif
 
   /**
-   * Sets the timeout value for communication operations.
-   * Can be called with a specified timeout value in milliseconds.
+   * @brief Sets the timeout value for communication operations.
+   * 
+   * @param Can be called with a specified timeout value in milliseconds.
    */
   void timeout(size_t timeout_ms) {_timeout = timeout_ms;}
 

libraries/WiFiS3/src/StringHelpers.h

@@ -6,25 +6,68 @@
 #include <algorithm>
 
 /**
- * Trims whitespace characters from the beginning (left side) of the input string `s`.
+ * @brief Trims whitespace characters from the beginning of a string. 
+ * 
+ * @param `s` is the string from which leading whitespace characters will be removed. 
+ * The function modifies this string directly.
  */
 void ltrim(std::string &s);
 
-// trim from end (in place)
+/**
+ * @brief Trims trailing whitespace characters from a string.
+ *
+ * @param `s` the string from which trailing whitespace characters will be removed. 
+ * The function modifies this string directly.
+ */
 void rtrim(std::string &s);
 
-// trim from both ends (in place)
+
+/**
+ * @brief Trims whitespace characters from both ends of a string.
+ *
+ * This function removes any leading and trailing whitespace characters (spaces, 
+ * tabs, etc.) from the given string. It modifies the string in place, erasing 
+ * whitespace from both the beginning and the end of the string.
+ *
+ * @param `s` is the string from which both leading and trailing whitespace characters 
+ * will be removed. The function modifies this string directly.
+ */
 void trim(std::string &s);
 
 /**
- * Takes a string `str` and splits it into substrings based on a specified `delimiter`.
- * The resulting substrings are stored in the `res` vector of strings.
+ * @brief Takes a string and splits it into substrings.
+ * 
+ * This function splits a string into multiple substrings, storing each substring 
+ * as an element in the `res` vector. The string is split at each occurrence of 
+ * the specified delimiter. Optionally, the function can trim whitespace from 
+ * each token before storing it in the result vector.
+ * 
+ * @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 
+ * split.
+ * `delimiter` is the delimiter string that separates the tokens in `str`.
+ * `_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);
 
 /** 
- * Checks if the input string `str` starts with the specified string `what`. If `str` starts 
- * with `what`, the function removes `what` from the beginning of `str` and returns `true`.
+ * @brief Removes a specified substring from the beginning of a string.
+ *
+ * This function attempts to remove the first occurrence of the specified substring 
+ * (`what`) from the beginning of the string (`str`). Before performing the removal, 
+ * it trims leading whitespace from the string. If the substring is found at the 
+ * beginning of the string, it is removed, and the function returns `true`. If the 
+ * substring is not found at the beginning, the string remains unchanged, and the 
+ * function returns `false`.
+ *
+ * @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`.
+ * 
+ * @return `true` if the substring was found and removed from the beginning of 
+ *         the string, `false` otherwise.
  */
 bool removeAtBegin(std::string &str, const std::string &what);
 

libraries/WiFiS3/src/WiFiClient.h

@@ -40,64 +40,68 @@ class WiFiClient : public Client {
   ~WiFiClient();
 
   /**
-   * Establish a connection to a remote server using the specified IP address and port number.
+   * @brief Establish a connection to a remote server using the specified IP address and port number.
    */
   virtual int connect(IPAddress ip, uint16_t port);
 
   /**
-   * Establish a connection to a remote server
-   * using the specified host (domain name or IP address) and port number.
+   * @brief Establish a connection to a remote server.
+   * 
+   * @param Uses the specified domain name or IP address `host` and `port` for port number.
    */
   virtual int connect(const char *host, uint16_t port);
 
   /** 
-   * Writes a single byte of data to the connected client.
+   * @brief Writes a single byte of data to the connected client.
    */
   virtual size_t write(uint8_t);
 
   /** 
-   * Writes a buffer of data to the connected client.
-   * Takes a pointer to a buffer `buf` containing the data to be written
+   * @brief Writes a buffer of data to the connected client.
+   * 
+   * @param Takes a pointer to a buffer `buf` containing the data to be written
    * and the size of the buffer `size` as parameters.
-   * The function writes the data in the buffer to the connected client
+   * 
+   * @return The function writes the data in the buffer to the connected client
    * and returns the number of bytes written.
    */
   virtual size_t write(const uint8_t *buf, size_t size);
 
   /**
-   * Checks how many bytes are available for reading from the connected client.
+   * @brief Checks how many bytes are available for reading from the connected client.
    */
   virtual int available();
 
   /**
-   * Reads a single byte of data from the connected client.
+   * @brief Reads a single byte of data from the connected client.
    */
   virtual int read();
 
   /**
-   * Reads a specified number of bytes from the connected client into a buffer.
+   * @brief Reads a specified number of bytes from the connected client into a buffer.
    */
   virtual int read(uint8_t *buf, size_t size);
 
   /**
-   * Peeks at the next byte of incoming data without removing it from the internal buffer.
+   * @brief Peeks at the next byte of incoming data without removing it from the internal buffer.
    */
   virtual int peek();
 
   /**
-   * Clears any buffered outgoing data that has not been sent to the connected client.
+   * @brief Clears any buffered outgoing data that has not been sent to the connected client.
    */
   virtual void flush();
 
   /**
-   * Closes the connection to the remote server.
-   * Terminates the connection and release any resources associated with it.
+   * @brief Closes the connection to the remote server
+   * and releases any resources associated with it.
    */
   virtual void stop();
 
   /**
-   * Checks whether the client is currently connected to a remote server.
-   * Returns a `uint8_t` value indicating the connection status of the client.
+   * @brief Checks whether the client is currently connected to a remote server.
+   * 
+   * @return Returns a `uint8_t` value indicating the connection status of the client.
    */
   virtual uint8_t connected();
 
@@ -111,19 +115,19 @@ class WiFiClient : public Client {
   };
 
   /**
-   * Returns the IP address of the remote server to which the client is connected.
+   * @return Returns the IP address of the remote server to which the client is connected.
    */
   virtual IPAddress remoteIP();
 
   /**
-   * Returns the port number of the remote server for the connetec client.
+   * @return Returns the port number of the remote server for the connetec client.
    */
   virtual uint16_t remotePort();
 
   /**
-   * Sets the connection timeout value for the client.
-   * It takes an integer `timeout` as a parameter which determines how long the client will wait
-   * for a connection to be established before timing out.
+   * @brief Sets the connection timeout value for the client.
+   * @param It takes an integer `timeout` as a parameter which determines how long the
+   * client will wait for a connection to be established before timing out.
    */
   void setConnectionTimeout(int timeout) {
     _connectionTimeout = timeout;

libraries/WiFiS3/src/WiFiFileSystem.h

@@ -28,26 +28,38 @@ class WiFiFileSystem {
 
 public:
    /**
-    * Initializes objects of the `WiFiFileSystem` class.
+    * @brief Initializes objects of the `WiFiFileSystem` class.
     */
    WiFiFileSystem();
 
    /**
-    * Mounts the file system.
-    * If `format_on_fault` is set to `true`,
+    * @brief Mounts the file system and optionally formats it on failure.
+    *
+    * @param If `format_on_fault` is set to `true`,
     * the file system will be formatted if a fault occurs during mounting.
     */
    void mount(bool format_on_fault = false);
 
    /**
-    * Writes data to a file in the file system.
+    * @brief Writes data to a file in the file system.
+    *
+    * @param `name` is the name of the file to which the data will be written.
+    * A pointer `data` to the data that will be written to the file.
+    * `size` is the number of bytes to write from the provided data buffer.
+    * `operation` determines the type of file operation to perform (e.g., create, overwrite).
+    * 
+    * @return Returns the number of bytes successfully written. Returns 0 if the operation fails.
     */
    size_t writefile(const char* name, const char* data, size_t size, int operation = WIFI_FILE_WRITE);
-   
+
    /**
-    * Reads data from a file in the file system.
-    * It takes a `const char* name` parameter,
-    * which specifies the name of the file to be read.
+    * @brief Reads a file from the file system and prints its content.
+    * 
+    * It sends the read request to the modem, which fetches the data. The content 
+    * is printed to the serial output in chunks, with each chunk being processed 
+    * until the entire file is read. 
+    * 
+    * @param `name` is the name of the file to be read from the file system.
     */
    void readfile(const char* name);