|
136 | 136 | //!
|
137 | 137 | //! This populates the module with a number of definitions,
|
138 | 138 | //! the most important of which are the `Error` type
|
139 |
| -//! and the `ErrorKind` type. They look something like the |
140 |
| -//! following: |
141 |
| -//! |
142 |
| -//! ```ignore |
143 |
| -//! use std::error::Error as StdError; |
144 |
| -//! use std::sync::Arc; |
145 |
| -//! |
146 |
| -//! #[derive(Debug)] |
147 |
| -//! pub struct Error { |
148 |
| -//! pub kind: ErrorKind, |
149 |
| -//! pub state: ::error_chain::State, |
150 |
| -//! } |
151 |
| -//! |
152 |
| -//! impl Error { |
153 |
| -//! pub fn kind(&self) -> &ErrorKind { ... } |
154 |
| -//! pub fn into_kind(self) -> ErrorKind { ... } |
155 |
| -//! pub fn iter(&self) -> error_chain::ErrorChainIter { ... } |
156 |
| -//! pub fn backtrace(&self) -> Option<&error_chain::Backtrace> { ... } |
157 |
| -//! } |
158 |
| -//! |
159 |
| -//! impl StdError for Error { ... } |
160 |
| -//! impl Display for Error { ... } |
161 |
| -//! |
162 |
| -//! #[derive(Debug)] |
163 |
| -//! pub enum ErrorKind { |
164 |
| -//! Msg(String), |
165 |
| -//! Dist(rustup_dist::ErrorKind), |
166 |
| -//! Utils(rustup_utils::ErrorKind), |
167 |
| -//! Temp, |
168 |
| -//! InvalidToolchainName(String), |
169 |
| -//! } |
170 |
| -//! ``` |
171 |
| -//! |
172 |
| -//! This is the basic error structure. You can see that `ErrorKind` |
173 |
| -//! has been populated in a variety of ways. All `ErrorKind`s get a |
174 |
| -//! `Msg` variant for basic errors. When strings are converted to |
175 |
| -//! `ErrorKind`s they become `ErrorKind::Msg`. The "links" defined in |
176 |
| -//! the macro are expanded to `Dist` and `Utils` variants, and the |
177 |
| -//! "foreign links" to the `Temp` variant. |
178 |
| -//! |
179 |
| -//! Both types come with a variety of `From` conversions as well: |
180 |
| -//! `Error` can be created from `ErrorKind`, `&str` and `String`, |
181 |
| -//! and the `links` and `foreign_links` error types. `ErrorKind` |
182 |
| -//! can be created from the corresponding `ErrorKind`s of the link |
183 |
| -//! types, as well as from `&str` and `String`. |
184 |
| -//! |
185 |
| -//! `into()` and `From::from` are used heavily to massage types into |
186 |
| -//! the right shape. Which one to use in any specific case depends on |
187 |
| -//! the influence of type inference, but there are some patterns that |
188 |
| -//! arise frequently. |
| 139 | +//! and the `ErrorKind` type. An example of generated code can be found in the |
| 140 | +//! [example_generated](example_generated) module. |
189 | 141 | //!
|
190 | 142 | //! ## Returning new errors
|
191 | 143 | //!
|
@@ -310,7 +262,9 @@ use std::sync::Arc;
|
310 | 262 | #[cfg(feature = "backtrace")]
|
311 | 263 | pub use backtrace::Backtrace;
|
312 | 264 |
|
| 265 | +#[macro_use] |
313 | 266 | mod quick_error;
|
| 267 | +#[macro_use] |
314 | 268 | mod error_chain;
|
315 | 269 |
|
316 | 270 | /// Iterator over the error chain.
|
@@ -416,3 +370,43 @@ impl Default for State {
|
416 | 370 | state
|
417 | 371 | }
|
418 | 372 | }
|
| 373 | + |
| 374 | +/// This modules show an example of code generated by the macro. IT MUST NOT BE |
| 375 | +/// USED OUTSIDE THIS CRATE. |
| 376 | +/// |
| 377 | +/// This is the basic error structure. You can see that `ErrorKind` |
| 378 | +/// has been populated in a variety of ways. All `ErrorKind`s get a |
| 379 | +/// `Msg` variant for basic errors. When strings are converted to |
| 380 | +/// `ErrorKind`s they become `ErrorKind::Msg`. The "links" defined in |
| 381 | +/// the macro are expanded to the `Inner` variant, and the |
| 382 | +/// "foreign links" to the `Io` variant. |
| 383 | +/// |
| 384 | +/// Both types come with a variety of `From` conversions as well: |
| 385 | +/// `Error` can be created from `ErrorKind`, `&str` and `String`, |
| 386 | +/// and the `links` and `foreign_links` error types. `ErrorKind` |
| 387 | +/// can be created from the corresponding `ErrorKind`s of the link |
| 388 | +/// types, as well as from `&str` and `String`. |
| 389 | +/// |
| 390 | +/// `into()` and `From::from` are used heavily to massage types into |
| 391 | +/// the right shape. Which one to use in any specific case depends on |
| 392 | +/// the influence of type inference, but there are some patterns that |
| 393 | +/// arise frequently. |
| 394 | +pub mod example_generated { |
| 395 | + /// Another code generated by the macro. |
| 396 | + pub mod inner { |
| 397 | + error_chain! {} |
| 398 | + } |
| 399 | + |
| 400 | + error_chain! { |
| 401 | + links { |
| 402 | + Inner(inner::Error) #[doc = "Link to another `ErrorChain`."]; |
| 403 | + } |
| 404 | + foreign_links { |
| 405 | + Io(::std::io::Error) #[doc = "Link to a `std::error::Error` type."]; |
| 406 | + } |
| 407 | + errors { |
| 408 | + #[doc = "A custom error kind."] |
| 409 | + Custom |
| 410 | + } |
| 411 | + } |
| 412 | +} |
0 commit comments