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

//! # Attributes understood by the `Snafu` macro
//!
//! ## Controlling `Display`
//!
//! There are a number of ways you can specify how the `Display` trait
//! will be implemented for each variant:
//!
//! - `#[snafu(display("a format string with arguments: {}", info))]`
//!
//!   The argument is a format string and the arguments. Available in Rust 1.34.
//!
//! - `#[snafu(display = r#"("a format string with arguments: {}", info)"#)]`
//!
//!   The same argument as above, but wrapped in a raw string to
//!   support previous Rust versions.
//!
//! Each choice has the same capabilities. All of the fields of the
//! variant will be available and you can call methods on them, such
//! as `filename.display()`.
//!
//! ## Controlling visibility
//!
//! By default, each of the context selectors and their inherent
//! methods will be private. It is our opinion that each module should
//! have one or more error types that are scoped to that module,
//! reducing the need to deal with unrelated errors when matching and
//! increasing cohesiveness.
//!
//! If you need access the context selectors from outside of their
//! module, you can use the `#[snafu(visibility)]` attribute. This can
//! be applied to the error type as a default visibility or to
//! specific context selectors.
//!
//! There are a number of forms of the attribute:
//!
//! - `#[snafu(visibility(X))]`
//!
//!   `X` is a normal Rust visibility modifier (`pub`, `pub(crate)`,
//!   `pub(in some::path)`, etc.). Supported in Rust 1.34.
//!
//! - `#[snafu(visibility = "X")]`
//!
//!   The same argument as above, but wrapped in a string to support
//!   previous Rust versions.
//!
//! - `#[snafu(visibility)]` will reset back to private visibility.
//!
//! ```
//! # use snafu::Snafu;
//! #[derive(Debug, Snafu)]
//! #[snafu(visibility = "pub(crate)")] // Default
//! enum Error {
//!     IsPubCrate, // Uses the default
//!     #[snafu(visibility)]
//!     IsPrivate,  // Will be private
//! }
//! ```
//!
//! ## Controlling backtraces
//!
//! If your error contains other SNAFU errors which can report
//! backtraces, you may wish to delegate returning a backtrace to
//! those errors. Use `#[snafu(backtrace(delegate))]` to specify this:
//!
//! ```rust
//! # mod another {
//! #     use snafu::Snafu;
//! #     #[derive(Debug, Snafu)]
//! #     pub enum Error {}
//! # }
//! # use snafu::Snafu;
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     MyError {
//!         #[snafu(backtrace(delegate))]
//!         source: another::Error,
//!     }
//! }
//! ```