Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Outdated doc-comment for trait Format (?) #583

Closed
Urhengulas opened this issue Sep 17, 2021 · 0 comments · Fixed by #584
Closed

Outdated doc-comment for trait Format (?) #583

Urhengulas opened this issue Sep 17, 2021 · 0 comments · Fixed by #584
Assignees
Labels
difficulty: easy Pretty easy to solve priority: medium Medium priority for the Knurling team status: needs PR Issue just needs a Pull Request implementing the changes type: documentation Fixes, improvements or additions to the documentation

Comments

@Urhengulas
Copy link
Member

It seems that the doc-comment for the trait Format is outdated. Definitely the "Note that [write!] can only be called once, as it consumes the [Formatter].". Maybe also the section about the manual implementation?

defmt/src/traits.rs

Lines 7 to 46 in 149c0ef

/// Trait for types that can be formatted via defmt.
///
/// This trait is used by the `{:?}` format specifier and can format a wide range of types.
/// User-defined types can `#[derive(Format)]` to get an auto-generated implementation of this
/// trait.
///
/// **Note**: The implementation of `#[derive(Format)]` assumes that no builtin types are shadowed
/// (for example by defining a `struct u8;`). This allows it to represent them more compactly.
///
/// # Example
///
/// Usually, an implementation of this trait can be `#[derive]`d automatically:
///
/// ```
/// use defmt::Format;
///
/// #[derive(Format)]
/// struct Header {
/// source: u8,
/// destination: u8,
/// sequence: u16,
/// }
/// ```
///
/// Manual implementations can make use of the [`write!`] macro:
///
/// ```
/// use defmt::{Format, Formatter, write};
///
/// struct Id(u32);
///
/// impl Format for Id {
/// fn format(&self, fmt: Formatter) {
/// // Format as hexadecimal.
/// write!(fmt, "Id({:x})", self.0);
/// }
/// }
/// ```
///
/// Note that [`write!`] can only be called once, as it consumes the [`Formatter`].

@Dirbaio Can you please update this? 😁

@Urhengulas Urhengulas added difficulty: easy Pretty easy to solve priority: medium Medium priority for the Knurling team status: needs PR Issue just needs a Pull Request implementing the changes type: documentation Fixes, improvements or additions to the documentation labels Sep 17, 2021
bors bot added a commit that referenced this issue Sep 17, 2021
584: Remove outdated doc "you may only call write! once" r=jonas-schievink a=Dirbaio

SInce #508 it is possible to call it multiple times, and the result is concatenated as you'd expect.

The rest of the comment is still relevant.

Fixes #583

Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
@bors bors bot closed this as completed in aaffb7d Sep 17, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
difficulty: easy Pretty easy to solve priority: medium Medium priority for the Knurling team status: needs PR Issue just needs a Pull Request implementing the changes type: documentation Fixes, improvements or additions to the documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants