Better documentation for ChainedError.

Author: Yamakaky

src/lib.rs

@@ -358,17 +358,15 @@ pub fn make_backtrace() -> Option<Arc<Backtrace>> {
     }
 }
 
-/// This trait is an implementation detail which must be implemented on each
-/// ErrorKind. We can't do it globally since each ErrorKind is different.
+/// This trait is implemented on all the errors generated by the `error_chain`
+/// macro.
 pub trait ChainedError: error::Error + Send + 'static {
     /// Associated kind type.
     type ErrorKind;
     /// Creates an error from it's parts.
     fn new(kind: Self::ErrorKind, state: State) -> Self;
-    /// Use downcasts to extract the backtrace from types we know,
-    /// to avoid generating a new one. It would be better to not
-    /// define this in the macro, but types need some additional
-    /// machinery to make it work.
+    /// Returns the first known backtrace, either from it's State or from one
+    /// of the errors from `foreign_links`.
     #[cfg(feature = "backtrace")]
     fn extract_backtrace(e: &(error::Error + Send + 'static))
         -> Option<Option<Arc<Backtrace>>>;