[stm32] Document UART buffer config transition

src/modm/platform/uart/stm32/module.lb

@@ -14,6 +14,25 @@
 
 props = {}
 
+descr_example = """
+```cpp
+using namespace modm::platform;
+// Using only hardware buffers for Tx and Rx (both 1 symbol)
+using UartN = BufferedUart<U(s)artHalN>;
+// using only TX software buffer
+using UartN = BufferedUart<U(s)artHalN, UartTxBuffer<512>>;
+// using only RX software buffer
+using UartN = BufferedUart<U(s)artHalN, UartRxBuffer<256>>;
+// using both TX and RX software buffers
+using UartN = BufferedUart<U(s)artHalN, UartTxBuffer<512>, UartRxBuffer<256>>;
+```
+"""
+
+descr_buffer = """
+The buffer configuration is now implemented in C++.
+Please replace any `modm::platform::U(s)artN` type with:
+""" + descr_example
+
 class Instance(Module):
     def __init__(self, driver, instance):
         self.driver = driver
@@ -27,6 +46,8 @@ class Instance(Module):
         module.description = "Instance {}".format(self.instance)
 
     def prepare(self, module, options):
+        module.add_alias(Alias(name="buffer.tx", description=descr_buffer))
+        module.add_alias(Alias(name="buffer.rx", description=descr_buffer))
         module.depends(":platform:uart")
         return True
 
@@ -55,7 +76,22 @@ class Instance(Module):
 
 def init(module):
     module.name = ":platform:uart"
-    module.description = "Universal Asynchronous Receiver Transmitter (UART)"
+    module.description = """
+# Universal Asynchronous Receiver Transmitter (UART)
+
+The UART buffer configuration is implemented as C++ template arguments:
+""" + descr_example + """
+
+## Using FreeRTOS buffers
+
+A special buffer implementation is available for FreeRTOS that uses the proper
+queue implementation to sleep and wake up the calling thread:
+
+```cpp
+// using both TX and RX software buffers
+using UartTxRxN = BufferedUart<U(s)artHalN, UartTxBufferFreeRtos<512>, UartRxBufferFreeRtos<256>>;
+```
+"""
 
 def prepare(module, options):
     device = options[":target"]