From ba079bd7992905777170365878013c025602467e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niccol=C3=B2=20Betto?= <niccolo.betto@skywarder.eu>
Date: Sat, 18 Jan 2025 13:19:53 +0100
Subject: [PATCH] [USART] Improve documentation of internal queue

Behavior of the read function when the requested size if larger than the internal queue length has been specified.
---
 src/shared/drivers/usart/USART.cpp | 4 ++--
 src/shared/drivers/usart/USART.h   | 9 +++++++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/shared/drivers/usart/USART.cpp b/src/shared/drivers/usart/USART.cpp
index ad6203c70..846d2219a 100644
--- a/src/shared/drivers/usart/USART.cpp
+++ b/src/shared/drivers/usart/USART.cpp
@@ -594,9 +594,9 @@ void USART::writeString(const char* buffer)
 
 void USART::clearQueue()
 {
-    char buf[usart_queue_default_capacity];
+    char buf[INTERNAL_QUEUE_LENGTH];
     rxQueue.reset();
-    while (read(buf, usart_queue_default_capacity))
+    while (read(buf, INTERNAL_QUEUE_LENGTH))
         ;
     rxQueue.reset();
 }
diff --git a/src/shared/drivers/usart/USART.h b/src/shared/drivers/usart/USART.h
index 707e23d6b..1e0f378ad 100644
--- a/src/shared/drivers/usart/USART.h
+++ b/src/shared/drivers/usart/USART.h
@@ -196,13 +196,18 @@ public:
      * no control flow and no oversampling).
      * Requires that the gpios are configured for the choosen uart.
      *
+     * @note An internal queue is used to store the received data, before the
+     * user reads it. Reading more data than the queue capacity is allowed, but
+     * only up to the internal queue capacity will be returned.
+     *
      * @param usart structure that represents the usart peripheral [accepted
      * are: USART1, USART2, USART3, UART4, UART5, USART6, UART7, UART8].
      * @param baudrate Baudrate in bit per second. Default values are [2400,
      * 9600, 19200, 38400, 57600, 115200, 230400, 256000, 460800, 921600]
+     * @param queueLen Length of the internal queue for the received data.
      */
     USART(USARTType* usart, int baudrate,
-          unsigned int queueLen = usart_queue_default_capacity);
+          unsigned int queueLen = INTERNAL_QUEUE_LENGTH);
 
     ///< Delete copy/move constructors/operators.
     USART(const USART&)            = delete;
@@ -337,7 +342,7 @@ private:
     bool error            = false;  ///< Error occurred while receiving message
 
     ///< Default queue length
-    const static unsigned int usart_queue_default_capacity = 256;
+    static constexpr unsigned int INTERNAL_QUEUE_LENGTH = 256;
 };
 
 /**
-- 
GitLab