Document the features of the remaining packages (#1143)

* Document features for `esp-riscv-rt` package

* Document features for `esp-hal-smartled`

* Document features for `esp-hal-procmacros`

esp-hal-procmacros/Cargo.toml

@@ -14,32 +14,48 @@ features = ["esp32c3", "embassy", "interrupt", "ram"]
 proc-macro = true
 
 [dependencies]
-darling          = "0.20.3"
-litrs            = "0.4.1"
-object           = { version = "0.32.1", optional = true }
-proc-macro-crate = "2.0.1"
-proc-macro-error = "1.0.4"
-proc-macro2      = "1.0.70"
-quote            = "1.0.33"
-syn              = { version = "2.0.40", features = ["extra-traits", "full"] }
+darling           = "0.20.3"
+document-features = "0.2.7"
+litrs             = "0.4.1"
+object            = { version = "0.32.1", optional = true }
+proc-macro-crate  = "2.0.1"
+proc-macro-error  = "1.0.4"
+proc-macro2       = "1.0.70"
+quote             = "1.0.33"
+syn               = { version = "2.0.40", features = ["extra-traits", "full"] }
 
 [features]
-# Select a target device:
-esp32       = []
-esp32c2     = []
-esp32c3     = []
-esp32c6     = ["dep:object"]
-esp32c6-lp  = []
-esp32h2     = []
-esp32p4     = []
-esp32s2     = ["dep:object"]
-esp32s2-ulp = []
-esp32s3     = ["dep:object"]
-esp32s3-ulp = []
-
-# Gated features:
-embassy       = []
+## Provide a `#[main]` procmacro to mark the entry point for Embassy applications.
+embassy = []
+## Provide enum dispatch helpers.
 enum-dispatch = []
-interrupt     = []
-ram           = []
-rtc_slow      = []
+## Provide an `#[interrupt]` procmacro for defining interrupt service routines.
+interrupt = []
+## Provide a `#[ram]` procmacro to place functions in RAM instead of flash.
+ram = []
+## Indicates the target devices has RTC slow memory available.
+rtc_slow = []
+
+#! ### Chip Support Feature Flags
+## Target the ESP32.
+esp32 = []
+## Target the ESP32-C2.
+esp32c2 = []
+## Target the ESP32-C3.
+esp32c3 = []
+## Target the ESP32-C6.
+esp32c6 = ["dep:object"]
+## Target the ESP32-C6's low-power core.
+esp32c6-lp = []
+## Target the ESP32-H2.
+esp32h2 = []
+## Target the ESP32-P4.
+esp32p4 = []
+## Target the ESP32-S2.
+esp32s2 = ["dep:object"]
+## Target the ESP32-S2's ultra-low-power core.
+esp32s2-ulp = []
+## Target the ESP32-S3.
+esp32s3 = ["dep:object"]
+## Target the ESP32-S3's ultra-low-power core.
+esp32s3-ulp = []

esp-hal-procmacros/src/lib.rs

@@ -70,7 +70,9 @@
 //! #[ram(rtc_fast, zeroed)]
 //! static mut SOME_ZEROED_DATA: [u8; 8] = [0; 8];
 //! ```
-
+//!
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
 #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 #[cfg(feature = "ram")]

esp-hal-smartled/Cargo.toml

@@ -9,22 +9,35 @@ license      = "MIT OR Apache-2.0"
 
 [package.metadata.docs.rs]
 features = ["esp32c3"]
+targets  = ["riscv32imc-unknown-none-elf"]
 
 [dependencies]
-defmt            = { version = "=0.3.5", optional = true }
-esp-hal          = { version = "0.15.0", path = "../esp-hal" }
-fugit            = "0.3.7"
-smart-leds-trait = "0.3.0"
+defmt             = { version = "=0.3.5", optional = true }
+document-features = "0.2.7"
+esp-hal           = { version = "0.15.0", path = "../esp-hal" }
+fugit             = "0.3.7"
+smart-leds-trait  = "0.3.0"
 
 [features]
+## Implement `defmt::Format` on certain types.
+defmt = ["dep:defmt", "esp-hal/defmt"]
+
+#! ### Chip Support Feature Flags
+## Target the ESP32.
 esp32   = ["esp-hal/esp32"]
+## Target the ESP32-C3.
 esp32c3 = ["esp-hal/esp32c3"]
+## Target the ESP32-C6.
 esp32c6 = ["esp-hal/esp32c6"]
+## Target the ESP32-H2.
 esp32h2 = ["esp-hal/esp32h2"]
+## Target the ESP32-S2.
 esp32s2 = ["esp-hal/esp32s2"]
+## Target the ESP32-S3.
 esp32s3 = ["esp-hal/esp32s3"]
 
+#! ### Crystal Frequency Feature Flags
+## Target device has a 26MHz crystal.
 xtal-26mhz = ["esp-hal/xtal-26mhz"]
+## Target device has a 40MHz crystal.
 xtal-40mhz = ["esp-hal/xtal-40mhz"]
-
-defmt = ["dep:defmt", "esp-hal/defmt"]

esp-hal-smartled/src/lib.rs

@@ -2,11 +2,11 @@
 //! with RGB LEDs and use the convenience functions of the
 //! [`smart-leds`](https://crates.io/crates/smart-leds) crate.
 //!
-//! _This is a simple implementation where every LED is adressed in an
+//! This is a simple implementation where every LED is adressed in an
 //! individual RMT operation. This is working perfectly fine in blocking mode,
 //! but in case this is used in combination with interrupts that might disturb
 //! the sequential sending, an alternative implementation (addressing the LEDs
-//! in a sequence in a single RMT send operation) might be required!_
+//! in a sequence in a single RMT send operation) might be required!
 //!
 //! ## Example
 //!
@@ -17,10 +17,12 @@
 //! let rmt_buffer = smartLedBuffer!(1);
 //! let mut led = SmartLedsAdapter::new(rmt.channel0, io.pins.gpio2, rmt_buffer);
 //! ```
-
-#![no_std]
-#![deny(missing_docs)]
+//!
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
 #![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
+#![deny(missing_docs)]
+#![no_std]
 
 use core::{fmt::Debug, slice::IterMut};
 

esp-riscv-rt/Cargo.toml

@@ -10,20 +10,36 @@ keywords     = ["esp32", "riscv", "runtime", "startup"]
 categories   = ["embedded", "no-std"]
 
 [dependencies]
-riscv           = "0.11.0"
-riscv-rt-macros = "0.2.1"
+document-features = "0.2.7"
+riscv             = "0.11.0"
+riscv-rt-macros   = "0.2.1"
 
 [features]
-direct-vectoring     = []
-fix-sp               = []
-has-mie-mip          = []
-init-data            = []
-init-rtc-fast-data   = []
-init-rtc-fast-text   = []
-init-rw-text         = []
+## Move the stack to the start of RAM to get zero-cost stack overflow
+## protection (ESP32-C6 and ESP32-H2 only!)
+fix-sp = []
+## Indicate that the device supports `mie` and `mip` instructions.
+has-mie-mip = []
+
+#! ### Memory Initialization Feature Flags
+## Initialize the `data` section.
+init-data = []
+## Initialize the `.rtc_fast.data` section.
+init-rtc-fast-data = []
+## Initialize the `.rtc_fast.text` section.
+init-rtc-fast-text = []
+## Initialize the `.rwtext` section.
+init-rw-text = []
+## Zero the `.bss` section.
+zero-bss = []
+## Zero the `.rtc_fast.bss` section.
+zero-rtc-fast-bss = []
+
+#! ### Interrupt Feature Flags
+## Enable direct interrupt vectoring.
+direct-vectoring = []
+## Enable interrupt preemption.
 interrupt-preemption = []
-zero-bss             = []
-zero-rtc-fast-bss    = []
 
 # This feature is intended for testing; you probably don't want to enable it:
 ci = [

esp-riscv-rt/src/lib.rs

@@ -1,14 +1,17 @@
-//! Minimal startup / runtime for RISC-V CPUs from Espressif
+//! Minimal startup/runtime for RISC-V CPUs from Espressif.
 //!
-//! # Features
+//! ## Features
 //!
 //! This crate provides:
 //!
 //! - Before main initialization of the `.bss` and `.data` sections controlled
 //!   by features
 //! - `#[entry]` to declare the entry point of the program
-
-// NOTE: Adapted from riscv-rt/src/lib.rs
+//!
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
+#![deny(missing_docs)]
 #![no_std]
 
 use core::arch::global_asm;