Finished API docs

libraries/WiFiS3/src/WiFiUdp.h

@@ -48,57 +48,212 @@ class WiFiUDP : public UDP {
   virtual void read_if_needed(size_t s);
 
 public:
-  WiFiUDP();  // Constructor
-  virtual uint8_t begin(uint16_t);	// initialize, start listening on specified port. Returns 1 if successful, 0 if there are no sockets available to use
+  /**
+   * @brief Default constructor for the WiFiUDP class.
+   */
+  WiFiUDP();
+
+  /**
+   * @brief Starts a UDP socket on the specified local port.
+   * 
+   * @param `uint16_t` The local port number to bind the UDP socket to.
+   * 
+   * @return Returns `1` if the socket is successfully opened, or 
+   * `0` if the socket is already in use or could not be opened.
+   */
+  virtual uint8_t begin(uint16_t);
+
+  /**
+   * @brief Starts a UDP socket bound to a specific IP address and port.
+   * 
+   * @param `a` The local IP address to bind the UDP socket to.
+   * @param `p` The local port number to bind the UDP socket to.
+   * 
+   * @return Returns `1` if the socket is successfully opened, or 
+   * `0` if the socket is already in use or could not be opened.
+   */
   virtual uint8_t begin(IPAddress a, uint16_t p);
-  virtual uint8_t beginMulticast(IPAddress, uint16_t);  // initialize, start listening on specified multicast IP address and port. Returns 1 if successful, 0 if there are no sockets available to use
-  virtual void stop();  // Finish with the UDP socket
+
+  /**
+   * @brief Starts a UDP multicast socket bound to a specific IP address and port.
+   * 
+   * @param `IPAddress` The multicast IP address to bind the UDP socket to.
+   * @param `uint16_t` The port number to bind the UDP socket to.
+   * 
+   * @return Returns `1` if the socket is successfully opened, or 
+   * `0` if the socket is already in use or could not be opened.
+   */
+  virtual uint8_t beginMulticast(IPAddress, uint16_t);
+
+  /**
+   * @brief Stops the UDP socket and releases its resources.
+   */
+  virtual void stop();
 
-  // Sending UDP packets
+  /**
+   * @brief Begins constructing a multicast UDP packet for sending.
+   * 
+   * @return Returns `1` if the packet preparation is successful.
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int beginMulticastPacket();
-  // Start building up a packet to send to the remote host specific in ip and port
-  // Returns 1 if successful, 0 if there was a problem with the supplied IP address or port
+
+  /**
+   * @brief Begins constructing a UDP packet for sending to a specific IP address and port.
+   * 
+   * @param `ip` The destination IP address as an `IPAddress` object.
+   * @param `port` The destination port number.
+   * 
+   * @return Returns `1` if the packet preparation is successful. 
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int beginPacket(IPAddress ip, uint16_t port);
-  // Start building up a packet to send to the remote host specific in host and port
-  // Returns 1 if successful, 0 if there was a problem resolving the hostname or port
+
+  /**
+   * @brief Begins constructing a UDP packet for sending to a specific hostname and port.
+   * 
+   * @param `host` The destination hostname as a null-terminated string.
+   * @param `port` The destination port number.
+   * 
+   * @return Returns `1` if the packet preparation is successful.
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int beginPacket(const char *host, uint16_t port);
-  // Finish off this packet and send it
-  // Returns 1 if the packet was sent successfully, 0 if there was an error
+
+  /**
+   * @brief Completes the construction of a UDP packet and sends it to the specified destination.
+   * 
+   * @return Returns `1` if the packet is successfully transmitted.
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int endPacket();
-  // Write a single byte into the packet
+
+  /**
+   * @brief Sends a single byte of data to the currently opened UDP packet.
+   * 
+   * @param `b` The byte of data to send.
+   * 
+   * @return Returns `1` if the byte was successfully written.
+   * Or `0` if there was an error or the packet was not properly initialized.
+   */
   virtual size_t write(uint8_t);
-  // Write size bytes from buffer into the packet
+
+  /**
+   * @brief Sends a buffer of data to the currently opened UDP packet.
+   * 
+   * @param `buffer` A pointer to the buffer containing the data to send.
+   * @param `size` The number of bytes from the buffer to write.
+   * 
+   * @return Returns the number of bytes successfully written if the operation is successful.
+   * Or `0` if the data was not successfully written, or if the packet was not properly initialized.
+   */
   virtual size_t write(const uint8_t *buffer, size_t size);
 
+  /**
+   * @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;
 
-  // Start processing the next available incoming packet
-  // Returns the size of the packet in bytes, or 0 if no packets are available
+  /** 
+   * @brief Start processing the next available incoming packet
+   * 
+   * @return Returns the size of the incoming packet, or `0` if no packet is available.
+   */
   virtual int parsePacket();
-  // Number of bytes remaining in the current packet
+
+  /** 
+   * @brief Checks if there are any available UDP packets to read.
+   * 
+   * @return Returns the number of available bytes if packets are available, or `0` if no packets are available.
+   */
   virtual int available();
-  // Read a single byte from the current packet
+
+  /** 
+   * @brief Read a single byte from the current packet
+   * 
+   * @return Returns the number of bytes read into the buffer, or `-1` if an error occurs.
+   */
   virtual int read();
-  // Read up to len bytes from the current packet and place them into buffer
-  // Returns the number of bytes read, or 0 if none are available
+
+  /** 
+   * @brief Reads data from the UDP receive buffer into a provided buffer.
+   * 
+   * @param `buffer` A pointer to the buffer where the received data will be stored.
+   * @param `size` The number of bytes to read from the UDP buffer.
+   * 
+   * @return The number of bytes successfully read into the buffer.
+   * If less than `size` bytes are read, it indicates that the buffer was exhausted early.
+   */
   virtual int read(unsigned char* buffer, size_t len);
-  // Read up to len characters from the current packet and place them into buffer
-  // Returns the number of characters read, or 0 if none are available
+
+
+  /** 
+   * @brief Reads data from the UDP receive buffer into a character buffer.
+   * 
+   * @param `buffer` A pointer to the character buffer where the received data will be stored.
+   * @param `len` The number of bytes to read from the UDP buffer.
+   * 
+   * @return The number of bytes successfully read into the buffer.
+   * If less than `len` bytes are read, it indicates that the buffer was exhausted early.
+   */
   virtual int read(char* buffer, size_t len) { return read((unsigned char*)buffer, len); };
-  // Return the next byte from the current packet without moving on to the next byte
+
+  /** 
+   * @brief Peeks at the next byte available in the UDP buffer without moving on to the next byte.
+   * 
+   * @return The value of the next byte in the UDP buffer, or `-1` if no data is available.
+   */
   virtual int peek();
+
+  /** 
+   * @brief Finish reading the current packet
+   */
   virtual void flush();	// Finish reading the current packet
+
+  /** 
+   * @brief Compares two WiFiUDP objects for equality.
+   * 
+   * This function compares two `WiFiUDP` objects by checking if their associated 
+   * socket values (`_sock`) are the same.
+   * 
+   * @param `WiFiUDP&` The WiFiUDP object to compare with the current object.
+   * 
+   * @return `true` if the socket values are equal, `false` otherwise.
+   */
   virtual bool operator==(const WiFiUDP&);
+
+  /** 
+   * @brief Compares two WiFiUDP objects for inequality.
+   * 
+   * This function compares two `WiFiUDP` objects by checking if their associated 
+   * socket values (`_sock`) are different.
+   * 
+   * @param `whs` The WiFiUDP object to compare with the current object.
+   * @return `true` if the socket values are different, `false` otherwise.
+   */
   virtual bool operator!=(const WiFiUDP& whs)
   {
     return !this->operator==(whs);
   };
 
-  // Return the IP address of the host who sent the current incoming packet
+  /** 
+   * @brief Retrieves the remote IP address of the host who sent the current incoming packet.
+   * 
+   * @return An `IPAddress` object representing the remote IP address. If the socket
+   * is not valid or the address cannot be retrieved, it returns `IPAddress(0, 0, 0, 0)`.
+   */
   virtual IPAddress remoteIP();
-  // Return the port of the host who sent the current incoming packet
+
+  /** 
+   * @brief Return the port of the host who sent the current incoming packet.
+   * 
+   * @return The remote port number as a `uint16_t`. If the socket is not valid or
+   * the port cannot be retrieved, it returns `0`.
+   */
   virtual uint16_t remotePort();
-
 
 };