1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
derive(Display) /// `From<docs>`
===============
[](https://crates.io/crates/displaydoc)
[](https://docs.rs/displaydoc)
This library provides a convenient derive macro for the standard library's
[`core::fmt::Display`] trait.
[`core::fmt::Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
```toml
[dependencies]
displaydoc = "0.2"
```
*Compiler support: requires rustc 1.31+*
<br>
### Example
```rust
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,
}
```
<br>
### Details
- A `Display` impl is generated for your type if you provide doc comment
messages on the struct or each variant of your enum, as shown above in the
example.
The messages support a shorthand for interpolating fields from the error.
- `/// {var}` ⟶ `write!("{}", self.var)`
- `/// {0}` ⟶ `write!("{}", self.0)`
- `/// {var:?}` ⟶ `write!("{:?}", self.var)`
- `/// {0:?}` ⟶ `write!("{:?}", self.0)`
- 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. Multi-line
comments using `///` are otherwise treated as an error, so use this
attribute or consider switching to block doc comments (`/** */`).
- `#[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
`#[displaydoc("...")` atrribute may be used on the variant or struct to
override it.
<br>
### 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](https://github.com/dtolnay/case-studies/blob/master/autoref-specialization/README.md) 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
<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>
<br>
<sub>
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.
</sub>
|
