add render-documentation workflow

Author: leonardocavagnis

.github/workflows/render-documentation.yml

@@ -0,0 +1,28 @@
+name: Render Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/render-documentation.ya?ml"
+      - "examples/**"
+      - "src/**"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/render-documentation.ya?ml"
+      - "examples/**"
+      - "src/**"
+  workflow_dispatch:
+      
+jobs:
+  render-docs:
+    permissions:
+      contents: write
+    uses: arduino/render-docs-github-action/.github/workflows/render-docs.yml@main
+    with:
+      source-path: './src'
+      target-path: './docs/api.md'
+      fail-on-warnings: false

src/Arduino_10BASE_T1S_PHY_Interface.h

@@ -29,6 +29,19 @@ class Arduino_10BASE_T1S_PHY_Interface
 public:
   virtual ~Arduino_10BASE_T1S_PHY_Interface() { }
 
+  /**
+   * @brief Initializes the PHY interface with the specified network settings.
+   *
+   * This method configures the PHY interface with the provided IP address,
+   * network mask, gateway, MAC address, and PLCA settings.
+   *
+   * @param ip_addr The IP address to assign to the interface.
+   * @param network_mask The network mask to use.
+   * @param gateway The gateway IP address.
+   * @param mac_addr The MAC address to assign to the interface.
+   * @param t1s_plca_settings The PLCA settings to use.
+   * @return Returns true if the initialization was successful, false otherwise.
+   */
   virtual bool begin(IPAddress const ip_addr,
                      IPAddress const network_mask,
                      IPAddress const gateway,

src/Arduino_10BASE_T1S_UDP.h

@@ -36,32 +36,174 @@
 class Arduino_10BASE_T1S_UDP : public UDP
 {
 public:
+  /**
+   * @class Arduino_10BASE_T1S_UDP
+   * @brief UDP communication class for Arduino 10BASE-T1S library.
+   */
            Arduino_10BASE_T1S_UDP();
   virtual ~Arduino_10BASE_T1S_UDP();
 
 
   /* arduino:UDP */
+  /**
+   * @brief Initializes the UDP instance to listen on the specified port.
+   *
+   * This method sets up the UDP protocol to begin listening for incoming packets
+   * on the given port. It should be called before attempting to send or receive
+   * UDP packets.
+   *
+   * @param port The local port to listen on.
+   * @return Returns 1 if successful, 0 if there was an error.
+   */
   virtual uint8_t begin(uint16_t port) override;
+
+
+  /**
+   * @brief Stops the UDP connection and releases any associated resources.
+   *
+   * This method overrides the base class implementation to properly close
+   * the UDP socket and perform necessary cleanup operations.
+   */
   virtual void stop() override;
 
+  /**
+   * @brief Begins the construction of a UDP packet to the specified IP address and port.
+   *
+   * Initializes the UDP packet buffer and prepares it to send data to the given destination.
+   *
+   * @param ip The destination IP address.
+   * @param port The destination port number.
+   * @return int Returns 1 on success, 0 on failure.
+   */
   virtual int beginPacket(IPAddress ip, uint16_t port) override;
+
+  /**
+   * @brief Begins the construction of a UDP packet to the specified host and port.
+   *
+   * Initializes the UDP packet buffer and prepares it to send data to the given destination.
+   *
+   * @param host The destination host name or IP address as a string.
+   * @param port The destination port number.
+   * @return int Returns 1 on success, 0 on failure.
+   */
   virtual int beginPacket(const char *host, uint16_t port) override;
+
+  /**
+   * @brief Finishes the construction of a UDP packet and sends it.
+   *
+   * This method finalizes the UDP packet and transmits it to the previously specified
+   * destination IP address and port.
+   *
+   * @return int Returns 1 on success, 0 on failure.
+   */
   virtual int endPacket() override;
+  
+  /**
+   * @brief Sends a single byte of data in the current UDP packet.
+   *
+   * This method appends a single byte to the current UDP packet buffer.
+   *
+   * @param data The byte of data to send.
+   * @return size_t Returns the number of bytes written, which is always 1 for a single byte.
+   */
   virtual size_t write(uint8_t data) override;
+  
+  /**
+   * @brief Sends a buffer of data in the current UDP packet.
+   *
+   * This method appends a specified number of bytes from the provided buffer to the
+   * current UDP packet buffer.
+   *
+   * @param buffer Pointer to the data buffer to send.
+   * @param size The number of bytes to write from the buffer.
+   * @return size_t Returns the number of bytes written, which may be less than size if an error occurs.
+   */
   virtual size_t write(const uint8_t * buffer, size_t size) override;
 
+  /**
+   * @brief Sends a string in the current UDP packet.
+   *
+   * This method appends a null-terminated string to the current UDP packet buffer.
+   *
+   * @param str Pointer to the null-terminated string to send.
+   * @return size_t Returns the number of bytes written, including the null terminator.
+   */
   virtual int parsePacket() override;
+  
+  /**
+   * @brief Checks if there are any incoming UDP packets available to read.
+   *
+   * This method checks the internal buffer for any received UDP packets.
+   *
+   * @return int Returns the number of available bytes in the current packet, or 0 if no packets are available.
+   */
   virtual int available() override;
+  
+  /**
+   * @brief Reads a single byte from the current UDP packet.
+   *
+   * This method retrieves the next byte from the current UDP packet buffer.
+   *
+   * @return int Returns the byte read, or -1 if no data is available.
+   */
   virtual int read() override;
+  
+  /**
+   * @brief Reads a specified number of bytes from the current UDP packet into a buffer.
+   *
+   * This method reads data from the current UDP packet into the provided buffer.
+   *
+   * @param buffer Pointer to the buffer where the data will be stored.
+   * @param len The number of bytes to read into the buffer.
+   * @return int Returns the number of bytes read, which may be less than len if not enough data is available.
+   */
   virtual int read(unsigned char* buffer, size_t len) override;
+  
+  /**
+   * @brief Reads a specified number of bytes from the current UDP packet into a character buffer.
+   *
+   * This method reads data from the current UDP packet into the provided character buffer.
+   *
+   * @param buffer Pointer to the character buffer where the data will be stored.
+   * @param len The number of bytes to read into the buffer.
+   * @return int Returns the number of bytes read, which may be less than len if not enough data is available.
+   */
   virtual int read(char* buffer, size_t len) override;
+  
+  /**
+   * @brief Peeks at the next byte in the current UDP packet without removing it from the buffer.
+   *
+   * This method retrieves the next byte from the current UDP packet buffer without consuming it.
+   *
+   * @return int Returns the next byte, or -1 if no data is available.
+   */
   virtual int peek() override;
+  
+  /**
+   * @brief Flushes the current UDP packet buffer.
+   *
+   * This method clears the current UDP packet buffer, discarding any unsent data.
+   */
   virtual void flush() override;
 
+  /**
+   * @brief Returns the IP address of the remote host that sent the last received packet.
+   *
+   * This method retrieves the IP address of the sender of the last received UDP packet.
+   *
+   * @return IPAddress Returns the IP address of the remote host.
+   */
   virtual IPAddress remoteIP() override;
+  
+  /**
+   * @brief Returns the port number of the remote host that sent the last received packet.
+   *
+   * This method retrieves the port number of the sender of the last received UDP packet.
+   *
+   * @return uint16_t Returns the port number of the remote host.
+   */
   virtual uint16_t remotePort() override;
 
-
   /* This function MUST not be called from the user of this library,
    * it's used for internal purposes only.
    */

src/microchip/TC6_Arduino_10BASE_T1S.h

@@ -74,11 +74,31 @@ enum class DIO { A0, A1 };
 class TC6_Arduino_10BASE_T1S : public Arduino_10BASE_T1S_PHY_Interface
 {
 public:
+  /**
+   * @class TC6_Arduino_10BASE_T1S
+   * @brief Arduino 10BASE-T1S PHY interface implementation using TC6.
+   *
+   * This class provides the implementation of the Arduino_10BASE_T1S_PHY_Interface
+   * using the TC6 hardware abstraction layer for 10BASE-T1S communication.
+   */
   TC6_Arduino_10BASE_T1S(TC6_Io & tc6_io);
 
   virtual ~TC6_Arduino_10BASE_T1S();
 
-
+  /**
+   * @brief Initializes the TC6 Arduino 10BASE-T1S PHY interface with the specified network settings.
+   *
+   * This method configures the TC6 interface with the provided IP address,
+   * network mask, gateway, MAC address, and PLCA settings.
+   *
+   * @param ip_addr The IP address to assign to the interface.
+   * @param network_mask The network mask to use.
+   * @param gateway The gateway IP address.
+   * @param mac_addr The MAC address to assign to the interface.
+   * @param t1s_plca_settings The PLCA settings to use.
+   * @param t1s_mac_settings The MAC settings to use.
+   * @return Returns true if the initialization was successful, false otherwise.
+   */
   virtual bool begin(IPAddress const ip_addr,
                      IPAddress const network_mask,
                      IPAddress const gateway,
@@ -88,15 +108,37 @@ class TC6_Arduino_10BASE_T1S : public Arduino_10BASE_T1S_PHY_Interface
 
 
   virtual void service() override;
-
+  
   void digitalWrite(DIO const dio, bool const value);
 
+  /**
+   * @brief Gets the PLCA status.
+   *
+   * This method retrieves the current PLCA status from the TC6 hardware.
+   *
+   * @param on_plca_status Callback function to handle the PLCA status.
+   * @return bool Returns true if the PLCA status was successfully retrieved, false otherwise.
+   */
   bool getPlcaStatus(TC6LwIP_On_PlcaStatus on_plca_status);
+  /**
+   * @brief Enables PLCA (Physical Layer Collision Avoidance).
+   *
+   * This method enables the PLCA functionality on the TC6 hardware.
+   *
+   * @return bool Returns true if PLCA was successfully enabled, false otherwise.
+   */
   bool enablePlca();
 
+  /**
+   * @brief Checks if sending data would block.
+   *
+   * This method checks if the TC6 hardware is currently able to send data
+   * without blocking.
+   *
+   * @return bool Returns true if sending data would block, false otherwise.
+   */
   bool sendWouldBlock();
 
-
 private:
   TC6_Io & _tc6_io;
   TC6LwIP_t _lw;