From 05c8d410a229f838c1acbe415f44f6f0574e1562 Mon Sep 17 00:00:00 2001
From: Barnaby Walters <barnaby@waterpigs.co.uk>
Date: Fri, 22 Dec 2023 23:37:29 +0100
Subject: [PATCH] [embassy-nrf] auto-documented features

---
 embassy-nrf/Cargo.toml | 63 +++++++++++++++++++++++++++---------------
 embassy-nrf/src/lib.rs |  3 ++
 2 files changed, 44 insertions(+), 22 deletions(-)

diff --git a/embassy-nrf/Cargo.toml b/embassy-nrf/Cargo.toml
index 970f62b0c..4648d56d9 100644
--- a/embassy-nrf/Cargo.toml
+++ b/embassy-nrf/Cargo.toml
@@ -17,6 +17,7 @@ flavors = [
 
 [features]
 default = ["rt"]
+## Cortex-M runtime (enabled by default)
 rt = [
     "nrf52805-pac?/rt",
     "nrf52810-pac?/rt",
@@ -30,45 +31,62 @@ rt = [
     "nrf9160-pac?/rt",
 ]
 
+## Enable features requiring `embassy-time`
 time = ["dep:embassy-time"]
 
+## Enable defmt
 defmt = ["dep:defmt", "embassy-hal-internal/defmt", "embassy-sync/defmt", "embassy-usb-driver/defmt", "embassy-embedded-hal/defmt"]
 
-# Reexport the PAC for the currently enabled chip at `embassy_nrf::pac`.
+## Reexport the PAC for the currently enabled chip at `embassy_nrf::pac` (unstable)
+unstable-pac = []
 # This is unstable because semver-minor (non-breaking) releases of embassy-nrf 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 = []
-
-nrf52805 = ["nrf52805-pac", "_nrf52"]
-nrf52810 = ["nrf52810-pac", "_nrf52"]
-nrf52811 = ["nrf52811-pac", "_nrf52"]
-nrf52820 = ["nrf52820-pac", "_nrf52"]
-nrf52832 = ["nrf52832-pac", "_nrf52", "_nrf52832_anomaly_109"]
-nrf52833 = ["nrf52833-pac", "_nrf52", "_gpio-p1"]
-nrf52840 = ["nrf52840-pac", "_nrf52", "_gpio-p1"]
-nrf5340-app-s = ["_nrf5340-app", "_s"]
-nrf5340-app-ns = ["_nrf5340-app", "_ns"]
-nrf5340-net = ["_nrf5340-net"]
-nrf9160-s = ["_nrf9160", "_s"]
-nrf9160-ns = ["_nrf9160", "_ns"]
 
+## Enable GPIO tasks and events
 gpiote = []
+
+## Use RTC1 as the time driver for `embassy-time`, with a tick rate of 32.768khz
 time-driver-rtc1 = ["_time-driver"]
 
-# Allow using the NFC pins as regular GPIO pins (P0_09/P0_10 on nRF52, P0_02/P0_03 on nRF53)
+## Allow using the NFC pins as regular GPIO pins (P0_09/P0_10 on nRF52, P0_02/P0_03 on nRF53)
 nfc-pins-as-gpio = []
 
-# Allow using the RST pin as a regular GPIO pin.
-# nrf52805, nrf52810, nrf52811, nrf52832: P0_21
-# nrf52820, nrf52833, nrf52840: P0_18
+## Allow using the RST pin as a regular GPIO pin.
+##  * nrf52805, nrf52810, nrf52811, nrf52832: P0_21
+##  * nrf52820, nrf52833, nrf52840: P0_18
 reset-pin-as-gpio = []
 
-# Implements the MultiwriteNorFlash trait for QSPI. Should only be enabled if your external
-# flash supports the semantics described in
-# https://docs.rs/embedded-storage/0.3.1/embedded_storage/nor_flash/trait.MultiwriteNorFlash.html
+## Implements the MultiwriteNorFlash trait for QSPI. Should only be enabled if your external
+## flash supports the semantics described [here](https://docs.rs/embedded-storage/0.3.1/embedded_storage/nor_flash/trait.MultiwriteNorFlash.html)
 qspi-multiwrite-flash = []
 
+#! ### Chip selection features
+## NRF52805
+nrf52805 = ["nrf52805-pac", "_nrf52"]
+## NRF52810
+nrf52810 = ["nrf52810-pac", "_nrf52"]
+## NRF52811
+nrf52811 = ["nrf52811-pac", "_nrf52"]
+## NRF52820
+nrf52820 = ["nrf52820-pac", "_nrf52"]
+## NRF52832
+nrf52832 = ["nrf52832-pac", "_nrf52", "_nrf52832_anomaly_109"]
+## NRF52833
+nrf52833 = ["nrf52833-pac", "_nrf52", "_gpio-p1"]
+## NRF52840
+nrf52840 = ["nrf52840-pac", "_nrf52", "_gpio-p1"]
+## NRF5340-app-s
+nrf5340-app-s = ["_nrf5340-app", "_s"]
+## NRF5340-app-ns
+nrf5340-app-ns = ["_nrf5340-app", "_ns"]
+## NRF5340-net
+nrf5340-net = ["_nrf5340-net"]
+## NRF9160-s
+nrf9160-s = ["_nrf9160", "_s"]
+## NRF9160-ns
+nrf9160-ns = ["_nrf9160", "_ns"]
+
 # Features starting with `_` are for internal use only. They're not intended
 # to be enabled by other crates, and are not covered by semver guarantees.
 
@@ -114,6 +132,7 @@ fixed = "1.10.0"
 embedded-storage = "0.3.1"
 embedded-storage-async = "0.4.0"
 cfg-if = "1.0.0"
+document-features = "0.2.7"
 
 nrf52805-pac = { version = "0.12.0", optional = true }
 nrf52810-pac = { version = "0.12.0", optional = true }
diff --git a/embassy-nrf/src/lib.rs b/embassy-nrf/src/lib.rs
index e3458e2de..1510b7265 100644
--- a/embassy-nrf/src/lib.rs
+++ b/embassy-nrf/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>"#)]
+
 #[cfg(not(any(
     feature = "nrf51",
     feature = "nrf52805",