From ad8b280d345e2dcf1684523b9bc3cc6ef341f86c Mon Sep 17 00:00:00 2001 From: JadKHaddad Date: Fri, 20 Sep 2024 19:17:11 +0200 Subject: [PATCH 1/4] docs(formatters): added example usage to clock_to_4digits Signed-off-by: JadKHaddad --- tm1637/Cargo.toml | 11 ++++++++++- tm1637/src/formatters.rs | 42 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 51 insertions(+), 2 deletions(-) diff --git a/tm1637/Cargo.toml b/tm1637/Cargo.toml index 1292ddc..e549c9b 100644 --- a/tm1637/Cargo.toml +++ b/tm1637/Cargo.toml @@ -10,7 +10,13 @@ keywords = ["tm1637", "embedded-hal", "no-std", "embedded"] readme = "../README.md" [features] -default = ["async", "impl-debug"] +default = [ + "blocking", + "async", # Make blocking default + "impl-debug", + "mappings", + "formatters", +] # TODO remove mappings, formatters before release async = ["dep:embedded-hal", "dep:embedded-hal-async"] blocking = ["dep:embedded-hal"] mappings = [] @@ -26,6 +32,9 @@ embedded-hal-async = { version = "1.0.0", optional = true } embedded-hal = { version = "1.0.0", optional = true } defmt = { version = "0.3.6", optional = true } +[dev-dependencies] +embedded-hal-mock = { version = "0.11.1" } + [package.metadata.docs.rs] all-features = true rustdoc-args = ["--cfg", "docsrs"] diff --git a/tm1637/src/formatters.rs b/tm1637/src/formatters.rs index ea1efe8..98ba84c 100644 --- a/tm1637/src/formatters.rs +++ b/tm1637/src/formatters.rs @@ -112,10 +112,50 @@ pub fn degrees_to_4digits(n: i16) -> [u8; 4] { b } -/// Formats two [i8]s between 0 and 99, with an optional colon between them. +/// Formats two [u8]s between 0 and 99, with an optional colon between them. /// /// This will only work for 4-digit displays where there's a physical colon, /// and that colon acts as the decimal dot between the 2nd and 3rd digit. +/// +/// # Example +/// +/// Let's create a clock displaying `12:34` with a blinking colon: +/// +/// ```rust +/// use tm1637_embedded_hal::{ +/// blocking::TM1637, +/// formatters::clock_to_4digits, +/// Brightness, +/// }; +/// use embedded_hal::delay::DelayNs; +/// use embedded_hal_mock::eh1::{delay::NoopDelay, digital::Mock as PinMock}; +/// +/// let clk = PinMock::new([]); +/// let dio = PinMock::new([]); +/// +/// let delay = NoopDelay::new(); +/// +/// let mut tm = TM1637::builder(clk, dio, delay) +/// .brightness(Brightness::L3) +/// .build(); +/// +/// tm.init().unwrap(); +/// +/// let mut delay = NoopDelay::new(); +/// +/// for hour in 13..24 { +/// for minute in 34..60 { +/// for second in 0..120 { +/// let blink = second % 2 == 0; +/// let segs = clock_to_4digits(hour, minute, blink); +/// +/// tm.write_segments_raw(0, &segs).ok(); +/// +/// delay.delay_ms(500); +/// } +/// } +/// } +/// ``` pub fn clock_to_4digits(hour: u8, minute: u8, colon: bool) -> [u8; 4] { let mut b: [u8; 4] = [0, 0, 0, 0]; From e6070a1d5c457e5d11f232b6ca72fe40967379cd Mon Sep 17 00:00:00 2001 From: JadKHaddad Date: Fri, 20 Sep 2024 19:36:34 +0200 Subject: [PATCH 2/4] docs(formatters): updated example usage to clock_to_4digits Signed-off-by: JadKHaddad --- tm1637/Cargo.toml | 6 +----- tm1637/src/formatters.rs | 23 ++++------------------- 2 files changed, 5 insertions(+), 24 deletions(-) diff --git a/tm1637/Cargo.toml b/tm1637/Cargo.toml index e549c9b..d4c425a 100644 --- a/tm1637/Cargo.toml +++ b/tm1637/Cargo.toml @@ -11,8 +11,7 @@ readme = "../README.md" [features] default = [ - "blocking", - "async", # Make blocking default + "async", "impl-debug", "mappings", "formatters", @@ -32,9 +31,6 @@ embedded-hal-async = { version = "1.0.0", optional = true } embedded-hal = { version = "1.0.0", optional = true } defmt = { version = "0.3.6", optional = true } -[dev-dependencies] -embedded-hal-mock = { version = "0.11.1" } - [package.metadata.docs.rs] all-features = true rustdoc-args = ["--cfg", "docsrs"] diff --git a/tm1637/src/formatters.rs b/tm1637/src/formatters.rs index 98ba84c..bfb4473 100644 --- a/tm1637/src/formatters.rs +++ b/tm1637/src/formatters.rs @@ -121,29 +121,14 @@ pub fn degrees_to_4digits(n: i16) -> [u8; 4] { /// /// Let's create a clock displaying `12:34` with a blinking colon: /// -/// ```rust -/// use tm1637_embedded_hal::{ -/// blocking::TM1637, -/// formatters::clock_to_4digits, -/// Brightness, -/// }; -/// use embedded_hal::delay::DelayNs; -/// use embedded_hal_mock::eh1::{delay::NoopDelay, digital::Mock as PinMock}; -/// -/// let clk = PinMock::new([]); -/// let dio = PinMock::new([]); -/// -/// let delay = NoopDelay::new(); -/// -/// let mut tm = TM1637::builder(clk, dio, delay) +/// ```rust, ignore +/// let mut tm = TM1637::builder(clk_pin, dio_pin, delay) /// .brightness(Brightness::L3) /// .build(); /// -/// tm.init().unwrap(); -/// -/// let mut delay = NoopDelay::new(); +/// tm.init().ok(); /// -/// for hour in 13..24 { +/// for hour in 12..24 { /// for minute in 34..60 { /// for second in 0..120 { /// let blink = second % 2 == 0; From ea695730d94d8d6a52b5fb181dcc7d4850322414 Mon Sep 17 00:00:00 2001 From: JadKHaddad Date: Fri, 20 Sep 2024 19:39:42 +0200 Subject: [PATCH 3/4] docs(formatters): added example usage to i16_to_4digits Signed-off-by: JadKHaddad --- tm1637/src/formatters.rs | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/tm1637/src/formatters.rs b/tm1637/src/formatters.rs index bfb4473..b2df506 100644 --- a/tm1637/src/formatters.rs +++ b/tm1637/src/formatters.rs @@ -19,11 +19,28 @@ //! This module is only available when the `formatters` feature of this //! library is activated. -// TODO: let tm.write_bytes_raw(0, i16_to_4digits(1234)); be tested in docs rs. - use crate::mappings::{DigitBits, UpsideDownDigitBits}; -/// Formats a [i16] clamped between -999 and 9999, for a 4-digit display +/// Formats a [i16] clamped between `-999` and `9999`, for a `4-digit display` +/// +/// # Example +/// +/// A counter that goes from `-100` to `100`: +/// +/// ```rust, ignore +/// let mut tm = TM1637::builder(clk_pin, dio_pin, delay) +/// .brightness(Brightness::L3) +/// .build(); +/// +/// tm.init().ok(); +/// +/// for i in -100..100 { +/// let segs = i16_to_4digits(i); +/// tm.write_segments_raw(0, &segs).ok(); +/// +/// delay.delay_ms(100u16); +/// } +/// ``` pub fn i16_to_4digits(n: i16) -> [u8; 4] { let mut bytes: [u8; 4] = [0; 4]; let mut m: i16 = n.clamp(-999, 9999).abs(); From a3b83d09fde38450e320f49c9e8ebf296302180c Mon Sep 17 00:00:00 2001 From: JadKHaddad Date: Fri, 20 Sep 2024 19:43:21 +0200 Subject: [PATCH 4/4] docs(formatters): added docs highlights Signed-off-by: JadKHaddad --- tm1637/src/formatters.rs | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/tm1637/src/formatters.rs b/tm1637/src/formatters.rs index b2df506..d1cb1bd 100644 --- a/tm1637/src/formatters.rs +++ b/tm1637/src/formatters.rs @@ -1,6 +1,6 @@ //! Format numbers into byte arrays. //! -//! Functions for converting numbers ([i8]s, [i16]s, [i32]s or [f32]s) into arrays of bytes +//! Functions for converting numbers ([`i8`]s, [`i16`]s, [`i32`]s or [`f32`]s) into arrays of bytes //! that can be sent to a TM1637 display. //! //! There are versions of these functions that are meant for 4-digit displays @@ -21,7 +21,7 @@ use crate::mappings::{DigitBits, UpsideDownDigitBits}; -/// Formats a [i16] clamped between `-999` and `9999`, for a `4-digit display` +/// Formats a [`i16`] clamped between `-999` and `9999`, for a `4-digit display`. /// /// # Example /// @@ -61,7 +61,7 @@ pub fn i16_to_4digits(n: i16) -> [u8; 4] { bytes } -/// Formats a [i32] clamped between -99999 and 999999, for a 6-digit display +/// Formats a [`i32`] clamped between `-99999` and `999999`, for a `6-digit display`. pub fn i32_to_6digits(n: i32) -> [u8; 6] { let mut b: [u8; 6] = [0; 6]; let mut m: i32 = n.clamp(-99999, 999999).abs(); @@ -83,8 +83,8 @@ pub fn i32_to_6digits(n: i32) -> [u8; 6] { [b[2], b[1], b[0], b[5], b[4], b[3]] } -/// Formats a [i8] clamped between -9 and 99, appending the degrees symbol (°) -/// and an uppercase C, for a 4-digit display +/// Formats a [`i8`] clamped between `-9` and `99`, appending the degrees symbol `(°)` +/// and an `uppercase C`, for a `4-digit display`. pub fn celsius_to_4digits(n: i8) -> [u8; 4] { let mut m: i8 = n.clamp(-9, 99); @@ -106,8 +106,8 @@ pub fn celsius_to_4digits(n: i8) -> [u8; 4] { b } -/// Formats a [i16] clamped between -99 and 999, appending the degrees symbol (°), -/// for a 4-digit display +/// Formats a [`i16`] clamped between `-99` and `999`, appending the degrees symbol `(°)`, +/// for a `4-digit display`. pub fn degrees_to_4digits(n: i16) -> [u8; 4] { let mut m: i16 = n.clamp(-99, 999); @@ -129,9 +129,9 @@ pub fn degrees_to_4digits(n: i16) -> [u8; 4] { b } -/// Formats two [u8]s between 0 and 99, with an optional colon between them. +/// Formats two [`u8`]s between `0` and `99`, with an optional colon between them. /// -/// This will only work for 4-digit displays where there's a physical colon, +/// This will only work for `4-digit displays` where there's a physical colon, /// and that colon acts as the decimal dot between the 2nd and 3rd digit. /// /// # Example @@ -175,7 +175,7 @@ pub fn clock_to_4digits(hour: u8, minute: u8, colon: bool) -> [u8; 4] { b } -/// Formats a [i16] clamped between -999 and 9999, for an upside-down 4-digit display +/// Formats a [`i16`] clamped between `-999` and `9999`, for an `upside-down 4-digit display`. pub fn i16_to_upsidedown_4digits(n: i16) -> [u8; 4] { let mut bytes: [u8; 4] = [0; 4]; let mut m: i16 = n.clamp(-999, 9999).abs(); @@ -196,7 +196,7 @@ pub fn i16_to_upsidedown_4digits(n: i16) -> [u8; 4] { bytes } -/// Formats a [f32] with the given amount of decimal digits, for a 6-digit display +/// Formats a [`f32`] with the given amount of decimal digits, for a `6-digit display`. pub fn f32_to_6digits(n: f32, decimals: u8) -> [u8; 6] { use core::ops::Mul;