Improve discoverability with expect! as alias for unwrap! #872
Conversation
See related issue: knurling-rs#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.
|
pretty sure CI breaking is unrelated since this PR is only 1 use line + some lines of comments |
|
possible discussion point: because its an alias expect can be used without a message. Therefore you can not easily forbid unwrap's without a message by checking for the |
That's true. Please wait for #871 which fixes the nightly tests. I will mark this PR with "breaking change", which is not true, but the CI check compares against the latest published version and not against main and we have some breaking changes in the main branch already. |
Urhengulas
added
the
breaking change
| /// ``` | ||
| /// | ||
| /// 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 |
There was a problem hiding this comment.
ahh that means that link to unwrap written as: [unwrap](defmt::unwrap) does not go to the unwrap item but to the new expect introduced in this PR. That is why the word unwrap is italic and not a link in line 202.
See related issue: #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.