Merge pull request #2350 from barnabywalters/rp-docs

[embassy-rp] auto-documented feature flags

2 files changed, 33 insertions, 15 deletions

diff --git a/embassy-rp/Cargo.toml b/embassy-rp/Cargo.toml
index 93dad68ce..669d79f40 100644
--- a/embassy-rp/Cargo.toml
+++ b/embassy-rp/Cargo.toml
@@ -14,43 +14,57 @@ flavors = [
 
 [features]
 default = [ "rt" ]
+## Enable the RP runtime.
 rt = [ "rp-pac/rt" ]
 
+## Enable defmt
 defmt = ["dep:defmt", "embassy-usb-driver/defmt", "embassy-hal-internal/defmt"]
 
-# critical section that is safe for multicore use
+## critical section that is safe for multicore use
 critical-section-impl = ["critical-section/restore-state-u8"]
 
-# Reexport the PAC for the currently enabled chip at `embassy_rp::pac`.
-# This is unstable because semver-minor (non-breaking) releases of embassy-rp may major-bump (breaking) the PAC version.
-# If this is an issue for you, you're encouraged to directly depend on a fixed version of the PAC.
-# There are no plans to make this stable.
+## Reexport the PAC for the currently enabled chip at `embassy_rp::pac`.
+## This is unstable because semver-minor (non-breaking) releases of embassy-rp may major-bump (breaking) the PAC version.
+## If this is an issue for you, you're encouraged to directly depend on a fixed version of the PAC.
+## There are no plans to make this stable.
 unstable-pac = []
 
+## Enable the timer for use with `embassy-time` with a 1MHz tick rate
 time-driver = []
 
+## Enable ROM function cache
 rom-func-cache = []
+## Enable intrinsics
 intrinsics = []
+## Enable ROM v2 intrinsics
 rom-v2-intrinsics = []
 
-# boot2 flash chip support. if none of these is enabled we'll default to w25q080 (used on the pico)
+## Allow using QSPI pins as GPIO pins. This is mostly not what you want (because your flash lives there)
+## and would add both code and memory overhead when enabled needlessly.
+qspi-as-gpio = []
+
+## Indicate code is running from RAM.
+## Set this if all code is in RAM, and the cores never access memory-mapped flash memory through XIP.
+## This allows the flash driver to not force pausing execution on both cores when doing flash operations.
+run-from-ram = []
+
+#! ### boot2 flash chip support
+#! If none of these are enabled, w25q080 is used by default (used on the pico)
+## AT25SF128a
 boot2-at25sf128a = []
+## GD25Q64cs
 boot2-gd25q64cs = []
+## generic-03h
 boot2-generic-03h = []
+## IS25LP080
 boot2-is25lp080 = []
+## ram-memcpy
 boot2-ram-memcpy = []
+## W25Q080
 boot2-w25q080 = []
+## W25X10cl
 boot2-w25x10cl = []
 
-# Allow using QSPI pins as GPIO pins. This is mostly not what you want (because your flash lives there)
-# and would add both code and memory overhead when enabled needlessly.
-qspi-as-gpio = []
-
-# Indicate code is running from RAM.
-# Set this if all code is in RAM, and the cores never access memory-mapped flash memory through XIP.
-# This allows the flash driver to not force pausing execution on both cores when doing flash operations.
-run-from-ram = []
-
 [dependencies]
 embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
 embassy-time = { version = "0.2", path = "../embassy-time", features = [ "tick-hz-1_000_000" ] }
@@ -85,6 +99,7 @@ embedded-hal-nb = { version = "=1.0.0-rc.3" }
 pio-proc = {version= "0.2" }
 pio = {version= "0.2.1" }
 rp2040-boot2 = "0.3"
+document-features = "0.2.7"
 
 [dev-dependencies]
 embassy-executor = { version = "0.4.0", path = "../embassy-executor", features = ["arch-std", "executor-thread"] }
diff --git a/embassy-rp/src/lib.rs b/embassy-rp/src/lib.rs
index fdacf4965..0a3714777 100644
--- a/embassy-rp/src/lib.rs
+++ b/embassy-rp/src/lib.rs
@@ -3,6 +3,9 @@
 #![doc = include_str!("../README.md")]
 #![warn(missing_docs)]
 
+//! ## Feature flags
+#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
+
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;