Rollup merge of #45166 - tinaun:more_unstable_docs, r=steveklabnik

Documented a few more unstable feature gates.

unboxed closures, fn_traits, and OIBIT. hope these are decent!

3 files changed, 107 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/language-features/optin-builtin-traits.md b/src/doc/unstable-book/src/language-features/optin-builtin-traits.md
new file mode 100644
index 00000000000..ee24dd87d90
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/optin-builtin-traits.md
@@ -0,0 +1,47 @@
+# `optin_builtin_traits`
+
+The tracking issue for this feature is [#13231] 
+
+[#13231]: https://github.com/rust-lang/rust/issues/13231
+
+----
+
+The `optin_builtin_traits` feature gate allows you to define auto traits.
+
+Auto traits, like [`Send`] or [`Sync`] in the standard library, are marker traits
+that are automatically implemented for every type, unless the type, or a type it contains, 
+has explictly opted out via a negative impl. 
+
+[`Send`]: https://doc.rust-lang.org/std/marker/trait.Send.html
+[`Sync`]: https://doc.rust-lang.org/std/marker/trait.Sync.html
+
+```rust,ignore
+impl !Type for Trait
+```
+
+Example:
+
+```rust
+#![feature(optin_builtin_traits)]
+
+trait Valid {}
+
+impl Valid for .. {}
+
+struct True;
+struct False;
+
+impl !Valid for False {}
+
+struct MaybeValid<T>(T);
+
+fn must_be_valid<T: Valid>(_t: T) { }
+
+fn main() {
+    // works
+    must_be_valid( MaybeValid(True) );
+                
+    // compiler error - trait bound not satisfied
+    // must_be_valid( MaybeValid(False) );
+}
+```
diff --git a/src/doc/unstable-book/src/language-features/unboxed-closures.md b/src/doc/unstable-book/src/language-features/unboxed-closures.md
new file mode 100644
index 00000000000..0eaed7a1989
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/unboxed-closures.md
@@ -0,0 +1,25 @@
+# `unboxed_closures`
+
+The tracking issue for this feature is [#29625]
+
+See Also: [`fn_traits`](library-features/fn-traits.html)
+
+[#29625]: https://github.com/rust-lang/rust/issues/29625
+
+----
+
+The `unboxed_closures` feature allows you to write functions using the `"rust-call"` ABI,
+required for implmenting the [`Fn*`] family of traits. `"rust-call"` functions must have 
+exactly one (non self) argument, a tuple representing the argument list.
+
+[`Fn*`]: https://doc.rust-lang.org/std/ops/trait.Fn.html
+
+```rust
+#![feature(unboxed_closures)]
+
+extern "rust-call" fn add_args(args: (u32, u32)) -> u32 {
+    args.0 + args.1
+}
+
+fn main() {}
+```
diff --git a/src/doc/unstable-book/src/library-features/fn-traits.md b/src/doc/unstable-book/src/library-features/fn-traits.md
new file mode 100644
index 00000000000..72a3f36c10b
--- /dev/null
+++ b/src/doc/unstable-book/src/library-features/fn-traits.md
@@ -0,0 +1,35 @@
+# `fn_traits`
+
+The tracking issue for this feature is [#29625]
+
+See Also: [`unboxed_closures`](language-features/unboxed-closures.html)
+
+[#29625]: https://github.com/rust-lang/rust/issues/29625
+
+----
+
+The `fn_traits` feature allows for implementation of the [`Fn*`] traits
+for creating custom closure-like types.
+
+[`Fn*`]: https://doc.rust-lang.org/std/ops/trait.Fn.html
+
+```rust
+#![feature(unboxed_closures)]
+#![feature(fn_traits)]
+
+struct Adder {
+    a: u32
+}
+
+impl FnOnce<(u32, )> for Adder {
+    type Output = u32;
+    extern "rust-call" fn call_once(self, b: (u32, )) -> Self::Output {
+        self.a + b.0
+    }
+}
+
+fn main() {
+    let adder = Adder { a: 3 };
+    assert_eq!(adder(2), 5);
+}
+```