From 1e1f2849e28baae3e2133d6bf2fbb48653c54ad2 Mon Sep 17 00:00:00 2001 From: dvdsk Date: Wed, 9 Oct 2024 18:01:12 +0200 Subject: [PATCH] Improve discoverability with expect! as alias for unwrap! See related issue: https://github.com/knurling-rs/defmt/issues/867 Its easy to assume unwrap! can not have a message like std's expect. Adding an expect macro will help both autocomplete guide programmers looking for one and those who discount the unwrap entry in the defmt api docs based on their knowledge that std's unwrap can not have a message. The documentation of the expect alias highlights that unwrap works with a message to and points to the unwrap macro docs for details. --- defmt/src/lib.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/defmt/src/lib.rs b/defmt/src/lib.rs index 6222bd68..4abe61fe 100644 --- a/defmt/src/lib.rs +++ b/defmt/src/lib.rs @@ -190,6 +190,19 @@ pub use defmt_macros::panic_ as panic; /// [the manual]: https://defmt.ferrous-systems.com/macros.html pub use defmt_macros::unwrap; +/// This is an alias for defmt's [`unwrap`] macro which supports messages like std's except. +/// ``` +/// use defmt::expect; +/// +/// # let arg = (); +/// let x = value.expect(&format!("text {:?}", arg)); +/// let x = expect!(value, "text {:?}", arg); // arg must be implement `Format` +/// ``` +/// +/// For the complete documentation see that of defmt's *unwrap* macro. +// note: Linking to unwrap is broken as of 2024-10-09, it links back to expect +pub use defmt_macros::unwrap as expect; + /// Overrides the panicking behavior of `defmt::panic!` /// /// By default, `defmt::panic!` calls `core::panic!` after logging the panic message using `defmt`.