Document ErrorGuaranteed (rust-lang#1316)

* document ErrorGuaranteed

* Fix typos

Co-authored-by: pierwill <[email protected]>

* Clarify Niko comment

Co-authored-by: Niko Matsakis <[email protected]>

Co-authored-by: pierwill <[email protected]>
Co-authored-by: Niko Matsakis <[email protected]>

Author: 3 people

src/doc/rustc-dev-guide/src/SUMMARY.md

@@ -142,6 +142,7 @@
     - [`LintStore`](./diagnostics/lintstore.md)
     - [Diagnostic Codes](./diagnostics/diagnostic-codes.md)
     - [Diagnostic Items](./diagnostics/diagnostic-items.md)
+    - [`ErrorGuaranteed`](./diagnostics/error-guaranteed.md)
 
 # MIR to Binaries
 

src/doc/rustc-dev-guide/src/diagnostics/error-guaranteed.md

@@ -0,0 +1,37 @@
+# `ErrorGuaranteed`
+
+The previous sections have been about the error message that a user of the
+compiler sees. But emitting an error can also have a second important side
+effect within the compiler source code: it generates an
+[`ErrorGuaranteed`][errorguar].
+
+`ErrorGuaranteed` is a zero-sized type that is unconstructable outside of the
+[`rustc_errors`][rerrors] crate. It is generated whenever an error is reported
+to the user, so that if your compiler code ever encounters a value of type
+`ErrorGuaranteed`, the compilation is _statically guaranteed to fail_. This is
+useful for avoiding unsoundness bugs because you can statically check that an
+error code path leads to a failure.
+
+There are some important considerations about the usage of `ErrorGuaranteed`:
+
+* It does _not_ convey information about the _kind_ of error. For example, the
+  error may be due (indirectly) to a `delay_span_bug` or other compiler error.
+  Thus, you should not rely on
+  `ErrorGuaranteed` when deciding whether to emit an error, or what kind of error
+  to emit.
+
+* `ErrorGuaranteed` should not be used to indicate that a compilation _will
+  emit_ an error in the future. It should be used to indicate that an error
+  _has already been_ emitted -- that is, the [`emit()`][emit] function has
+  already been called.  For example, if we detect that a future part of the
+  compiler will error, we _cannot_ use `ErrorGuaranteed` unless we first emit
+  an error ourselves.
+
+Thankfully, in most cases, it should be statically impossible to abuse
+`ErrorGuaranteed`.
+
+
+[errorguar]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.ErrorGuaranteed.html
+[rerrors]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/index.html
+[dsp]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Handler.html#method.delay_span_bug
+[emit]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/diagnostic_builder/struct.DiagnosticBuilder.html#method.emit