#macro-derive #display #error-derive #traits #derive #docs #comments

no-std docsplay

A derive macro for implementing the display Trait via a doc comment and string interpolation. Fork of displaydoc

2 releases

0.1.1 Feb 27, 2024
0.1.0 Feb 27, 2024

#375 in Rust patterns

Download history 156/week @ 2024-03-13 284/week @ 2024-03-20 240/week @ 2024-03-27 242/week @ 2024-04-03 269/week @ 2024-04-10 426/week @ 2024-04-17 289/week @ 2024-04-24 378/week @ 2024-05-01 260/week @ 2024-05-08 299/week @ 2024-05-15 616/week @ 2024-05-22 565/week @ 2024-05-29 486/week @ 2024-06-05 527/week @ 2024-06-12 493/week @ 2024-06-19 978/week @ 2024-06-26

2,588 downloads per month
Used in 4 crates (2 directly)

MIT/Apache

19KB
105 lines

docsplay: doc comments - Displayed

Latest Version

This library is a fork of displaydoc that provides a convenient derive macro for the standard library's core::fmt::Display trait.

[dependencies]
docsplay = "0.1"

Compiler support: requires rustc 1.56+

Example

Demonstration alongside the Error derive macro from thiserror, to propagate source locations from io::Error with the #[source] attribute:

use std::io;
use docsplay::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,
}

let error = DataStoreError::Redaction("CLASSIFIED CONTENT".to_string());
assert!("the data for key `CLASSIFIED CONTENT` is not available" == &format!("{}", error));

Note that although io::Error implements Display, we do not add it to the generated message for DataStoreError::Disconnect, since it is already made available via #[source]. See further context on avoiding duplication in error reports at the rust blog here.

Details

  • A fmt::Display impl is generated for your enum if you provide a docstring comment on each variant as shown above in the example. The Display derive macro supports a shorthand for interpolating fields from the error:
    • /// {var}write!("{}", self.var)
    • /// {0}write!("{}", self.0)
    • /// {var:?}write!("{:?}", self.var)
    • /// {0:?}write!("{:?}", self.0)
    • /// {0.foo()}write!("{}", self.0.foo())
    • /// {0.foo():?}write!("{:?}", self.0.foo())
  • This also works with structs and generic types:
/// 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));
  • Two optional attributes can be added to your types next to the derive:

    • #[ignore_extra_doc_attributes] makes the macro ignore any doc comment attributes (or /// lines) after the first.

    • #[prefix_enum_doc_attributes] combines the doc comment message on your enum itself with the messages for each variant, in the format enum: variant. When added to an enum, the doc comment on the enum becomes mandatory. When added to any other type, it has no effect.

  • In case you want to have an independent doc comment, the #[display("...") attribute may be used on the variant or struct to override it.

FAQ

  1. Is this crate no_std compatible?

    • Yes! This crate implements the core::fmt::Display trait, not the std::fmt::Display trait, so it should work in std and no_std environments. Just add default-features = false.
  2. Does this crate work with Path and PathBuf via the Display trait?

    • Yuuup. This crate uses @dtolnay's autoref specialization technique to add a special trait for types to get the display impl. It then specializes for Path and PathBuf, and when either of these types are found, it calls self.display() to get a std::path::Display<'_> type which can be used with the Display format specifier!

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~300–760KB
~18K SLoC