DOCSEARCHbyAlgolia
Submit Docs

displaydoc

repository·master·Indexed 18 days ago

https://github.com/yaahc/displaydoc

A Rust library providing a derive macro to automatically implement the core::fmt::Display trait using docstrings as message templates. It is no_std compatible, requires rustc 1.71+, and supports interpolation of fields using Display and Debug traits, including specialized support for Path and PathBuf.

Tokens
925
Snippets
3
Records
6
Agent score
13%

What's inside displaydoc

  1. How displaydoc handles Path and PathBuf

    master
    The library provides specialized support for std::path::Path and std::path::PathBuf. When these types are encountered during interpolation, the macro uses an autoref specialization technique to call .display(), ensuring they are formatted correctly as paths within your Display message.

  2. Install displaydoc

    master

    Add displaydoc to your Cargo.toml dependencies. Note that the library requires rustc 1.71+.

    For no_std environments, disable default features.

    [dependencies]
displaydoc = "0.2"

  3. Configure Display macro with attributes

    master

    You can use specific attributes to modify how the macro processes docstrings or formats messages:

    • #[ignore_extra_doc_attributes]: Tells the macro to ignore any doc comment attributes (or /// lines) appearing after the last non-empty line. This is useful if you have multi-line comments that would otherwise cause errors.
    • #[prefix_enum_doc_attributes]: When applied to an enum, it combines the enum's doc comment with the variant's message in the format "enum: variant". The enum's doc comment becomes mandatory when using this attribute. This attribute has no effect on non-enum types.
    • #[displaydoc("...")]: Can be used on a variant or struct to override the message generated from the docstring with a custom string.

  4. Is displaydoc no_std compatible?

    master

    Yes. displaydoc implements core::fmt::Display rather than std::fmt::Display, making it compatible with no_std environments. To use it in a no_std project, disable default features:

    [dependencies]
displaydoc = { version = "0.2", default-features = false }

  5. Use the Display derive macro

    master

    The Display derive macro generates an implementation of the core::fmt::Display trait based on the docstrings (///) of your enum variants or struct fields.

    Interpolation Syntax

    You can interpolate fields into the display message using the following shorthand in your docstrings:

    • /// {var}: Interpolates field var using Display (write!("{}", self.var))
    • /// {0}: Interpolates the first field using Display (write!("{}", self.0))
    • /// {var:?}: Interpolates field var using Debug (write!("{:?}", self.var))
    • /// {0:?}: Interpolates the first field using Debug (write!("{:?}", self.0))

    Example: Enum with variants

    use std::io;
use displaydoc::Display;
use thiserror::Error;

#[derive(Display, Error, Debug)]
pub enum DataStoreError {
    /// data store disconnected
    Disconnect(#[source] io::Error),
    /// the data for key `{0}` is not available
    Redaction(String),
    /// invalid header (expected {expected:?}, found {found:?})
    InvalidHeader {
        expected: String,
        found: String,
    },
    /// unknown data store error
    Unknown,
}

  6. Use Display with structs and generic types

    master

    The Display macro also works on structs and generic types by using the docstring of the struct to define the message.

    /// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

let error: Error<&str> = Error("muahaha i am an error");
assert!("oh no, an error: muahaha i am an error" == &format!("{}", error));