API documentation

Author: BenjaminDannegard

.gitignore

@@ -9,3 +9,4 @@ cores/arduino/mydebug.cpp.donotuse
 .DS_Store?
 /.vs
 /.gitignore
+.vscode/settings.json

libraries/WiFiS3/src/Modem.h

@@ -18,28 +18,66 @@
 class ModemClass {
 
 public:
+  /** 
+   * 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 
+   * `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.
+   */
   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 
+   * 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,
+   * 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.
+   * Used for sending raw binary commands or data to the modem for operations that 
+   * require direct communication without any additional formatting or parsing.
+   */
   bool passthrough(const uint8_t *data, size_t size);
+
   void avoid_trim_results() {
     /* one shot - it works only 1 time the it is necessary to call again this
        funtion */
     trim_results = false;
   }
 
+
+  /**
+   * 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.
+   */
   void read_using_size() {
     read_by_size = true;
   } 
   bool beginned;
 
-  /* calling this function with no argument will enable debug message to be printed
+  /* Calling this function with no argument will enable debug message to be printed
      on Serial
      use first parameter UART *u to redirect debug output to a different serial 
 
@@ -54,15 +92,23 @@ class ModemClass {
     _debug_level = level;
   }
 
+  /**
+   * Used to disable debugging output for the modem communication.
+   */
   void noDebug() {
     _serial_debug = nullptr;
   }
 
+  /*NOT SURE*/
   #ifdef SELECTABLE_MODEM_DEBUG
   bool enable_dbg = false;
   void debug(bool e) {enable_dbg = e;}
   #endif
 
+  /**
+   * Sets the timeout value for communication operations.
+   * Can be called with a specified timeout value in milliseconds.
+   */
   void timeout(size_t timeout_ms) {_timeout = timeout_ms;}
 
 private:

libraries/WiFiS3/src/StringHelpers.h

@@ -5,6 +5,9 @@
 #include <vector>
 #include <algorithm>
 
+/**
+ * Trims whitespace characters from the beginning (left side) of the input string `s`.
+ */
 void ltrim(std::string &s);
 
 // trim from end (in place)
@@ -13,8 +16,16 @@ void rtrim(std::string &s);
 // trim from both ends (in place)
 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.
+ */
 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`.
+ */
 bool removeAtBegin(std::string &str, const std::string &what);
 
 #endif

libraries/WiFiS3/src/WiFiClient.h

@@ -38,17 +38,69 @@ class WiFiClient : public Client {
   WiFiClient(int s);
   WiFiClient(const WiFiClient& c);
   ~WiFiClient();
+
+  /**
+   * 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.
+   */
   virtual int connect(const char *host, uint16_t port);
+  
+  /** 
+   * 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
+   * and the size of the buffer `size` as parameters.
+   * 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.
+   */
   virtual int available();
+
+  /**
+   * 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.
+   */
   virtual int read(uint8_t *buf, size_t size);
+  
+  /**
+   * 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.
+   */
   virtual void flush();
+
+  /**
+   * Closes the connection to the remote server.
+   * Terminates the connection and release 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.
+   */
   virtual uint8_t connected();
+
   virtual operator bool() {
     return _sock != -1;
   }
@@ -57,9 +109,22 @@ class WiFiClient : public Client {
   {
       return !this->operator==(whs);
   };
+
+  /**
+   * 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.
+   */
   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.
+   */
   void setConnectionTimeout(int timeout) {
     _connectionTimeout = timeout;
   }

libraries/WiFiS3/src/WiFiFileSystem.h

@@ -27,9 +27,28 @@
 class WiFiFileSystem {
 
 public:
+   /**
+    * Initializes objects of the `WiFiFileSystem` class.
+    */
    WiFiFileSystem();
+
+   /**
+    * Mounts the file system.
+    * 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.
+    */
    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.
+    */
    void readfile(const char* name);
 
 };