Clarify cause iteration behavior

Author: mitsuhiko

book/src/fail.md

@@ -59,6 +59,17 @@ while let Some(cause) = fail.cause() {
 }
 ```
 
+For convenience an iterator is also provided:
+
+```rust
+// Assume err is a type that implements `Fail`
+let mut fail: &Fail = err;
+
+for cause in fail.iter_causes() {
+    println!("{}", cause);
+}
+```
+
 ## Backtraces
 
 Errors can also generate a backtrace when they are constructed, helping you

src/error/mod.rs

@@ -133,7 +133,7 @@ impl Error {
     }
 
     /// Returns a iterator over the causes of the `Error`, beginning with
-    /// the failure returned by the `cause` method and ending with the failure
+    /// the failure returned by the `as_fail` method and ending with the failure
     /// returned by `find_root_cause`.
     pub fn iter_causes(&self) -> Causes {
         self.as_fail().iter_causes()

src/lib.rs

@@ -222,6 +222,10 @@ impl Fail {
 
     /// Returns a iterator over the causes of this `Fail` with itself
     /// as the first item and the `root_cause` as the final item.
+    ///
+    /// This means that `causes` also includes the fail itself which
+    /// means that it does *not* start with `cause`.  To skip the outermost
+    /// fail use the `skip` method (`fail.causes().skip(1)`).
     pub fn iter_causes(&self) -> Causes {
         Causes { fail: Some(self) }
     }