Skip to content
This repository was archived by the owner on Aug 16, 2021. It is now read-only.

Commit fc117ef

Browse files
committed
Add example module in the doc.
1 parent e5c06b7 commit fc117ef

File tree

2 files changed

+45
-50
lines changed

2 files changed

+45
-50
lines changed

src/error_chain.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ macro_rules! error_chain_processed {
6767
$error_kind_name
6868
$([$link_error_path, $(#[$meta_links])*])*);
6969

70+
#[allow(dead_code)]
7071
impl $error_name {
7172
/// Constructs an error from a kind.
7273
pub fn from_kind(kind: $error_kind_name) -> $error_name {

src/lib.rs

Lines changed: 44 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -136,56 +136,8 @@
136136
//!
137137
//! This populates the module with a number of definitions,
138138
//! 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.
189141
//!
190142
//! ## Returning new errors
191143
//!
@@ -310,7 +262,9 @@ use std::sync::Arc;
310262
#[cfg(feature = "backtrace")]
311263
pub use backtrace::Backtrace;
312264

265+
#[macro_use]
313266
mod quick_error;
267+
#[macro_use]
314268
mod error_chain;
315269

316270
/// Iterator over the error chain.
@@ -416,3 +370,43 @@ impl Default for State {
416370
state
417371
}
418372
}
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

Comments
 (0)