sys/stdio: better document configuration

maribu · crasbe · maribu · commit 3d5fad5aa1ed · 2025-05-01T11:54:15.000+02:00
This changes the documentation of how to configure stdio, especially
with regard on how to configure the stdio frontends with
`printf_float`, `printf_long_long`, and `stdin`.

Co-authored-by: crasbe &lt;crasbe@gmail.com&gt;
diff --git a/makefiles/pseudomodules.inc.mk b/makefiles/pseudomodules.inc.mk
@@ -342,20 +342,8 @@ PSEUDOMODULES += picolibc
 PSEUDOMODULES += picolibc_stdout_buffered
 PSEUDOMODULES += pktqueue
 PSEUDOMODULES += posix_headers
-## @defgroup sys_stdio_printf_float         Support for printing floats
-## @ingroup sys_stdio
-## @{
-## This module enables printing of floats, if the printf implementation has
-## configurable features.
 PSEUDOMODULES += printf_float
-## @}
-## @defgroup sys_stdio_printf_long_long     Support for printing long long
-## @ingroup sys_stdio
-## @{
-## This module enables printing of long long / unsigned long long, if the printf
-##  implementation has configurable features.
 PSEUDOMODULES += printf_long_long
-## @}
 PSEUDOMODULES += prng
 PSEUDOMODULES += prng_%
 PSEUDOMODULES += psa_riot_cipher_aes_common
diff --git a/sys/include/stdio_base.h b/sys/include/stdio_base.h
@@ -8,10 +8,7 @@
  */
 
 /**
- * @defgroup    sys_stdio STDIO abstraction
- * @ingroup     sys
- *
- * @brief       Simple standard input/output (STDIO) abstraction for RIOT
+ * @addtogroup  sys_stdio STDIO abstraction
  *
  * @{
  * @file
diff --git a/sys/stdio/doc.md b/sys/stdio/doc.md
@@ -0,0 +1,45 @@
+@defgroup       sys_stdio STDIO abstraction
+@ingroup        sys
+
+@brief          Simple standard input/output (STDIO) abstraction for RIOT
+
+# Abstract
+
+STDIO in RIOT is split into two parts: An interface to the stdio transports
+consisting mainly of @ref stdio_read and @ref stdio_write provided by RIOT,
+and the standard C stdio functions (such as `printf()`, `puts()`, `scanf()`)
+provided by the standard C library.
+
+## Configuring STDIO
+
+While the standard features for input and output are enabled by default, some
+additional features have to be enabled explicitly due to higher memory
+consumption. This includes the following features:
+
+| Module               | Features                                      |
+|:-------------------- |:--------------------------------------------- |
+| `printf_float`       | Support for printing floats/doubles           |
+| `printf_long_long`   | Support for printing (unsigned) long long     |
+| `stdin`              | Support for input (default is output only)    |
+
+The additional features can be enabled in the application Makefile:
+```Makefile
+USEMODULE += printf_float
+```
+
+@note   Modules that depend on a certain stdio feature will depend on that. E.g.
+        when using the @ref sys_shell module, the module `stdin` is
+        automatically used, as it is a dependency.
+
+## Enable STDIO Backends
+
+The various transports supported by RIOT are enabled by selecting the
+corresponding modules, such as @ref sys_stdio_uart, @ref usbus_cdc_acm_stdio,
+or @ref sys_stdio_rtt. All available options can are shown as mdoules in the
+list below.
+
+As with the additional features, you can specify the STDIO backend to be used in your application Makefile:
+
+```Makefile
+USEMODULE += stdio_cdc_acm
+```
