HAL: Serial: Update the header file doxy (FIXME)

Author: mprse

TESTS/mbed_hal_fpga_ci_test_shield/uart/uart_fpga_test.h

@@ -21,7 +21,7 @@
 #ifndef MBED_FPGA_UART_TEST_H
 #define MBED_FPGA_UART_TEST_H
 
-#if DEVICE_UART
+#if DEVICE_SERIAL
 
 #ifdef __cplusplus
 extern "C" {
@@ -35,7 +35,7 @@ extern "C" {
  * Then the operation is successfull.
  *
  */
-void fpga_uart_init_free_test(PinName tx, PinName rx, PinName cts, PinName rts);
+void fpga_uart_init_free_test(PinName tx, PinName rx, PinName cts = NC, PinName rts = NC);
 
 /** Test that the uart can be initialized/de-initialized using all possible
  *  uart pins (flow control disabled).
@@ -46,9 +46,6 @@ void fpga_uart_init_free_test(PinName tx, PinName rx, PinName cts, PinName rts);
  *
  */
 void fpga_uart_init_free_test_no_fc(PinName tx, PinName rx);
-{
-    fpga_uart_init_free_test(tx, rx);
-}
 
 /** Test that the uart transfer can be performed in various configurations (flow control enabled).
  *
@@ -57,7 +54,7 @@ void fpga_uart_init_free_test_no_fc(PinName tx, PinName rx);
  * Then data is successfully transfered.
  *
  */
-void fpga_uart_test_common(PinName tx, PinName rx, PinName cts, PinName rts);
+void fpga_uart_test_common(PinName tx, PinName rx, PinName cts = NC, PinName rts = NC);
 
 /** Test that the uart transfer can be performed in various configurations (flow control disabled).
  *
@@ -68,6 +65,8 @@ void fpga_uart_test_common(PinName tx, PinName rx, PinName cts, PinName rts);
  */
 void fpga_uart_test_common_no_fc(PinName tx, PinName rx);
 
+/* Common test function. */
+static void uart_test_common(int baudrate, int data_bits, SerialParity parity, int stop_bits, PinName tx, PinName rx, PinName cts = NC, PinName rts = NC);
 
 /**@}*/
 

hal/serial_api.h

@@ -112,20 +112,14 @@ extern "C" {
  * \defgroup hal_GeneralSerial Serial Configuration Functions
  *
  * # Defined behavior
- * * ::serial_init initializes the serial peripheral.
- * * ::serial_init sets the default parameters for serial peripheral
-        ^^^ FIXME, are the defaults given, or platform specific?
-            Set to 9600, 8N1? Use MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE?
-
- * * ::serial_init configures its specified pins.
- * * ::serial_free releases the serial peripheral.
+ * * ::serial_init initializes the ::serial_t
+ * * ::serial_init sets the default parameters for serial peripheral (9600 bps, 8N1 format)
+ * * ::serial_init configures the specified pins
+ * * ::serial_free releases the serial peripheral
  * * ::serial_baud configures the baud rate
- *      ^^^ FIXME, are any baudrates mandatory?
-
+ * * at least 9600 bps the baud rate  must be supported
  * * ::serial_format configures the transmission format (number of bits, parity and the number of stop bits)
-        ^^^ FIXME, which values are mandatory?
-            Any other than 8N1?
-
+ * * at least 8N1 format must be supported
  * * ::serial_irq_handler registers the interrupt handler which will be invoked when the interrupt fires.
  * * ::serial_irq_set enables or disables the serial RX or TX IRQ.
  * * If `RxIrq` is enabled by ::serial_irq_set, ::serial_irq_handler will be invoked whenever
@@ -140,10 +134,7 @@ extern "C" {
  * * ::serial_putc is a blocking call (waits for a peripheral to be available).
  * * ::serial_readable returns non-zero value if a character can be read, 0 otherwise.
  * * ::serial_writable returns non-zero value if a character can be written, 0 otherwise.
- * * ::serial_clear clears the serial peripheral
-        ^^^ FIXME, what does that actually mean?
-            Reset both RX and TX FIFOs (and shift registers)?
-
+ * * ::serial_clear clears the ::serial_t RX/TX buffers
  * * ::serial_break_set sets the break signal.
  * * ::serial_break_clear clears the break signal.
  * * ::serial_pinout_tx configures the TX pin as an output (to be used in half-duplex mode).
@@ -152,17 +143,13 @@ extern "C" {
  * otherwise software emulation is used.
  * * ::serial_tx_asynch starts the serial asynchronous transfer.
  * * ::serial_tx_asynch writes `tx_length` bytes from the `tx` to the bus.
- * * ::serial_tx_asynch ignores the `tx_width` argument
-        ^^^ FIXME, is this valid; does deprecated == ignored?
-
+ * * ::serial_tx_asynch must support 8 bits words
  * * The callback given to ::serial_tx_asynch is invoked when the transfer completes.
  * * ::serial_tx_asynch specifies the logical OR of events to be registered.
  * * The ::serial_tx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.
  * * ::serial_rx_asynch starts the serial asynchronous transfer.
  * * ::serial_rx_asynch reads `rx_length` bytes to the `rx` buffer.
- * * ::serial_rx_asynch ignores the `rx_width` argument
-        ^^^ FIXME, is this valid; does deprecated == ignored?
-
+ * * ::serial_rx_asynch must support 8 bits words
  * * The callback given to ::serial_rx_asynch is invoked when the transfer completes.
  * * ::serial_rx_asynch specifies the logical OR of events to be registered.
  * * The ::serial_rx_asynch function may use the `DMAUsage` hint to select the appropriate async algorithm.