From 7161fca7f807e1b20798c126c38b3ab4f2fcbadc Mon Sep 17 00:00:00 2001
From: ROMemories <romain.fouquet@inria.fr>
Date: Fri, 15 Mar 2024 09:37:55 +0100
Subject: [PATCH] docs(riot-rs): document Cargo features aimed at users

---
 Cargo.lock             |  1 +
 Cargo.toml             |  1 +
 src/riot-rs/Cargo.toml | 49 ++++++++++++++++++++++++++++++++----------
 src/riot-rs/src/lib.rs |  7 +++++-
 4 files changed, 46 insertions(+), 12 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 88de0d0de..7cea52797 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2321,6 +2321,7 @@ dependencies = [
 name = "riot-rs"
 version = "0.1.0"
 dependencies = [
+ "document-features",
  "linkme",
  "riot-rs-boards",
  "riot-rs-buildinfo",
diff --git a/Cargo.toml b/Cargo.toml
index 6ec189f79..240978b95 100644
--- a/Cargo.toml
+++ b/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" }
diff --git a/src/riot-rs/Cargo.toml b/src/riot-rs/Cargo.toml
index 3570bf503..d48ae8513 100644
--- a/src/riot-rs/Cargo.toml
+++ b/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"]
diff --git a/src/riot-rs/src/lib.rs b/src/riot-rs/src/lib.rs
index bf8b48c27..5fe3bc74d 100644
--- a/src/riot-rs/src/lib.rs
+++ b/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")]