Improve documentation

Author: pschatzmann

ArduinoCore-Linux/cores/arduino/HardwareService.h

@@ -5,7 +5,7 @@
 namespace arduino {
 
 /**
- * We virtualize the hardware and send the requests and replys over
+ * @brief We virtualize the hardware and send the requests and replys over
  * a stream.
  *
  **/
@@ -68,9 +68,28 @@ enum HWCalls {
 };
 
 /**
- * Stream over which we tunnel the SPI, I2C, I2S and GPIO messages. Since most
- * embedded divices are little endian we communicate in little endian!
- **/
+ * @class HardwareService
+ * @brief Provides a virtualized hardware communication service for SPI, I2C, I2S, and GPIO over a stream.
+ *
+ * This class encapsulates the logic to tunnel hardware protocol messages (SPI, I2C, I2S, GPIO, Serial, etc.)
+ * over a generic stream interface. It handles serialization and deserialization of protocol calls and data,
+ * ensuring correct endianness (little endian by default for embedded devices). The class provides methods
+ * to send and receive various data types, manage the underlying stream, and perform byte-swapping as needed.
+ *
+ * Key features:
+ * - Tunnels hardware protocol messages over a stream (e.g., network, serial).
+ * - Supports sending and receiving multiple data types with correct endianness.
+ * - Provides blocking read with timeout for reliable communication.
+ * - Handles byte order conversion for cross-platform compatibility.
+ * - Can be used as a base for remote hardware emulation or proxying.
+ *
+ * Usage:
+ *   - Set the stream using setStream().
+ *   - Use send() methods to transmit protocol calls and data.
+ *   - Use receive methods to read responses from the remote hardware.
+ *   - Use flush() to ensure all data is sent.
+ *
+ */
 
 class HardwareService {
  public:

ArduinoCore-Linux/cores/arduino/HardwareSetupRemote.h

@@ -14,21 +14,40 @@
 namespace arduino {
 
 /**
- * Class which is used to configure the actual Hardware APIs
+ * @class HardwareSetupRemote
+ * @brief Configures and manages remote hardware interfaces for Arduino emulation.
+ *
+ * This class is responsible for setting up and managing remote hardware APIs such as I2C, SPI, and GPIO
+ * over a network or stream interface. It provides mechanisms to assign protocol handlers to a communication
+ * stream, perform handshakes with remote devices, and manage the lifecycle of hardware connections.
+ *
+ * Key features:
+ * - Supports initialization via a stream or UDP port.
+ * - Assigns remote protocol handlers (I2C, SPI, GPIO) to the provided stream.
+ * - Optionally sets up global protocol objects for use throughout the application.
+ * - Performs handshake with remote devices to ensure connectivity.
+ * - Provides accessors for the underlying protocol handler objects.
+ * - Manages cleanup and resource release on shutdown.
+ *
+ * Usage:
+ *   - Create an instance and call begin() with the desired configuration.
+ *   - Use getI2C(), getSPI(), and getGPIO() to access protocol handlers.
+ *   - Call end() to release resources when done.
+ *
  */
 
-class HardwareSetupRemoteClass : public I2CSource,
+class HardwareSetupRemote : public I2CSource,
                                  public SPISource,
                                  public GPIOSource {
  public:
   /// default constructor: you need to call begin() afterwards
-  HardwareSetupRemoteClass() = default;
+  HardwareSetupRemote() = default;
 
   /// HardwareSetup uses the indicated stream
-  HardwareSetupRemoteClass(Stream& stream) { begin(&stream, false); }
+  HardwareSetupRemote(Stream& stream) { begin(&stream, false); }
 
   /// HardwareSetup that uses udp
-  HardwareSetupRemoteClass(int port) { this->port = port; }
+  HardwareSetupRemote(int port) { this->port = port; }
 
   /// assigns the different protocols to the stream
   bool begin(Stream* s, bool asDefault = true, bool doHandShake = true) {
@@ -123,7 +142,7 @@ class HardwareSetupRemoteClass : public I2CSource,
 };
 
 #if !defined(SKIP_HARDWARE_SETUP)
-static HardwareSetupRemoteClass Remote{7000};
+static HardwareSetupRemote Remote{7000};
 #endif
 
 }  // namespace arduino