Add non_exhaustive to reference.

Author: davidtwco

src/attributes.md

@@ -196,6 +196,8 @@ The following is an index of all built-in attributes.
   - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level.
   - [`deprecated`] — Generates deprecation notices.
   - [`must_use`] — Generates a lint for unused values.
+  - [`non_exhaustive`] — Indicate that a type will have more fields/variants
+    added in future.
 - ABI, linking, symbols, and FFI
   - [`link`] — Specifies a native library to link with an `extern` block.
   - [`link_name`] — Specifies the name of the symbol for functions or statics
@@ -276,6 +278,7 @@ The following is an index of all built-in attributes.
 [`no_main`]: crates-and-source-files.md#the-no_main-attribute
 [`no_mangle`]: abi.md#the-no_mangle-attribute
 [`no_std`]: crates-and-source-files.md#preludes-and-no_std
+[`non_exhaustive`]: attributes/diagnostics.md#the-non_exhaustive-attribute
 [`panic_handler`]: runtime.md#the-panic_handler-attribute
 [`path`]: items/modules.md#the-path-attribute
 [`proc_macro_attribute`]: procedural-macros.md#attribute-macros

src/attributes/diagnostics.md

@@ -252,10 +252,125 @@ When used on a function in a trait implementation, the attribute does nothing.
 > let _ = five();
 > ```
 
+# The `non_exhaustive` attribute
+
+The *`non_exhaustive` attribute* is used to indicate that a type will have
+more fields/variants added in the future. It can be applied to
+[`struct`s][struct], [`enum`s][enum] and `enum` variants.
+
+The `non_exhaustive` attribute uses the [_MetaWord_] syntax and thus does not
+take any inputs.
+
+Within the defining crate, types annotated with `non_exhaustive` behave exactly
+the same as if the type were not annotated with `non_exhaustive`:
+
+```rust,ignore
+#[non_exhaustive]
+pub struct Config {
+    pub window_width: u16,
+    pub window_height: u16,
+}
+
+#[non_exhaustive]
+pub enum Error {
+    Message(String),
+    Other,
+}
+
+pub enum Message {
+    #[non_exhaustive] Send { from: u32, to: u32, contents: String },
+    #[non_exhaustive] Reaction(u32),
+    #[non_exhaustive] Quit,
+}
+
+// Non-exhaustive structs can be constructed as normal within the defining crate.
+let config = Config { window_width: 640, window_height: 480 };
+
+// Non-exhaustive structs can be matched on exhaustively within the defining crate.
+if let Ok(Config { window_width, window_height }) = config {
+    // ...
+}
+
+// Non-exhaustive enums can be matched on exhaustively within the defining crate.
+match error {
+    Error::Message(ref s) => { },
+    Error::Other => { },
+}
+
+match message {
+    // Non-exhaustive variants can be matched on exhaustively within the defining crate.
+    Message::Send { from, to, contents } => { },
+    Message::Reaction(type) => { },
+    Message::Quit => { },
+}
+```
+
+In downstream crates, types annotated with `non_exhaustive` have limitations that
+preserve backwards compatibility when new fields/variants are added.
+
+Non-exhaustive types cannot be constructed in downstream crates:
+
+```rust,ignore
+// `Config`, `Error` and `Message` are types defined in an upstream crate that have been
+// annotated as `#[non_exhaustive]`.
+use upstream::{Config, Error, Message};
+
+// Cannot construct an instance of `Config`, if new fields were added in
+// a new version of `upstream` then this would fail to compile, so it is
+// disallowed.
+let config = Config { window_width: 640, window_height: 480 };
+
+// Can construct an instance of `Error`, new variants being introduced would
+// not result in this failing to compile.
+let error = Error::Message("foo".to_string());
+
+// Cannot construct an instance of `Message::Send` or `Message::Reaction`,
+// if new fields were added in a new version of `upstream` then this would
+// fail to compile, so it is disallowed.
+let message = Message::Send { from: 0, to: 1, contents: "foo".to_string(), };
+let message = Message::Reaction(0);
+
+// Cannot construct an instance of `Message::Quit`, if this were converted to
+// a tuple-variant `upstream` then this would fail to compile.
+let message = Message::Quit;
+```
+
+Non-exhaustive types cannot be used in a [`match`]/[`if let`] expression without a
+wildcard arm:
+
+```rust, ignore
+// `Config`, `Error` and `Message` are types defined in an upstream crate that have been
+// annotated as `#[non_exhaustive]`.
+use upstream::{Config, Error, Message};
+
+// Cannot match on a non-exhaustive enum without including a wildcard arm.
+match error {
+  Error::Message(ref s) => { },
+  Error::Other => { },
+  // would compile with: `_ => {},`
+}
+
+// Cannot match on a non-exhaustive struct without a wildcard.
+if let Ok(Config { window_width, window_height }) = config {
+    // would compile with: `..`
+}
+
+match message {
+  // Cannot match on a non-exhaustive struct enum variant without including a wildcard.
+  Message::Send { from, to, contents } => { },
+  // Cannot match on a non-exhaustive tuple or unit enum variant.
+  Message::Reaction(type) => { },
+  Message::Quit => { },
+}
+```
+
+Non-exhaustive types are always considered inhabited in downstream crates.
+
 [Clippy]: https://github.com/rust-lang/rust-clippy
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax
 [_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
+[_MetaWord_]: ../attributes.md#meta-item-attribute-syntax
 [`Drop`]: ../special-types-and-traits.md#drop
 [attributes]: ../attributes.md
 [block expression]: ../expressions/block-expr.md
@@ -266,10 +381,12 @@ When used on a function in a trait implementation, the attribute does nothing.
 [expression]: ../expressions.md
 [external block item]: ../items/external-blocks.md
 [functions]: ../items/functions.md
+[`if let`]: ../expressions/if-expr.md#if-let-expressions
 [impl trait]: ../types/impl-trait.md
 [implementation]: ../items/implementations.md
 [item]: ../items.md
 [let statement]: ../statements.md#let-statements
+[`match`]: ../expressions/match-expr.md
 [module]: ../items/modules.md
 [rustc book]: ../../rustc/lints/index.html
 [struct field]: ../items/structs.md