From 6f076db2bf07f4401ecc63102621215fc7d385c9 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 23:41:45 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`feat/er?= =?UTF-8?q?ror-reporting`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @JanPetterMG. * https://github.com/VIPnytt/Bekant/pull/47#issuecomment-5591699862 The following files were modified: * `include/avr/LegHandler.h` * `include/esp/ConsoleHandler.h` * `src/avr/ConsoleHandler.cpp` * `src/esp/ConsoleHandler.cpp` * `src/esp/DeskService.cpp` * `src/esp/HomeAssistantHandler.cpp` --- include/avr/LegHandler.h | 17 +++++++++-- include/esp/ConsoleHandler.h | 4 +-- src/avr/ConsoleHandler.cpp | 5 ++-- src/esp/ConsoleHandler.cpp | 12 ++++---- src/esp/DeskService.cpp | 51 +++++++++++++++++++++++++++++++- src/esp/HomeAssistantHandler.cpp | 9 +++--- 6 files changed, 81 insertions(+), 17 deletions(-) diff --git a/include/avr/LegHandler.h b/include/avr/LegHandler.h index 8b53153..da9a0e4 100644 --- a/include/avr/LegHandler.h +++ b/include/avr/LegHandler.h @@ -90,7 +90,13 @@ class LegHandler template void send(unsigned char identifier, const unsigned char (&data)[N]) { static_assert(N <= 8U); - const unsigned char idByte{static_cast((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((identifier & 0x3FU) | calcParity(identifier))}; serialBreak(); Serial.write(linSyncByte); Serial.write(idByte); @@ -110,7 +116,14 @@ class LegHandler template [[nodiscard]] bool request(unsigned char identifier, unsigned char (&data)[N]) { static_assert(N <= 8U); - const unsigned char idByte{static_cast((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((identifier & 0x3FU) | calcParity(identifier))}; serialBreak(); Serial.write(linSyncByte); Serial.write(idByte); diff --git a/include/esp/ConsoleHandler.h b/include/esp/ConsoleHandler.h index 53c9618..5dc7ddd 100644 --- a/include/esp/ConsoleHandler.h +++ b/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{}; /** diff --git a/src/avr/ConsoleHandler.cpp b/src/avr/ConsoleHandler.cpp index effb892..faf4084 100644 --- a/src/avr/ConsoleHandler.cpp +++ b/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() { diff --git a/src/esp/ConsoleHandler.cpp b/src/esp/ConsoleHandler.cpp index 1f4a9db..462cb0e 100644 --- a/src/esp/ConsoleHandler.cpp +++ b/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 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) { diff --git a/src/esp/DeskService.cpp b/src/esp/DeskService.cpp index a15a9f4..eab06b3 100644 --- a/src/esp/DeskService.cpp +++ b/src/esp/DeskService.cpp @@ -371,6 +371,9 @@ void DeskService::setDriveUp(bool state) #endif // PIN_TPUP } +/** + * @brief Records an AVR error and activates the red status indicator. + */ void DeskService::setErrorAvr() { avr = false; @@ -378,6 +381,11 @@ void DeskService::setErrorAvr() 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 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() { diff --git a/src/esp/HomeAssistantHandler.cpp b/src/esp/HomeAssistantHandler.cpp index dcbb7fc..8d664a0 100644 --- a/src/esp/HomeAssistantHandler.cpp +++ b/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() {