Add example module in the doc.

Author: Yamakaky

src/error_chain.rs

@@ -67,6 +67,7 @@ macro_rules! error_chain_processed {
                     $error_kind_name
                     $([$link_error_path, $(#[$meta_links])*])*);
 
+        #[allow(dead_code)]
         impl $error_name {
             /// Constructs an error from a kind.
             pub fn from_kind(kind: $error_kind_name) -> $error_name {

src/lib.rs

@@ -136,56 +136,8 @@
 //!
 //! This populates the module with a number of definitions,
 //! the most important of which are the `Error` type
-//! and the `ErrorKind` type. They look something like the
-//! following:
-//!
-//! ```ignore
-//! use std::error::Error as StdError;
-//! use std::sync::Arc;
-//!
-//! #[derive(Debug)]
-//! pub struct Error {
-//!     pub kind: ErrorKind,
-//!     pub state: ::error_chain::State,
-//! }
-//!
-//! impl Error {
-//!     pub fn kind(&self) -> &ErrorKind { ... }
-//!     pub fn into_kind(self) -> ErrorKind { ... }
-//!     pub fn iter(&self) -> error_chain::ErrorChainIter { ... }
-//!     pub fn backtrace(&self) -> Option<&error_chain::Backtrace> { ... }
-//! }
-//!
-//! impl StdError for Error { ... }
-//! impl Display for Error { ... }
-//!
-//! #[derive(Debug)]
-//! pub enum ErrorKind {
-//!     Msg(String),
-//!     Dist(rustup_dist::ErrorKind),
-//!     Utils(rustup_utils::ErrorKind),
-//!     Temp,
-//!     InvalidToolchainName(String),
-//! }
-//! ```
-//!
-//! This is the basic error structure. You can see that `ErrorKind`
-//! has been populated in a variety of ways. All `ErrorKind`s get a
-//! `Msg` variant for basic errors. When strings are converted to
-//! `ErrorKind`s they become `ErrorKind::Msg`. The "links" defined in
-//! the macro are expanded to `Dist` and `Utils` variants, and the
-//! "foreign links" to the `Temp` variant.
-//!
-//! Both types come with a variety of `From` conversions as well:
-//! `Error` can be created from `ErrorKind`, `&str` and `String`,
-//! and the `links` and `foreign_links` error types. `ErrorKind`
-//! can be created from the corresponding `ErrorKind`s of the link
-//! types, as well as from `&str` and `String`.
-//!
-//! `into()` and `From::from` are used heavily to massage types into
-//! the right shape. Which one to use in any specific case depends on
-//! the influence of type inference, but there are some patterns that
-//! arise frequently.
+//! and the `ErrorKind` type. An example of generated code can be found in the
+//! [example_generated](example_generated) module.
 //!
 //! ## Returning new errors
 //!
@@ -310,7 +262,9 @@ use std::sync::Arc;
 #[cfg(feature = "backtrace")]
 pub use backtrace::Backtrace;
 
+#[macro_use]
 mod quick_error;
+#[macro_use]
 mod error_chain;
 
 /// Iterator over the error chain.
@@ -416,3 +370,43 @@ impl Default for State {
         state
     }
 }
+
+/// This modules show an example of code generated by the macro. IT MUST NOT BE
+/// USED OUTSIDE THIS CRATE.
+///
+/// This is the basic error structure. You can see that `ErrorKind`
+/// has been populated in a variety of ways. All `ErrorKind`s get a
+/// `Msg` variant for basic errors. When strings are converted to
+/// `ErrorKind`s they become `ErrorKind::Msg`. The "links" defined in
+/// the macro are expanded to the `Inner` variant, and the
+/// "foreign links" to the `Io` variant.
+///
+/// Both types come with a variety of `From` conversions as well:
+/// `Error` can be created from `ErrorKind`, `&str` and `String`,
+/// and the `links` and `foreign_links` error types. `ErrorKind`
+/// can be created from the corresponding `ErrorKind`s of the link
+/// types, as well as from `&str` and `String`.
+///
+/// `into()` and `From::from` are used heavily to massage types into
+/// the right shape. Which one to use in any specific case depends on
+/// the influence of type inference, but there are some patterns that
+/// arise frequently.
+pub mod example_generated {
+    /// Another code generated by the macro.
+    pub mod inner {
+        error_chain! {}
+    }
+
+    error_chain! {
+        links {
+            Inner(inner::Error) #[doc = "Link to another `ErrorChain`."];
+        }
+        foreign_links {
+            Io(::std::io::Error) #[doc = "Link to a `std::error::Error` type."];
+        }
+        errors {
+            #[doc = "A custom error kind."]
+            Custom
+        }
+    }
+}