Minor documentation improvements (#460)

* Add README, improve documentation for `esp-hal-procmacros` * Improve documentation for `esp-hal-smartled` * Use esp-rs logo for all packages' documentation
esp-rs · Mar 30, 2023 · a910402 · a910402
1 parent a677abd
commit a910402
Show file tree

Hide file tree

Showing 12 changed files with 71 additions and 8 deletions.
diff --git a/esp-hal-common/src/lib.rs b/esp-hal-common/src/lib.rs
@@ -28,6 +28,7 @@
     feature(async_fn_in_trait),
     feature(impl_trait_projections)
 )]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 #[cfg(riscv)]
 pub use esp_riscv_rt::{self, entry, riscv};

diff --git a/esp-hal-procmacros/Cargo.toml b/esp-hal-procmacros/Cargo.toml
@@ -11,6 +11,9 @@ description  = "Procedural macros for ESP-HAL"
 repository   = "https://github.com/esp-rs/esp-hal"
 license      = "MIT OR Apache-2.0"
 
+[package.metadata.docs.rs]
+features = ["esp32c3", "interrupt", "riscv"]
+
 [lib]
 proc-macro = true
 

diff --git a/esp-hal-procmacros/README.md b/esp-hal-procmacros/README.md
@@ -0,0 +1,27 @@
+# esp-hal-procmacros
+
+[![Crates.io](https://img.shields.io/crates/v/esp-hal-procmacros?labelColor=1C2C2E&color=C96329&logo=Rust&style=flat-square)](https://crates.io/crates/esp-hal-procmacros)
+[![docs.rs](https://img.shields.io/docsrs/esp-hal-procmacros?labelColor=1C2C2E&color=C96329&logo=rust&style=flat-square)](https://docs.rs/esp-hal-procmacros)
+![Crates.io](https://img.shields.io/crates/l/esp-hal-procmacros?labelColor=1C2C2E&style=flat-square)
+[![Matrix](https://img.shields.io/matrix/esp-rs:matrix.org?label=join%20matrix&labelColor=1C2C2E&color=BEC5C9&logo=matrix&style=flat-square)](https://matrix.to/#/#esp-rs:matrix.org)
+
+Procedural macros for placing statics and functions into RAM, and for marking interrupt handlers.
+
+## [Documentation]
+
+[documentation]: https://docs.rs/esp-hal-procmacros/
+
+## License
+
+Licensed under either of:
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
+the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
+any additional terms or conditions.
diff --git a/esp-hal-procmacros/src/lib.rs b/esp-hal-procmacros/src/lib.rs
@@ -1,3 +1,8 @@
+//! Procedural macros for placing statics and functions into RAM, and for
+//! marking interrupt handlers.
+
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
+
 use darling::FromMeta;
 use proc_macro::{self, Span, TokenStream};
 use proc_macro_error::{abort, proc_macro_error};
@@ -39,7 +44,6 @@ struct RamArgs {
 /// (e.g. to persist it across resets or deep sleep mode for the RTC RAM)
 ///
 /// Not all targets support RTC slow ram.
-
 #[proc_macro_attribute]
 #[proc_macro_error]
 pub fn ram(args: TokenStream, input: TokenStream) -> TokenStream {
@@ -414,6 +418,7 @@ impl Parse for MakeGpioEnumDispatchMacro {
     }
 }
 
+/// Create an enum for erased GPIO pins, using the enum-dispatch pattern
 #[proc_macro]
 pub fn make_gpio_enum_dispatch_macro(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as MakeGpioEnumDispatchMacro);

diff --git a/esp-hal-smartled/Cargo.toml b/esp-hal-smartled/Cargo.toml
@@ -6,6 +6,9 @@ description = "RMT adapter for smartleds"
 repository  = "https://github.com/esp-rs/esp-hal"
 license     = "MIT OR Apache-2.0"
 
+[package.metadata.docs.rs]
+features = ["esp32c3"]
+
 [dependencies]
 esp-hal-common   = { version = "0.8.0", path = "../esp-hal-common" }
 fugit            = "0.3.6"

diff --git a/esp-hal-smartled/src/lib.rs b/esp-hal-smartled/src/lib.rs
@@ -1,5 +1,3 @@
-//! # Smart-LEDs RMT Adapter
-//!
 //! This adapter allows for the use of an RMT output channel to easily interact
 //! with RGB LEDs and use the convenience functions of the
 //! [`smart-leds`](https://crates.io/crates/smart-leds) crate.
@@ -9,9 +7,27 @@
 //! 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!_
+//!
+//! ## Example
+//!
+//! ```rust,ignore
+//! let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let pulse = PulseControl::new(
+//!     peripherals.RMT,
+//!     &mut system.peripheral_clock_control,
+//!     ClockSource::APB,
+//!     0,
+//!     0,
+//!     0,
+//! )
+//! .unwrap();
+//!
+//! let led = <smartLedAdapter!(1)>::new(pulse.channel0, io.pins.gpio0);
+//! ```
 
 #![no_std]
 #![deny(missing_docs)]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 use core::slice::IterMut;
 
@@ -67,12 +83,13 @@ pub enum LedAdapterError {
 }
 
 /// Macro to generate adapters with an arbitrary buffer size fitting for a
-/// specific number of `$buffer_size` LEDs to be addressed. Attempting to use
-/// more LEDs that the buffer is configured for will result in an
-/// `LedAdapterError:BufferSizeExceeded` error.
+/// specific number of `$buffer_size` LEDs to be addressed.
+///
+/// Attempting to use more LEDs that the buffer is configured for will result in
+/// an `LedAdapterError:BufferSizeExceeded` error.
 #[macro_export]
 macro_rules! smartLedAdapter {
-    ($buffer_size: literal ) => {
+    ( $buffer_size: literal ) => {
         // The size we're assigning here is calculated as following
         //  (
         //   Nr. of LEDs
@@ -118,6 +135,7 @@ where
             .set_clock_source(ClockSource::APB);
 
         let channel = channel.assign_pin(pin);
+
         Self {
             channel,
             rmt_buffer: [0; BUFFER_SIZE],
@@ -171,7 +189,7 @@ where
     type Color = RGB8;
 
     /// Convert all RGB8 items of the iterator to the RMT format and
-    /// add them to internal buffer. Then start a singular RMT operation
+    /// add them to internal buffer, then start a singular RMT operation
     /// based on that buffer.
     fn write<T, I>(&mut self, iterator: T) -> Result<(), Self::Error>
     where

diff --git a/esp32-hal/src/lib.rs b/esp32-hal/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 pub use embedded_hal as ehal;
 #[cfg(feature = "embassy")]

diff --git a/esp32c2-hal/src/lib.rs b/esp32c2-hal/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 pub use embedded_hal as ehal;
 #[cfg(feature = "embassy")]

diff --git a/esp32c3-hal/src/lib.rs b/esp32c3-hal/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 #[cfg(feature = "mcu-boot")]
 use core::mem::size_of;

diff --git a/esp32c6-hal/src/lib.rs b/esp32c6-hal/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 pub use embedded_hal as ehal;
 #[cfg(feature = "embassy")]

diff --git a/esp32s2-hal/src/lib.rs b/esp32s2-hal/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 pub use embedded_hal as ehal;
 #[cfg(feature = "embassy")]

diff --git a/esp32s3-hal/src/lib.rs b/esp32s3-hal/src/lib.rs
@@ -4,6 +4,7 @@
     feature(asm_experimental_arch),
     feature(naked_functions)
 )]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 
 pub use embedded_hal as ehal;
 #[cfg(feature = "embassy")]