Rewrite the special traits section

Author: matthewjasper

src/SUMMARY.md

@@ -68,13 +68,7 @@
     - [Type coercions](type-coercions.md)
     - [Destructors](destructors.md)
 
-- [Special traits](special-traits.md)
-    - [The Copy trait](the-copy-trait.md)
-    - [The Sized trait](the-sized-trait.md)
-    - [The Drop trait](the-drop-trait.md)
-    - [The Deref trait](the-deref-trait.md)
-    - [The Send trait](the-send-trait.md)
-    - [The Sync trait](the-sync-trait.md)
+- [Special types and traits](special-types-and-traits.md)
 
 - [Memory model](memory-model.md)
     - [Memory allocation and lifetime](memory-allocation-and-lifetime.md)

src/dynamically-sized-types.md

@@ -23,7 +23,7 @@ types">DSTs</abbr>. Such types can only be used in certain cases:
 Notably: [variables], function parameters, [const] and [static] items must be
 `Sized`.
 
-[sized]: the-sized-trait.html
+[sized]: special-types-and-traits.html#sized
 [Slices]: types.html#array-and-slice-types
 [trait objects]: types.html#trait-objects
 [Pointer types]: types.html#pointer-types

src/expressions.md

@@ -68,13 +68,14 @@ other expression contexts are rvalue contexts.
 When an lvalue is evaluated in an _rvalue context_ or is bound by value in a
 pattern, it denotes the value held _in_ that memory location. If value is of a
 type that implements `Copy`, then the value will be copied. In the remaining
-situations if the type of the value is [`Sized`](the-sized-trait.html) it may
-be possible to move the value. Only the following lvalues may be moved out of:
+situations if the type of the value is
+[`Sized`](special-types-and-traits.html#sized) it may be possible to move the
+value. Only the following lvalues may be moved out of:
 
 * [Variables](variables.html) which are not currently borrowed.
 * [Temporary values](#temporary-lifetimes).
 * [Field]s of an lvalue which can be moved out of and
-  doesn't implement [`Drop`](the-drop-trait.html).
+  doesn't implement [`Drop`](special-types-and-traits.html#drop).
 * The result of [dereferencing] an expression with type `Box<T>` and that can
   also be moved out of.
 
@@ -216,7 +217,8 @@ also constant expressions:
   Recursively defining constants is not allowed.
 * [Tuple expressions].
 * [Array expressions].
-* [Struct] expressions, where the type does not implement [`Drop`](the-drop-trait.html).
+* [Struct] expressions, where the type does not implement
+  [`Drop`](special-types-and-traits.html#drop).
 * [Enum variant] expressions, where the enumeration type does not implement `Drop`.
 * [Block expressions]&nbsp;(and `unsafe` blocks) which only contain items and
   possibly a (constant) tail expression.

src/expressions/array-expr.md

@@ -14,7 +14,7 @@ such as a [literal](tokens.html#literals) or a [constant
 item](items/constant-items.html). `[a; b]` creates an array containing `b`
 copies of the value of `a`. If the expression after the semi-colon has a value
 greater than 1 then this requires that the type of `a` is
-[`Copy`](the-copy-trait.html).
+[`Copy`](special-types-and-traits.html#copy).
 
 ```rust
 [1, 2, 3, 4];

src/expressions/closure-expr.md

@@ -31,9 +31,10 @@ closure's type is `'static`.
 The compiler will determine which of the [closure
 traits](types.html#closure-types) the closure's type will implement by how it
 acts on its captured variables. The closure will also implement
-[`Send`](the-send-trait.html) and/or [`Sync`](the-sync-trait.html) if all of
-its captured types do. These traits allow functions to accept closures using
-generics, even though the exact types can't be named.
+[`Send`](special-types-and-traits.html#send) and/or
+[`Sync`](special-types-and-traits.html#sync) if all of its captured types do.
+These traits allow functions to accept closures using generics, even though the
+exact types can't be named.
 
 In this example, we define a function `ten_times` that takes a higher-order
 function argument, and we then call it with a closure expression as an argument,

src/expressions/field-expr.md

@@ -25,9 +25,9 @@ possible. In cases of ambiguity, we prefer fewer autoderefs to more.
 
 Finally, the fields of a struct or a reference to a struct are treated as
 separate entities when borrowing. If the struct does not implement
-[`Drop`](the-drop-trait.html) and is stored in a local variable, this also
-applies to moving out of each of its fields. This also does not apply if
-automatic dereferencing is done though user defined types.
+[`Drop`](special-types-and-traits.html#drop) and is stored in a local variable,
+this also applies to moving out of each of its fields. This also does not apply
+if automatic dereferencing is done though user defined types.
 
 ```rust
 struct A { f1: String, f2: String, f3: String }

src/items/constant-items.md

@@ -37,4 +37,4 @@ const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
 
 [constant value]: expressions.html#constant-expressions
 [static lifetime elision]: items/static-items.html#static-lifetime-elision
-[`Drop`]: the-drop-trait.html
+[`Drop`]: special-types-and-traits.html#drop

src/special-traits.md

@@ -0,0 +1,127 @@
+# Special types and traits
+
+Certain types and traits that exist in [the standard library] are known to the
+Rust compiler (usually by [lang items]). This chapter documents the special
+features of these types and traits.
+
+## `Box<T>`
+
+[`Box<T>`] has a few special features that Rust doesn't currently allow for user
+defined types.
+
+* The [dereference operator] for `Box<T>` produces an lvalue which can be moved
+  from. This means that the `*` operator and the destructor of `Box<T>` are
+  built in to the language.
+* [Methods] can take `Box<Self>` as a receiver.
+* For the purpose of the [orphan rules], `Box<T>` is treated as being defined in
+  the same crate as `T` (rather than in `alloc`).
+
+## `UnsafeCell<T>`
+
+[`std::cell::UnsafeCell<T>`] is used for [interior mutability]. It ensures that
+the compiler doesn't perform optimisations that are incorrect for such types.
+It also ensures that [`static` items] which have a type with interior
+mutability aren't placed in memory marked as read only.
+
+## `PhantomData<T>`
+
+[`std::marker::PhantomData<T>`] is a zero-sized, minimum alignment, type that
+is considered to own a `T` for the purposes of [variance] and [drop check].
+
+## Operator Traits
+
+The traits in [`std::ops`] and [`std::cmp`] are used to overload [operators],
+[indexing expressions] and [call expressions].
+
+## `Deref` and `DerefMut`
+
+As well as overloading the unary `*` operator, [`Deref`] and [`DerefMut`] are
+also used in [method resolution] and [deref coercions].
+
+## `Drop`
+
+The [`Drop`] trait provides a [destructor], to be run whenever a value of this
+type is to be destroyed.
+
+## `Copy`
+
+The [`Copy`] trait changes the semantics of a type implementing it. Values
+whose type implements `Copy` are copied rather than moved upon assignment.
+`Copy` cannot be implemented for types which implement `Drop`, or which have
+fields that are not `Copy`. `Copy` is implemented by the compiler for
+
+* [Numeric types]
+* `char` and `bool`
+* [Tuples] of `Copy` types
+* [Arrays] of `Copy` types
+* [Shared references]
+* [Raw pointers]
+* [Function pointers] and [function item types]
+
+## `Clone`
+
+The [`Clone`] trait is implemented by the compiler for the following types:
+
+* Types with a built-in `Copy` implementation (see above)
+* [Tuples] of `Clone` types
+* [Arrays] of `Clone` types
+
+## `Send`
+
+The [`Send`] trait indicates that a value of this type is safe to send from one
+thread to another. This trait is automatically implemented for types that
+only contain types which are `Send`. This trait can be added as a bound to any
+[trait object].
+
+## `Sync`
+
+The [`Sync`] trait indicates that a value of this type is safe to share between
+multiple threads, that is a shared reference to this type is `Send`. This trait
+is automatically implemented for types that only contain types which are
+`Send`. This trait must be implemented for all types used in [`static` items].
+This trait can be added as a bound to any [trait object].
+
+## `Sized`
+
+The [`Sized`] trait indicates that the size of this type is known at
+compile-time, that is, it's not a [dynamically sized type]. [Type parameters]
+are `Sized` by default. `Sized` is always implemented automatically by the
+compiler, not by [implementation items].
+
+[the standard library]: ../std/index.html
+[lang items]: attributes.html#language-items
+[`Box<T>`]: ../std/boxed/struct.Box.html
+[dereference operator]: expressions/operator-expr.html#the-dereference-operator
+[Methods]: items.html#associated-functions-and-methods
+[`std::cell::UnsafeCell<T>`]: ../std/cell/struct.UnsafeCell.html
+[interior mutability]: iterior-mutability.html
+[`std::marker::PhantomData<T>`]: ../std/marker/struct.PhantomData.html
+[variance]: ../nomicon/subtyping.html
+[drop check]: ../nomicon/dropck.html
+[operators]: expressions/operator-expr.html
+[`std::ops`]: ../std/ops/index.html
+[`std::cmp`]: ../std/cmp/index.html
+[indexing expressions]: expressions/array-expr.html#array-and-slice-indexing-expressions
+[call expressions]: expressoins/call-expr.html
+[`Deref`]: ../std/ops/trait.Deref.html
+[`DerefMut`]: ../std/ops/trait.DerefMut.html
+[method resolution]: expressions/method-call-expr.html
+[deref coercions]: type-coercions.html#coercion-types
+[`Drop`]: ../std/ops/trait.Drop.html
+[destructor]: destructors.html
+[`Copy`]: ../std/marker/trait.Copy.html
+[Numeric types]: types.html#numeric-types
+[Tuples]: types.html#tuple-types
+[Arrays]: types.html#array-and-slice-types
+[Shared references]: types.html#shared-references-
+[Raw pointers]: types.html#raw-pointers-const-and-mut
+[Function pointers]: types.html#function-pointer-types
+[function item types]: types.html#function-item-types
+[`Clone`]: ../std/clone/trait.Clone.html
+[`Send`]: ../std/marker/trait.Send.html
+[`static` items]: items/static-items.html
+[`Sync`]: ../std/marker/trait.Sync.html
+[`Sized`]: ../std/marker/trait.Sized.html
+[dynamically sized type]: dynamically-sized-types.html
+[Type parameters]: types.html#type-parameters
+[implementation items]: items.html/implementations.html

src/special-types-and-traits.md

@@ -215,7 +215,7 @@ to read from a union field or to write to a field that doesn't implement
 The memory layout of a `union` is undefined by default, but the `#[repr(...)]`
 attribute can be used to fix a layout.
 
-[`Copy`]: the-copy-trait.html
+[`Copy`]: special-types-and-traits.html#copy
 
 ## Recursive types
 

src/the-copy-trait.md

@@ -9,6 +9,6 @@ Rust:
 - Dereferencing a [raw pointer](types.html#pointer-types).
 - Reading or writing a [mutable static variable](items/static-items.html#mutable-statics).
 - Reading a field of a [`union`](items/unions.html), or writing to a field of a
-  union that isn't [`Copy`](the-copy-trait.html).
+  union that isn't [`Copy`](special-types-and-traits.html#copy).
 - Calling an unsafe function (including an intrinsic or foreign function).
 - Implementing an unsafe trait.