Merge pull request #4506 from PeterKietzmann/extend_uart_doc

periph/uart: extend uart API doc

drivers/include/periph/uart.h

@@ -12,6 +12,29 @@
  * @brief       Low-level UART peripheral driver
  * @{
  *
+ * This is a basic UART (Universal Asynchronous Receiver Transmitter) interface
+ * to allow platform independent access to the MCU's serial communication abilities.
+ * This interface is intentionally designed to be as simple as possible, to allow
+ * for easy implementation and maximum portability. In RIOT we only use the
+ * common 8-N-1 format of the serial port (8 data bist, no parity bit, one stop bit).
+ *
+ * The simple interface provides capabilities to initialize the serial communication
+ * module, which automatically enables for receiving data, as well as writing data
+ * to the UART port, which means transmitting data. The UART device and the
+ * corresponding pins need to be mapped in `RIOT/boards/ * /include/periph_conf.h`.
+ * Furthermore you need to select the baudrate for initialization which is typically
+ * {9600, 19200, 38400, 57600, 115200} baud. Additionally you should register a
+ * callback function that is executed in interrupt context when data is being received.
+ * The driver will then read the received data byte, call the registered callback
+ * function and pass the received data to it via its argument. The interface enforces
+ * the receiving to be impemented in an interrupt driven mode. Thus, you never now how
+ * many bytes are going to be received and might want to handle that in your specific
+ * callback function. The transmit function can be implemented in any way
+ *
+ * By default the @p UART_DEV(0) device of each board is initialized and mapped to STDIO
+ * in RIOT which is used for standard input/output functions like `printf()` or
+ * `puts()`.
+ *
  * @file
  * @brief       Low-level UART peripheral driver interface definition
  *