Add IntoFieldError to error docs

Part of graphql-rust#8.

Author: LegNeato

docs/types/objects/error_handling.md

@@ -17,6 +17,7 @@ use juniper::FieldResult;
 use std::path::PathBuf;
 use std::fs::File;
 use std::io::Read;
+use std::str;
 
 struct Example {
     filename: PathBuf,
@@ -29,6 +30,15 @@ graphql_object!(Example: () |&self| {
         file.read_to_string(&mut contents)?;
         Ok(contents)
     }
+    field foo() -> FieldResult<Option<String>> {
+      // Some invalid bytes.
+      let invalid = vec![128, 223];
+
+      match str::from_utf8(&invalid) {
+        Ok(s) => Ok(Some(s.to_string())),
+        Err(e) => Err(e)?,
+      }
+    }
 });
 
 # fn main() {}
@@ -41,6 +51,118 @@ there - those errors are automatically converted into `FieldError`.
 
 When a field returns an error, the field's result is replaced by `null`, an
 additional `errors` object is created at the top level of the response, and the
-execution is resumed. If an error is returned from a non-null field, such as the
+execution is resumed. For example, with the previous example and the following
+query:
+
+```graphql
+{
+  example {
+    contents
+    foo
+  }
+}
+```
+
+If `str::from_utf8` resulted in a `std::str::Utf8Error`, the following would be
+returned:
+
+!FILENAME Response for nullable field with error
+
+```js
+{
+  "data": {
+    "example": {
+      contents: "<Contents of the file>",
+      foo: null,
+    }
+  },
+  "errors": [
+    "message": "invalid utf-8 sequence of 2 bytes from index 0",
+    "locations": [{ "line": 2, "column": 4 }])
+  ]
+}
+```
+
+If an error is returned from a non-null field, such as the
 example above, the `null` value is propagated up to the first nullable parent
 field, or the root `data` object if there are no nullable fields.
+
+For example, with the following query:
+
+```graphql
+{
+  example {
+    contents
+  }
+}
+```
+
+If `File::open()` above resulted in `std::io::ErrorKind::PermissionDenied`, the
+following would be returned:
+
+!FILENAME Response for non-null field with error and no nullable parent
+
+```js
+{
+  "errors": [
+    "message": "Permission denied (os error 13)",
+    "locations": [{ "line": 2, "column": 4 }])
+  ]
+}
+```
+
+## Structured errors
+
+Sometimes it is desirable to return additional structured error information
+to clients. This can be accomplished by implementing [`IntoFieldError`](https://docs.rs/juniper/latest/juniper/trait.IntoFieldError.html):
+
+```rust
+# #[macro_use] extern crate juniper;
+use juniper::{FieldError, IntoFieldError};
+
+enum CustomError {
+    WhateverNotSet,
+}
+
+impl IntoFieldError for CustomError {
+    fn into_field_error(self) -> FieldError {
+        match self {
+            CustomError::WhateverNotSet => FieldError::new(
+                "Whatever does not exist",
+                graphql_value!({
+                    "type": "NO_WHATEVER"
+                }),
+            ),
+        }
+    }
+}
+
+struct Example {
+    whatever: Option<bool>,
+}
+
+graphql_object!(Example: () |&self| {
+    field whatever() -> Result<bool, CustomError> {
+      if let Some(value) = self.whatever {
+        return Ok(value);
+      }
+      Err(CustomError::WhateverNotSet)
+    }
+});
+
+# fn main() {}
+```
+
+The specified structured error information is included in the [`extensions`](https://facebook.github.io/graphql/June2018/#sec-Errors) key:
+
+```js
+{
+  "errors": [
+    "message": "Whatever does not exist",
+    "locations": [{ "line": 2, "column": 4 }]),
+    "extensions": {
+      "type": "NO_WHATEVER"
+    }
+  ]
+}
+```