Fixed wifi.h api docs

Author: BenjaminDannegard

libraries/WiFiS3/src/WiFi.h

@@ -33,7 +33,14 @@ class CAccessPoint {
 
 
 
-
+/**
+ * @brief Class to manage Wi-Fi connectivity and operations.
+ * 
+ * The `CWifi` class provides an interface to manage Wi-Fi operations such as connecting 
+ * to networks, setting up an access point, retrieving network information, and more. 
+ * It interfaces with a modem to execute commands related to Wi-Fi functionality and manages 
+ * connection settings such as IP address, DNS, and other network configurations.
+ */
 class CWifi {
 private: 
    void _config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1, IPAddress dns2);
@@ -206,148 +213,225 @@ class CWifi {
      */
     void end(void);
 
-    /*
-     * Get the interface MAC address.
-     *
-     * return: pointer to uint8_t array with length WL_MAC_ADDR_LENGTH
+
+    /**
+     * @brief Retrieves the MAC address of the device.
+     * 
+     * This function retrieves the MAC address of the device based on its current operating mode.
+     * The value returned by this function is meaningfull only if called afert a 
+     * begin (both begin or beginAP) or a ScanNetwork function otherwise 
+     * an empty mac address is returned.
      * 
-     * the value returned by this function is meaningfull only if called 
-     * afert a begin (both begin or beginAP) or a ScanNetwork function
-     * otherwise an empty mac address is returned
+     * @param `_mac` A pointer to a uint8_t array where the MAC address will be stored.
+     * 
+     * @return uint8_t* The pointer to the array containing the MAC address.
      */
     uint8_t* macAddress(uint8_t* mac);
 
-    /*
-     * Get the interface IP address.
-     *
-     * return: IP address value
+    /**
+     * @brief Retrieves the local IP address of the device.
+     * 
+     * This function retrieves the local IP address of the device. It checks the current mode (station or soft AP) 
+     * and retrieves the appropriate IP address based on the mode.
+     * 
+     * @return `IPAddress` The local IP address of the device.
      */
     IPAddress localIP();
 
-    /*
-     * Get the interface subnet mask address.
-     *
-     * return: subnet mask address value
+    /**
+     * @brief Retrieves the subnet mask of the device.
+     * 
+     * This function retrieves the subnet mask of the device by querying the modem for the subnet information. 
+     * It sends a command to the modem to fetch the subnet mask and returns it as an `IPAddress` object.
+     * 
+     * @return `IPAddress` The subnet mask address value of the device.
      */
     IPAddress subnetMask();
 
-    /*
-     * Get the gateway IP address.
-     *
-     * return: gateway IP address value
-     */
+   /**
+    * @brief Retrieves the gateway IP address of the device.
+    * 
+    * This function retrieves the gateway IP address of the device by querying the modem for the gateway 
+    * information. It sends a command to the modem to fetch the gateway IP address and returns it as an 
+    * `IPAddress` object.
+    * 
+    * @return `IPAddress` The gateway IP address value of the device.
+    */
    IPAddress gatewayIP();
 
+   /**
+    * @brief Retrieves the DNS IP address.
+    * 
+    * @param `n` The index of the DNS server to retrieve, `0` for the primary DNS server 
+    * and `1` for the secondary DNS server.
+    * 
+    * @return `IPAddress` The DNS IP address as an `IPAddress` object, or `0.0.0.0` if not found.
+    */
    IPAddress dnsIP(int n = 0);
 
-    /*
-     * Get the interface the AP IP address.
-     *
-     * return: IP address value
+
+    /**
+     * @brief Retrieves the IP address of the soft access point (AP).
+     * 
+     * @return `IPAddress` The IP address of the soft AP as an `IPAddress` object, or `0.0.0.0` if not found.
      */
     IPAddress softAPIP();
 
-    /*
-     * Return the current SSID associated with the network
-     *
-     * return: ssid string
+    /**
+     * @brief Retrieves the SSID of the current Wi-Fi connection or SoftAP.
+     * 
+     * @return The SSID of the current Wi-Fi connection or SoftAP as a string.
+     * If unable to retrieve the SSID, returns an empty string.
      */
     const char* SSID();
 
-    /*
-      * Return the current BSSID associated with the network.
-      *
-      * return: pointer to uint8_t array with length WL_MAC_ADDR_LENGTH
-      */
+    /**
+     * @brief Retrieves the BSSID (MAC address) of the currently connected Wi-Fi network.
+     * 
+     * @param `bssid` A pointer to an array where the BSSID will be stored. The array must be large enough to hold the MAC address.
+     * 
+     * @return A pointer to the `bssid` array containing the retrieved BSSID. If the BSSID cannot be retrieved, returns `nullptr`.
+     */
     uint8_t* BSSID(uint8_t* bssid);
 
-    /*
-      * Return the current RSSI/Received Signal Strength in dBm)
-      * associated with the network
-      *
-      * return: signed value
-      */
+    /**
+     * @brief Retrieves the RSSI (Received Signal Strength Indicator) of the currently connected Wi-Fi network.
+     * 
+     * @return The RSSI value representing the signal strength. A higher (less negative) value indicates a stronger signal.
+     * If the RSSI cannot be retrieved, returns 0.
+     */
     int32_t RSSI();
 
-    /*
-     * Return the current SSID associated with to the soft AP
-     *
-     * return: ssid string
+    /**
+     * @brief Retrieves the SSID (Service Set Identifier) of the SoftAP (Software Access Point) mode.
+     * 
+     * @return The SSID of the SoftAP. If the SSID cannot be retrieved, an empty string is returned.
      */
     const char* softAPSSID();
 
-
-    /*
-     * Start scan WiFi networks available
-     *
-     * return: Number of discovered networks
+    /**
+     * @brief Scans for available Wi-Fi networks and stores the information in the `access_points` list.
+     * 
+     * This function initiates a scan for nearby Wi-Fi networks and retrieves details such as SSID, BSSID, 
+     * RSSI (signal strength), channel, and encryption mode for each detected access point.
+     * 
+     * @return The number of networks found during the scan. Returns a negative value in case of an error.
      */
     int8_t scanNetworks();
 
-    /*
-     * Return the SSID discovered during the network scan.
-     *
-     * param networkItem: specify from which network item want to get the information
-    *
-     * return: SSID string of the specified item on the networks scanned list
+    /**
+     * @brief Retrieves the SSID of a specific Wi-Fi network from the scan results.
+     * 
+     * @param `networkItem` The index of the network in the list of scanned access points.
+     * 
+     * @return The SSID of the specified network, or `nullptr` if the index is out of bounds.
      */
     const char*   SSID(uint8_t networkItem);
 
-    /*
-     * Return the encryption type of the networks discovered during the scanNetworks
-     *
-     * param networkItem: specify from which network item want to get the information
-    *
-     * return: encryption type (enum wl_enc_type) of the specified item on the networks scanned list
-
-    
-      
+    /**
+     * @brief Returns the encryption type for a specified network.
+     * 
+     * This function retrieves the encryption type of a specific Wi-Fi access point
+     * based on its index in the list of scanned networks.
+     * 
+     * @param `networkItem` The index of the network in the list of available access points.
+     * 
+     * @return The encryption type in numeric form (e.g., 0 for no encryption, 
+     * 1 for WEP, 2 for WPA, etc.). Returns 0 if the network item index is invalid.
      */
     uint8_t encryptionType(uint8_t networkItem);
+
+    /**
+     * @brief Returns the encryption type of the currently connected Wi-Fi network.
+     * 
+     * @return The encryption type in numeric form (e.g., 0 for no encryption, 1 for WEP, 2 for WPA, etc.).
+     * Returns `ENC_TYPE_UNKNOWN` if the encryption type cannot be determined.
+     */
     uint8_t encryptionType();
 
+    /**
+     * @brief Retrieves the BSSID of a specific Wi-Fi network.
+     * 
+     * This function retrieves the BSSID (MAC address) of the Wi-Fi network at the specified
+     * index from the list of available networks. The BSSID is stored in the provided 
+     * array of 6 bytes.
+     * 
+     * @param `networkItem` The index of the Wi-Fi network in the list of available networks.
+     * @param `bssid` A pointer to a byte array (of size 6) where the BSSID will be stored.
+     * 
+     * @return A pointer to the `bssid` array if the BSSID is successfully retrieved, 
+     * or `nullptr` if the network index is out of range.
+     */
     uint8_t* BSSID(uint8_t networkItem, uint8_t* bssid);
+
+    /**
+     * @brief Retrieves the channel number of a specific Wi-Fi network.
+     * 
+     * @param `networkItem` The index of the Wi-Fi network in the list of available networks.
+     * 
+     * @return The channel number of the specified network, or `0` if the network index 
+     * is out of range.
+     */
     uint8_t channel(uint8_t networkItem);
 
-    /*
-     * Return the RSSI of the networks discovered during the scanNetworks
-     *
-     * param networkItem: specify from which network item want to get the information
-    *
-     * return: signed value of RSSI of the specified item on the networks scanned list
+    /**
+     * @brief Retrieves the RSSI (Received Signal Strength Indicator) of the networks discovered during the scanNetworks.
+     * 
+     * @param `networkItem` The index of the Wi-Fi network in the list of available networks.
+     * 
+     * @return The RSSI value of the specified network in dBm, or `-1000` if the network index 
+     * is out of range.
      */
     int32_t RSSI(uint8_t networkItem);
 
-    /*
-     * Return Connection status.
-     *
-     * return: one of the value defined in wl_status_t
+    /**
+     * @brief Retrieves the current connection status of the Wi-Fi connection.
+     * 
+     * @return One of the values defined in wl_status_t
      */
     uint8_t status();
 
-    /*
-     * Return The deauthentication reason code.
+    /**
+     * @brief Retrieves The deauthentication reason code.
      *
-     * return: the deauthentication reason code
+     * @return The deauthentication reason code.
      */
     uint8_t reasonCode();
 
-    /*
-     * Resolve the given hostname to an IP address.
-     * param aHostname: Name to be resolved
-     * param aResult: IPAddress structure to store the returned IP address
-     * result: 1 if aIPAddrString was successfully converted to an IP address,
-     *          else error code
+    /**
+     * @brief Resolves a hostname to an IP address.
+     * 
+     * @param `aHostname` The hostname to resolve (e.g., "www.example.com").
+     * @param `aResult` IPAddress structure to store the returned IP address result: 
+     * 1 if aIPAddrString was successfully converted to an IP address, else error code
+     * 
+     * @return Returns `1` if the hostname was successfully resolved, `0` otherwise.
      */
     int hostByName(const char* aHostname, IPAddress& aResult);
 
+    /**
+     * @brief Retrieves the current time from the modem.
+     * 
+     * @return The current time value in seconds, or `0` if the time could not be retrieved.
+     */
     unsigned long getTime();
 
+    /**
+     * @brief Sets the timeout value for the WiFi connection.
+     * 
+     * @param `timeout` The timeout value in milliseconds.
+     */
     void setTimeout(unsigned long timeout);
 
 
 };
 
+/**
+ * @brief Global instance of the CWifi class.
+ * 
+ * This external declaration provides access to a global instance of the `CWifi` class, which 
+ * facilitates interaction with the WiFi module.
+ */
 extern CWifi WiFi;
 
 

libraries/WiFiS3/src/WiFiUdp.h

@@ -30,6 +30,13 @@
 #include "Modem.h"
 #include "FifoBuffer.h"
 
+/**
+ * @brief A class for handling UDP communication over a Wi-Fi network.
+ * 
+ * The `WiFiUDP` class is an extension of the `UDP` class that enables sending and receiving UDP packets
+ * over a Wi-Fi network. It provides functions for initialization, packet transmission, and reception
+ * tailored for Wi-Fi connectivity.
+ */
 class WiFiUDP : public UDP {
 private:
   int _sock;