From 6dd2fc59418c9d96f049f184694ddaf4845a4425 Mon Sep 17 00:00:00 2001
From: JuliDi <20155974+JuliDi@users.noreply.github.com>
Date: Fri, 28 Jul 2023 16:59:13 +0200
Subject: [PATCH] add document-features

---
 embassy-stm32/Cargo.toml | 54 +++++++++++++++++++++++++++++-----------
 embassy-stm32/src/lib.rs |  3 +++
 2 files changed, 42 insertions(+), 15 deletions(-)

diff --git a/embassy-stm32/Cargo.toml b/embassy-stm32/Cargo.toml
index 6f34c741..ba279f79 100644
--- a/embassy-stm32/Cargo.toml
+++ b/embassy-stm32/Cargo.toml
@@ -67,6 +67,7 @@ cfg-if = "1.0.0"
 embedded-io = { version = "0.4.0", features = ["async"], optional = true }
 chrono = { version = "^0.4", default-features = false, optional = true}
 bit_field = "0.10.2"
+document-features = "0.2.7"
 
 [dev-dependencies]
 critical-section = { version = "1.1", features = ["std"] }
@@ -78,40 +79,63 @@ stm32-metapac = { version = "13", default-features = false, features = ["metadat
 
 [features]
 default = ["rt"]
+
+## Enable `stm32-metapac`'s `rt` feature
 rt = ["stm32-metapac/rt"]
 
+## Use [`defmt`](https://docs.rs/defmt/latest/defmt/) for logging
 defmt = ["dep:defmt", "bxcan/unstable-defmt", "embassy-sync/defmt", "embassy-embedded-hal/defmt", "embassy-hal-internal/defmt", "embedded-io?/defmt", "embassy-usb-driver?/defmt", "embassy-net-driver/defmt"]
-memory-x = ["stm32-metapac/memory-x"]
+
 exti = []
 
-# Enables additional driver features that depend on embassy-time
+## Automatically generate `memory.x` file using [`stm32-metapac`](https://docs.rs/stm32-metapac/)
+memory-x = ["stm32-metapac/memory-x"]
+
+## Enable nightly-only features
+nightly = ["embedded-hal-1", "embedded-hal-async", "embedded-storage-async", "dep:embedded-io", "dep:embassy-usb-driver", "embassy-embedded-hal/nightly"]
+
+## Re-export stm32-metapac at `embassy_stm32::pac`.
+## This is unstable because semver-minor (non-breaking) releases of embassy-stm32 may major-bump (breaking) the stm32-metapac 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 = []
+
+## Implement embedded-hal 1.0 alpha traits.
+## Implement embedded-hal-async traits if `nightly` is set as well.
+unstable-traits = ["embedded-hal-1", "dep:embedded-hal-nb"]
+
+#! ## Time
+
+## Enables additional driver features that depend on embassy-time
 time = ["dep:embassy-time"]
 
 # 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.
 _time-driver = ["time"]
+
+## Use any time driver
 time-driver-any = ["_time-driver"]
+## Use TIM2 as time driver
 time-driver-tim2 = ["_time-driver"]
+## Use TIM3 as time driver
 time-driver-tim3 = ["_time-driver"]
+## Use TIM4 as time driver
 time-driver-tim4 = ["_time-driver"]
+## Use TIM5 as time driver
 time-driver-tim5 = ["_time-driver"]
+## Use TIM12 as time driver
 time-driver-tim12 = ["_time-driver"]
+## Use TIM15 as time driver
 time-driver-tim15 = ["_time-driver"]
 
-# Enable nightly-only features
-nightly = ["embedded-hal-1", "embedded-hal-async", "embedded-storage-async", "dep:embedded-io", "dep:embassy-usb-driver", "embassy-embedded-hal/nightly"]
 
-# Reexport stm32-metapac at `embassy_stm32::pac`.
-# This is unstable because semver-minor (non-breaking) releases of embassy-stm32 may major-bump (breaking) the stm32-metapac 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 = []
+#! ## Chip-selection features
+#! Select your chip by specifying the model as a feature, e.g. `stm32c011d6`.
+#! Check the `Cargo.toml` for the latest list of supported chips.
+#!
+#! **Important:** Do not forget to adapt the target chip in your toolchain,
+#! e.g. in `.cargo/config.toml`.
 
-# Implement embedded-hal 1.0 alpha traits.
-# Implement embedded-hal-async traits if `nightly` is set as well.
-unstable-traits = ["embedded-hal-1", "dep:embedded-hal-nb"]
-
-# Chip-selection features
 stm32c011d6 = [ "stm32-metapac/stm32c011d6" ]
 stm32c011f4 = [ "stm32-metapac/stm32c011f4" ]
 stm32c011f6 = [ "stm32-metapac/stm32c011f6" ]
@@ -1445,4 +1469,4 @@ stm32wle5cb = [ "stm32-metapac/stm32wle5cb" ]
 stm32wle5cc = [ "stm32-metapac/stm32wle5cc" ]
 stm32wle5j8 = [ "stm32-metapac/stm32wle5j8" ]
 stm32wle5jb = [ "stm32-metapac/stm32wle5jb" ]
-stm32wle5jc = [ "stm32-metapac/stm32wle5jc" ]
\ No newline at end of file
+stm32wle5jc = [ "stm32-metapac/stm32wle5jc" ]
diff --git a/embassy-stm32/src/lib.rs b/embassy-stm32/src/lib.rs
index bb2ef2fc..9e67596b 100644
--- a/embassy-stm32/src/lib.rs
+++ b/embassy-stm32/src/lib.rs
@@ -1,6 +1,9 @@
 #![cfg_attr(not(test), no_std)]
 #![cfg_attr(feature = "nightly", feature(async_fn_in_trait, impl_trait_projections))]
 
+//! ## Feature flags
+#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
+
 // This must go FIRST so that all the other modules see its macros.
 pub mod fmt;
 include!(concat!(env!("OUT_DIR"), "/_macros.rs"));