From 610dd65c77cfc9f81b146def4ac6b288d42041d5 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Thu, 26 Nov 2020 12:58:39 +0100 Subject: [PATCH 1/2] document the unwrap! macro --- src/lib.rs | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 1600a170..f71de759 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -118,7 +118,33 @@ pub use defmt_macros::todo_ as unimplemented; /// [the manual]: https://defmt.ferrous-systems.com/macros.html pub use defmt_macros::panic_ as panic; -/// todo +/// This macro is roughly equivalent to `{Option,Result}::{expect,unwrap}` but invocation looks +/// a bit different because this is a macro and not a method. The other difference is that +/// `unwrap!`-ing a `Result` value requires that the error type `E` implements the `Format` +/// trait +/// +/// The following snippet shows the differences between core's unwrap method and defmt's unwrap +/// macro +/// +/// ``` +/// use defmt::unwrap; +/// +/// # let option = Some(()); +/// let x = option.unwrap(); +/// let x = unwrap!(option); +/// +/// # let result = Ok::<(), ()>(()); +/// let x = result.unwrap(); +/// let x = unwrap!(result); +/// +/// # let value = result; +/// let x = value.expect("text"); +/// let x = unwrap!(value, "text"); +/// +/// # let arg = (); +/// let x = value.expect(&format!("text {:?}", arg)); +/// let x = unwrap!(value, "text {:?}", arg); // arg must be implement `Format` +/// ``` /// /// If used, the format string must follow the defmt syntax (documented in [the manual]) /// From d4896440315f520831f96b0dc81f1c6f4326b665 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Thu, 26 Nov 2020 12:34:40 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Jonas Schievink --- src/lib.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index f71de759..6884e31e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -118,13 +118,15 @@ pub use defmt_macros::todo_ as unimplemented; /// [the manual]: https://defmt.ferrous-systems.com/macros.html pub use defmt_macros::panic_ as panic; +/// Unwraps an `Option` or `Result`, panicking if it is `None` or `Err`. +/// /// This macro is roughly equivalent to `{Option,Result}::{expect,unwrap}` but invocation looks /// a bit different because this is a macro and not a method. The other difference is that /// `unwrap!`-ing a `Result` value requires that the error type `E` implements the `Format` /// trait /// /// The following snippet shows the differences between core's unwrap method and defmt's unwrap -/// macro +/// macro: /// /// ``` /// use defmt::unwrap;