📝 Add docstrings to feat/error-reporting

include/avr/LegHandler.h

@@ -90,7 +90,13 @@ class LegHandler
     template <unsigned int N> void send(unsigned char identifier, const unsigned char (&data)[N])
     {
         static_assert(N <= 8U);
-        const unsigned char idByte{static_cast<unsigned char>((identifier & 0x3FU) | calcParity(identifier))};
+        /**
+     * Sends a LIN frame containing the specified payload.
+     *
+     * @param identifier LIN frame identifier.
+     * @param data Payload bytes to transmit; must contain at most eight bytes.
+     */
+    const unsigned char idByte{static_cast<unsigned char>((identifier & 0x3FU) | calcParity(identifier))};
         serialBreak();
         Serial.write(linSyncByte);
         Serial.write(idByte);
@@ -110,7 +116,14 @@ class LegHandler
     template <unsigned int N> [[nodiscard]] bool request(unsigned char identifier, unsigned char (&data)[N])
     {
         static_assert(N <= 8U);
-        const unsigned char idByte{static_cast<unsigned char>((identifier & 0x3FU) | calcParity(identifier))};
+        /**
+ * Requests a LIN frame and stores its payload in the provided buffer.
+ *
+ * @param identifier LIN frame identifier.
+ * @param data Buffer that receives the response payload; its size determines the expected payload length.
+ * @returns `true` if a valid response is received, `false` if the response times out or fails checksum validation.
+ */
+const unsigned char idByte{static_cast<unsigned char>((identifier & 0x3FU) | calcParity(identifier))};
         serialBreak();
         Serial.write(linSyncByte);
         Serial.write(idByte);

include/esp/ConsoleHandler.h

@@ -66,8 +66,8 @@ class ConsoleHandler
     Command commandTx{};
 
     /**
-     * State received from the console.
-     */
+ * Stores the state received from the console.
+ */
     State stateRx{};
 
     /**

src/avr/ConsoleHandler.cpp

@@ -6,9 +6,10 @@
 #include "avr/constants.h"
 
 /**
- * @brief Buffers a serial command and parses it when its complete payload is received.
+ * @brief Receives a serial command and parses it when its declared payload is complete.
  *
- * The first byte specifies the payload length and command identifier.
+ * The first byte encodes the payload length and command identifier. UART overrun and
+ * framing errors are reported through the console command channel.
  */
 void ConsoleHandler::handle()
 {

src/esp/ConsoleHandler.cpp

@@ -19,7 +19,7 @@ void ConsoleHandler::begin()
 }
 
 /**
- * @brief Processes available secondary-serial data, pending UART errors, or primary-serial input.
+ * @brief Processes a complete secondary-serial frame or forwards primary-serial input.
  */
 void ConsoleHandler::handle()
 {
@@ -73,9 +73,11 @@ void ConsoleHandler::forward()
 }
 
 /**
- * @brief Applies the buffered console frame to the corresponding device state.
+ * @brief Applies the buffered frame to the corresponding device state.
  *
- * Invalid command and payload-length combinations set the device status to red.
+ * Dispatches button, error, node, and preset data based on the frame state and
+ * payload length. Invalid state and payload-length combinations set the device
+ * status to red; invalid node payload lengths set the corresponding node error.
  */
 void ConsoleHandler::parse() const
 {
@@ -175,9 +177,9 @@ void ConsoleHandler::write(std::span<const uint8_t> payload)
 }
 
 /**
- * @brief Stores the latest hardware serial error for processing.
+ * @brief Records a hardware serial receive error in the desk state.
  *
- * @param error Hardware serial error to store.
+ * @param error Hardware serial receive error to record.
  */
 void ConsoleHandler::onReceiveError(hardwareSerial_error_t error)
 {

src/esp/DeskService.cpp

@@ -371,13 +371,21 @@ void DeskService::setDriveUp(bool state)
 #endif // PIN_TPUP
 }
 
+/**
+ * @brief Records an AVR error and activates the red status indicator.
+ */
 void DeskService::setErrorAvr()
 {
     avr = false;
     pending = true;
     statusRed();
 }
 
+/**
+ * @brief Updates the line communication error flags.
+ *
+ * @param flags New line communication error flags.
+ */
 void DeskService::setErrorLin(uint8_t flags)
 {
     if (flags != errorLin)
@@ -388,6 +396,9 @@ void DeskService::setErrorLin(uint8_t flags)
     statusRed();
 }
 
+/**
+ * @brief Records an error for node 8 and activates the red status indicator.
+ */
 void DeskService::setErrorNode8()
 {
     if (node8)
@@ -398,6 +409,9 @@ void DeskService::setErrorNode8()
     statusRed();
 }
 
+/**
+ * @brief Records an error for node 9 and activates the red status indicator.
+ */
 void DeskService::setErrorNode9()
 {
     if (node9)
@@ -408,6 +422,11 @@ void DeskService::setErrorNode9()
     statusRed();
 }
 
+/**
+ * @brief Records a serial receive error state and activates the red status indicator.
+ *
+ * @param flags Serial receive error flags.
+ */
 void DeskService::setErrorRx(hardwareSerial_error_t flags)
 {
     if (flags != errorRx)
@@ -418,6 +437,11 @@ void DeskService::setErrorRx(hardwareSerial_error_t flags)
     statusRed();
 }
 
+/**
+ * @brief Updates the transmit error flags and activates the red status indicator.
+ *
+ * @param flags Transmit error flags to record.
+ */
 void DeskService::setErrorTx(uint8_t flags)
 {
     if (flags != errorTx)
@@ -428,6 +452,15 @@ void DeskService::setErrorTx(uint8_t flags)
     statusRed();
 }
 
+/**
+ * @brief Updates node 8 position and motor state.
+ *
+ * Marks node 8 as available and schedules persistence or publication when its
+ * position or state changes.
+ *
+ * @param position Node 8 encoder position.
+ * @param state Node 8 motor state.
+ */
 void DeskService::setNode8(uint16_t position, uint8_t state)
 {
     if (position != encoder8 && state != state8)
@@ -461,6 +494,15 @@ void DeskService::setNode8(uint16_t position, uint8_t state)
     }
 }
 
+/**
+ * @brief Updates node 9's position and motor state.
+ *
+ * Marks node 9 as active and schedules persistence or publication when its
+ * position or state changes.
+ *
+ * @param position Node 9's encoder position.
+ * @param state Node 9's motor state.
+ */
 void DeskService::setNode9(uint16_t position, uint8_t state)
 {
     if (position != encoder9 && state != state9)
@@ -636,6 +678,11 @@ std::string DeskService::toHex(std::span<const uint8_t> payload)
     return hex;
 }
 
+/**
+ * @brief Appends active desk, node, USART, and UART errors to a JSON array.
+ *
+ * @param list JSON array to receive the error descriptions.
+ */
 void DeskService::toErrorArray(JsonArray &list)
 {
     if (!avr)
@@ -774,7 +821,9 @@ void DeskService::onInterruptDown()
 }
 
 /**
- * @brief Updates the reset state and status indicator from the reset input.
+ * @brief Updates reset state and clears communication errors when reset is asserted.
+ *
+ * @return None.
  */
 void DeskService::onInterruptReset()
 {

src/esp/HomeAssistantHandler.cpp

@@ -249,11 +249,10 @@ void HomeAssistantHandler::configuration()
 /**
  * @brief Configures diagnostic entities for Home Assistant discovery.
  *
- * Adds diagnostic controls and sensors for calibration, encoder data, firmware
- * versions, positional offset, serial activity, temperature, Wi-Fi signal
- * strength, and optionally button inputs and power-supply voltage. Diagnostic
- * entities are categorized and selected hardware-specific entities are disabled
- * by default.
+ * Adds diagnostic controls and sensors for calibration, errors, firmware updates,
+ * encoder position, positional offset, serial activity, temperature, Wi-Fi signal
+ * strength, and optionally button inputs and power-supply voltage. Selected
+ * diagnostic entities are disabled by default.
  */
 void HomeAssistantHandler::diagnostic()
 {