docs(riot-rs): document Cargo features aimed at users

Cargo.toml

@@ -54,6 +54,7 @@ riot-rs-rt = { path = "src/riot-rs-rt" }
 riot-rs-runqueue = { path = "src/riot-rs-runqueue" }
 
 const_panic = { version = "0.2.8", default_features = false }
+document-features = "0.2.8"
 heapless = { version = "0.8.0", default-features = false }
 konst = { version = "0.3.8", default_features = false }
 ld-memory = { version = "0.2.9" }

src/riot-rs/Cargo.toml

@@ -8,6 +8,7 @@ edition.workspace = true
 workspace = true
 
 [dependencies]
+document-features = { workspace = true }
 linkme = { workspace = true }
 riot-rs-boards = { path = "../riot-rs-boards" }
 riot-rs-buildinfo = { path = "../riot-rs-buildinfo" }
@@ -32,21 +33,47 @@ riot-rs-rt = { path = "../riot-rs-rt", features = ["executor-single-thread"] }
 [features]
 default = ["riot-rs-rt/_panic-handler"]
 
-debug-console = ["riot-rs-rt/debug-console"]
-net = ["riot-rs-embassy/net"]
-# Allows to have no boards selected, useful to run platform-independent tooling
-no-boards = ["riot-rs-boards/no-boards"]
-override-network-config = ["riot-rs-embassy/override-network-config"]
-override-usb-config = ["riot-rs-embassy/override-usb-config"]
-silent-panic = ["riot-rs-rt/silent-panic"]
+#! ## Network type selection
+#! At most one of the features below can be enabled at once.
+## Selects Ethernet over USB (USB CDC-NCM).
+usb-ethernet = ["riot-rs-embassy/usb-ethernet"]
+## Selects Wi-Fi (with the CYW43 chip).
+wifi-cyw43 = ["riot-rs-embassy/wifi-cyw43"]
+## Selects Wi-Fi (on ESP chips).
+wifi-esp = ["riot-rs-embassy/wifi-esp"]
+
+#! ## Wired communication
+## Enables USB support.
+usb = ["riot-rs-embassy/usb"]
+
+#! ## System functionality
+## Enables threading support, see the [`macro@thread`] attribute macro.
 threading = [
   "dep:riot-rs-threads",
   "riot-rs-rt/threading",
   "riot-rs-embassy/threading",
 ]
+## Enables support for timeouts in the internal executor, e.g., required to use
+## `embassy_time::Timer`.
 time = ["riot-rs-embassy/time"]
-usb = ["riot-rs-embassy/usb"]
 
-usb-ethernet = ["riot-rs-embassy/usb-ethernet"]
-wifi-esp = ["riot-rs-embassy/wifi-esp"]
-wifi-cyw43 = ["riot-rs-embassy/wifi-cyw43"]
+#! ## System configuration
+#! The [`macro@config`] attribute macro allows to provide configuration for
+#! specific system functionality.
+#! The features below need to be enabled so that the provided custom
+#! configuration is taken into account.
+## Enables custom network configuration.
+override-network-config = ["riot-rs-embassy/override-network-config"]
+## Enables custom USB configuration.
+override-usb-config = ["riot-rs-embassy/override-usb-config"]
+
+#! ## Development and debugging
+## Enables the debug console, required to use
+## [`println!`](riot_rs_debug::println).
+debug-console = ["riot-rs-rt/debug-console"]
+## Prints nothing in case of panics (may help reduce binary size).
+silent-panic = ["riot-rs-rt/silent-panic"]
+## Allows to have no boards selected, useful to run target-independent tooling.
+no-boards = ["riot-rs-boards/no-boards"]
+
+net = ["riot-rs-embassy/net"]

src/riot-rs/src/lib.rs

@@ -1,8 +1,12 @@
 //! riot-rs
 //!
 //! This is a meta-package, pulling in the sub-crates of RIOT-rs.
+//!
+//! # Cargo features
+#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
 
 #![no_std]
+#![feature(doc_cfg)]
 
 pub use riot_rs_buildinfo as buildinfo;
 pub use riot_rs_debug as debug;
@@ -11,7 +15,8 @@ pub use riot_rs_rt as rt;
 
 // Attribute macros
 pub use riot_rs_macros::config;
-#[cfg(feature = "threading")]
+#[cfg(any(feature = "threading", doc))]
+#[doc(cfg(feature = "threading"))]
 pub use riot_rs_macros::thread;
 
 #[cfg(feature = "threading")]