Tweak std::marker docs

Fixes #29361.

src/libcore/marker.rs

@@ -8,11 +8,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Primitive traits and marker types representing basic 'kinds' of types.
+//! Primitive traits and types representing basic properties of types.
 //!
 //! Rust types can be classified in various useful ways according to
-//! intrinsic properties of the type. These classifications, often called
+//! their intrinsic properties. These classifications are represented
-//! 'kinds', are represented as traits.
+//! as traits.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -22,7 +22,21 @@ use hash::Hasher;
 
 /// Types that can be transferred across thread boundaries.
 ///
-/// This trait is automatically derived when the compiler determines it's appropriate.
+/// This trait is automatically implemented when the compiler determines it's
+/// appropriate.
+///
+/// An example of a non-`Send` type is the reference-counting pointer
+/// [`rc::Rc`][rc]. If two threads attempt to clone `Rc`s that point to the same
+/// reference-counted value, they might try to update the reference count at the
+/// same time, which is [undefined behavior][ub] because `Rc` doesn't use atomic
+/// operations. Its cousin [`sync::Arc`][arc] does use atomic operations (incurring
+/// some overhead) and thus is `Send`.
+///
+/// See [the Nomicon](../../nomicon/send-and-sync.html) for more details.
+///
+/// [rc]: ../../std/rc/struct.Rc.html
+/// [arc]: ../../std/sync/struct.Arc.html
+/// [ub]: ../../reference.html#behavior-considered-undefined
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "send"]
 #[rustc_on_unimplemented = "`{Self}` cannot be sent between threads safely"]
@@ -38,10 +52,10 @@ impl<T: ?Sized> !Send for *const T { }
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> !Send for *mut T { }
 
-/// Types with a constant size known at compile-time.
+/// Types with a constant size known at compile time.
 ///
-/// All type parameters which can be bounded have an implicit bound of `Sized`. The special syntax
+/// All type parameters have an implicit bound of `Sized`. The special syntax
-/// `?Sized` can be used to remove this bound if it is not appropriate.
+/// `?Sized` can be used to remove this bound if it's not appropriate.
 ///
 /// ```
 /// # #![allow(dead_code)]
@@ -51,6 +65,26 @@ impl<T: ?Sized> !Send for *mut T { }
 /// // struct FooUse(Foo<[i32]>); // error: Sized is not implemented for [i32]
 /// struct BarUse(Bar<[i32]>); // OK
 /// ```
+///
+/// The one exception is the implicit `Self` type of a trait, which does not
+/// get an implicit `Sized` bound. This is because a `Sized` bound prevents
+/// the trait from being used to form a [trait object]:
+///
+/// ```
+/// # #![allow(unused_variables)]
+/// trait Foo { }
+/// trait Bar: Sized { }
+///
+/// struct Impl;
+/// impl Foo for Impl { }
+/// impl Bar for Impl { }
+///
+/// let x: &Foo = &Impl;    // OK
+/// // let y: &Bar = &Impl; // error: the trait `Bar` cannot
+///                         // be made into an object
+/// ```
+///
+/// [trait object]: ../../book/trait-objects.html
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "sized"]
 #[rustc_on_unimplemented = "`{Self}` does not have a constant size known at compile-time"]
@@ -59,14 +93,27 @@ pub trait Sized {
     // Empty.
 }
 
-/// Types that can be "unsized" to a dynamically sized type.
+/// Types that can be "unsized" to a dynamically-sized type.
+///
+/// For example, the sized array type `[i8; 2]` implements `Unsize<[i8]>` and
+/// `Unsize<fmt::Debug>`.
+///
+/// All implementations of `Unsize` are provided automatically by the compiler.
+///
+/// `Unsize` is used along with [`ops::CoerceUnsized`][coerceunsized] to allow
+/// "user-defined" containers such as [`rc::Rc`][rc] to contain dynamically-sized
+/// types. See the [DST coercion RFC][RFC982] for more details.
+///
+/// [coerceunsized]: ../ops/trait.CoerceUnsized.html
+/// [rc]: ../../std/rc/struct.Rc.html
+/// [RFC982]: https://github.com/rust-lang/rfcs/blob/master/text/0982-dst-coercion.md
 #[unstable(feature = "unsize", issue = "27732")]
 #[lang="unsize"]
 pub trait Unsize<T: ?Sized> {
     // Empty.
 }
 
-/// Types that can be copied by simply copying bits (i.e. `memcpy`).
+/// Types whose values can be duplicated simply by copying bits.
 ///
 /// By default, variable bindings have 'move semantics.' In other
 /// words:
@@ -87,7 +134,8 @@ pub trait Unsize<T: ?Sized> {
 /// However, if a type implements `Copy`, it instead has 'copy semantics':
 ///
 /// ```
-/// // we can just derive a `Copy` implementation
+/// // We can derive a `Copy` implementation. `Clone` is also required, as it's
+/// // a supertrait of `Copy`.
 /// #[derive(Debug, Copy, Clone)]
 /// struct Foo;
 ///
@@ -100,13 +148,59 @@ pub trait Unsize<T: ?Sized> {
 /// println!("{:?}", x); // A-OK!
 /// ```
 ///
-/// It's important to note that in these two examples, the only difference is if you are allowed to
+/// It's important to note that in these two examples, the only difference is whether you
-/// access `x` after the assignment: a move is also a bitwise copy under the hood.
+/// are allowed to access `x` after the assignment. Under the hood, both a copy and a move
+/// can result in bits being copied in memory, although this is sometimes optimized away.
+///
+/// ## How can I implement `Copy`?
+///
+/// There are two ways to implement `Copy` on your type. The simplest is to use `derive`:
+///
+/// ```
+/// #[derive(Copy, Clone)]
+/// struct MyStruct;
+/// ```
+///
+/// You can also implement `Copy` and `Clone` manually:
+///
+/// ```
+/// struct MyStruct;
+///
+/// impl Copy for MyStruct { }
+///
+/// impl Clone for MyStruct {
+///     fn clone(&self) -> MyStruct {
+///         *self
+///     }
+/// }
+/// ```
+///
+/// There is a small difference between the two: the `derive` strategy will also place a `Copy`
+/// bound on type parameters, which isn't always desired.
+///
+/// ## What's the difference between `Copy` and `Clone`?
+///
+/// Copies happen implicitly, for example as part of an assignment `y = x`. The behavior of
+/// `Copy` is not overloadable; it is always a simple bit-wise copy.
+///
+/// Cloning is an explicit action, `x.clone()`. The implementation of [`Clone`][clone] can
+/// provide any type-specific behavior necessary to duplicate values safely. For example,
+/// the implementation of `Clone` for [`String`][string] needs to copy the pointed-to string
+/// buffer in the heap. A simple bitwise copy of `String` values would merely copy the
+/// pointer, leading to a double free down the line. For this reason, `String` is `Clone`
+/// but not `Copy`.
+///
+/// `Clone` is a supertrait of `Copy`, so everything which is `Copy` must also implement
+/// `Clone`. If a type is `Copy` then its `Clone` implementation need only return `*self`
+/// (see the example above).
+///
+/// [clone]: ../clone/trait.Clone.html
+/// [string]: ../../std/string/struct.String.html
 ///
 /// ## When can my type be `Copy`?
 ///
 /// A type can implement `Copy` if all of its components implement `Copy`. For example, this
-/// `struct` can be `Copy`:
+/// struct can be `Copy`:
 ///
 /// ```
 /// # #[allow(dead_code)]
@@ -116,7 +210,8 @@ pub trait Unsize<T: ?Sized> {
 /// }
 /// ```
 ///
-/// A `struct` can be `Copy`, and `i32` is `Copy`, so therefore, `Point` is eligible to be `Copy`.
+/// A struct can be `Copy`, and `i32` is `Copy`, therefore `Point` is eligible to be `Copy`.
+/// By contrast, consider
 ///
 /// ```
 /// # #![allow(dead_code)]
@@ -126,57 +221,35 @@ pub trait Unsize<T: ?Sized> {
 /// }
 /// ```
 ///
-/// The `PointList` `struct` cannot implement `Copy`, because [`Vec<T>`] is not `Copy`. If we
+/// The struct `PointList` cannot implement `Copy`, because [`Vec<T>`] is not `Copy`. If we
 /// attempt to derive a `Copy` implementation, we'll get an error:
 ///
 /// ```text
 /// the trait `Copy` may not be implemented for this type; field `points` does not implement `Copy`
 /// ```
 ///
-/// ## When can my type _not_ be `Copy`?
+/// ## When *can't* my type be `Copy`?
 ///
 /// Some types can't be copied safely. For example, copying `&mut T` would create an aliased
-/// mutable reference, and copying [`String`] would result in two attempts to free the same buffer.
+/// mutable reference. Copying [`String`] would duplicate responsibility for managing the `String`'s
+/// buffer, leading to a double free.
 ///
 /// Generalizing the latter case, any type implementing [`Drop`] can't be `Copy`, because it's
 /// managing some resource besides its own [`size_of::<T>()`] bytes.
 ///
-/// ## What if I derive `Copy` on a type that can't?
+/// If you try to implement `Copy` on a struct or enum containing non-`Copy` data, you will get a
+/// compile-time error. Specifically, with structs you'll get [E0204] and with enums you'll get
+/// [E0205].
 ///
-/// If you try to derive `Copy` on a struct or enum, you will get a compile-time error.
+/// [E0204]: https://doc.rust-lang.org/error-index.html#E0204
-/// Specifically, with structs you'll get [E0204](https://doc.rust-lang.org/error-index.html#E0204)
+/// [E0205]: https://doc.rust-lang.org/error-index.html#E0205
-/// and with enums you'll get [E0205](https://doc.rust-lang.org/error-index.html#E0205).
 ///
-/// ## When should my type be `Copy`?
+/// ## When *should* my type be `Copy`?
 ///
-/// Generally speaking, if your type _can_ implement `Copy`, it should. There's one important thing
+/// Generally speaking, if your type _can_ implement `Copy`, it should. Keep in mind, though,
-/// to consider though: if you think your type may _not_ be able to implement `Copy` in the future,
+/// that implementing `Copy` is part of the public API of your type. If the type might become
-/// then it might be prudent to not implement `Copy`. This is because removing `Copy` is a breaking
+/// non-`Copy` in the future, it could be prudent to omit the `Copy` implementation now, to
-/// change: that second example would fail to compile if we made `Foo` non-`Copy`.
+/// avoid a breaking API change.
-///
-/// ## Derivable
-///
-/// This trait can be used with `#[derive]` if all of its components implement `Copy` and the type.
-///
-/// ## How can I implement `Copy`?
-///
-/// There are two ways to implement `Copy` on your type:
-///
-/// ```
-/// #[derive(Copy, Clone)]
-/// struct MyStruct;
-/// ```
-///
-/// and
-///
-/// ```
-/// struct MyStruct;
-/// impl Copy for MyStruct {}
-/// impl Clone for MyStruct { fn clone(&self) -> MyStruct { *self } }
-/// ```
-///
-/// There is a small difference between the two: the `derive` strategy will also place a `Copy`
-/// bound on type parameters, which isn't always desired.
 ///
 /// [`Vec<T>`]: ../../std/vec/struct.Vec.html
 /// [`String`]: ../../std/string/struct.String.html
@@ -188,64 +261,74 @@ pub trait Copy : Clone {
     // Empty.
 }
 
-/// Types that can be safely shared between threads when aliased.
+/// Types for which it is safe to share references between threads.
+///
+/// This trait is automatically implemented when the compiler determines
+/// it's appropriate.
 ///
 /// The precise definition is: a type `T` is `Sync` if `&T` is
-/// thread-safe. In other words, there is no possibility of data races
+/// [`Send`][send]. In other words, if there is no possibility of
-/// when passing `&T` references between threads.
+/// [undefined behavior][ub] (including data races) when passing
+/// `&T` references between threads.
 ///
-/// As one would expect, primitive types like [`u8`] and [`f64`] are all
+/// As one would expect, primitive types like [`u8`][u8] and [`f64`][f64]
-/// `Sync`, and so are simple aggregate types containing them (like
+/// are all `Sync`, and so are simple aggregate types containing them,
-/// tuples, structs and enums). More instances of basic `Sync` types
+/// like tuples, structs and enums. More examples of basic `Sync`
-/// include "immutable" types like `&T` and those with simple
+/// types include "immutable" types like `&T`, and those with simple
-/// inherited mutability, such as [`Box<T>`], [`Vec<T>`] and most other
+/// inherited mutability, such as [`Box<T>`][box], [`Vec<T>`][vec] and
-/// collection types. (Generic parameters need to be `Sync` for their
+/// most other collection types. (Generic parameters need to be `Sync`
-/// container to be `Sync`.)
+/// for their container to be `Sync`.)
 ///
-/// A somewhat surprising consequence of the definition is `&mut T` is
+/// A somewhat surprising consequence of the definition is that `&mut T`
-/// `Sync` (if `T` is `Sync`) even though it seems that it might
+/// is `Sync` (if `T` is `Sync`) even though it seems like that might
-/// provide unsynchronized mutation. The trick is a mutable reference
+/// provide unsynchronized mutation. The trick is that a mutable
-/// stored in an aliasable reference (that is, `& &mut T`) becomes
+/// reference behind a shared reference (that is, `& &mut T`)
-/// read-only, as if it were a `& &T`, hence there is no risk of a data
+/// becomes read-only, as if it were a `& &T`. Hence there is no risk
-/// race.
+/// of a data race.
 ///
 /// Types that are not `Sync` are those that have "interior
-/// mutability" in a non-thread-safe way, such as [`Cell`] and [`RefCell`]
+/// mutability" in a non-thread-safe form, such as [`cell::Cell`][cell]
-/// in [`std::cell`]. These types allow for mutation of their contents
+/// and [`cell::RefCell`][refcell]. These types allow for mutation of
-/// even when in an immutable, aliasable slot, e.g. the contents of
+/// their contents even through an immutable, shared reference. For
-/// [`&Cell<T>`][`Cell`] can be [`.set`], and do not ensure data races are
+/// example the `set` method on `Cell<T>` takes `&self`, so it requires
-/// impossible, hence they cannot be `Sync`. A higher level example
+/// only a shared reference `&Cell<T>`. The method performs no
-/// of a non-`Sync` type is the reference counted pointer
+/// synchronization, thus `Cell` cannot be `Sync`.
-/// [`std::rc::Rc`][`Rc`], because any reference [`&Rc<T>`][`Rc`] can clone a new
+///
-/// reference, which modifies the reference counts in a non-atomic
+/// Another example of a non-`Sync` type is the reference-counting
-/// way.
+/// pointer [`rc::Rc`][rc]. Given any reference `&Rc<T>`, you can clone
+/// a new `Rc<T>`, modifying the reference counts in a non-atomic way.
 ///
 /// For cases when one does need thread-safe interior mutability,
-/// types like the atomics in [`std::sync`][`sync`] and [`Mutex`] / [`RwLock`] in
+/// Rust provides [atomic data types], as well as explicit locking via
-/// the [`sync`] crate do ensure that any mutation cannot cause data
+/// [`sync::Mutex`][mutex] and [`sync::RWLock`][rwlock]. These types
-/// races.  Hence these types are `Sync`.
+/// ensure that any mutation cannot cause data races, hence the types
+/// are `Sync`. Likewise, [`sync::Arc`][arc] provides a thread-safe
+/// analogue of `Rc`.
 ///
-/// Any types with interior mutability must also use the [`std::cell::UnsafeCell`]
+/// Any types with interior mutability must also use the
-/// wrapper around the value(s) which can be mutated when behind a `&`
+/// [`cell::UnsafeCell`][unsafecell] wrapper around the value(s) which
-/// reference; not doing this is undefined behavior (for example,
+/// can be mutated through a shared reference. Failing to doing this is
-/// [`transmute`]-ing from `&T` to `&mut T` is invalid).
+/// [undefined behavior][ub]. For example, [`transmute`][transmute]-ing
+/// from `&T` to `&mut T` is invalid.
 ///
-/// This trait is automatically derived when the compiler determines it's appropriate.
+/// See [the Nomicon](../../nomicon/send-and-sync.html) for more
+/// details about `Sync`.
 ///
-/// [`u8`]: ../../std/primitive.u8.html
+/// [send]: trait.Send.html
-/// [`f64`]: ../../std/primitive.f64.html
+/// [u8]: ../../std/primitive.u8.html
-/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
+/// [f64]: ../../std/primitive.f64.html
-/// [`Box<T>`]: ../../std/boxed/struct.Box.html
+/// [box]: ../../std/boxed/struct.Box.html
-/// [`Cell`]: ../../std/cell/struct.Cell.html
+/// [vec]: ../../std/vec/struct.Vec.html
-/// [`RefCell`]: ../../std/cell/struct.RefCell.html
+/// [cell]: ../cell/struct.Cell.html
-/// [`std::cell`]: ../../std/cell/index.html
+/// [refcell]: ../cell/struct.RefCell.html
-/// [`.set`]: ../../std/cell/struct.Cell.html#method.set
+/// [rc]: ../../std/rc/struct.Rc.html
-/// [`Rc`]: ../../std/rc/struct.Rc.html
+/// [arc]: ../../std/sync/struct.Arc.html
-/// [`sync`]: ../../std/sync/index.html
+/// [atomic data types]: ../sync/atomic/index.html
-/// [`Mutex`]: ../../std/sync/struct.Mutex.html
+/// [mutex]: ../../std/sync/struct.Mutex.html
-/// [`RwLock`]: ../../std/sync/struct.RwLock.html
+/// [rwlock]: ../../std/sync/struct.RwLock.html
-/// [`std::cell::UnsafeCell`]: ../../std/cell/struct.UnsafeCell.html
+/// [unsafecell]: ../cell/struct.UnsafeCell.html
-/// [`transmute`]: ../../std/mem/fn.transmute.html
+/// [ub]: ../../reference.html#behavior-considered-undefined
+/// [transmute]: ../../std/mem/fn.transmute.html
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "sync"]
 #[rustc_on_unimplemented = "`{Self}` cannot be shared between threads safely"]
@@ -314,29 +397,30 @@ macro_rules! impls{
         )
 }
 
-/// `PhantomData<T>` allows you to describe that a type acts as if it stores a value of type `T`,
+/// Zero-sized type used to mark things that "act like" they own a `T`.
-/// even though it does not. This allows you to inform the compiler about certain safety properties
-/// of your code.
 ///
-/// For a more in-depth explanation of how to use `PhantomData<T>`, please see [the Nomicon].
+/// Adding a `PhantomData<T>` field to your type tells the compiler that your
+/// type acts as though it stores a value of type `T`, even though it doesn't
+/// really. This information is used when computing certain safety properties.
 ///
-/// [the Nomicon]: ../../nomicon/phantom-data.html
+/// For a more in-depth explanation of how to use `PhantomData<T>`, please see
+/// [the Nomicon](../../nomicon/phantom-data.html).
 ///
 /// # A ghastly note 👻👻👻
 ///
-/// Though they both have scary names, `PhantomData<T>` and 'phantom types' are related, but not
+/// Though they both have scary names, `PhantomData` and 'phantom types' are
-/// identical. Phantom types are a more general concept that don't require `PhantomData<T>` to
+/// related, but not identical. A phantom type parameter is simply a type
-/// implement, but `PhantomData<T>` is the most common way to implement them in a correct manner.
+/// parameter which is never used. In Rust, this often causes the compiler to
+/// complain, and the solution is to add a "dummy" use by way of `PhantomData`.
 ///
 /// # Examples
 ///
-/// ## Unused lifetime parameter
+/// ## Unused lifetime parameters
 ///
-/// Perhaps the most common time that `PhantomData` is required is
+/// Perhaps the most common use case for `PhantomData` is a struct that has an
-/// with a struct that has an unused lifetime parameter, typically as
+/// unused lifetime parameter, typically as part of some unsafe code. For
-/// part of some unsafe code. For example, here is a struct `Slice`
+/// example, here is a struct `Slice` that has two pointers of type `*const T`,
-/// that has two pointers of type `*const T`, presumably pointing into
+/// presumably pointing into an array somewhere:
-/// an array somewhere:
 ///
 /// ```ignore
 /// struct Slice<'a, T> {
@@ -350,7 +434,7 @@ macro_rules! impls{
 /// intent is not expressed in the code, since there are no uses of
 /// the lifetime `'a` and hence it is not clear what data it applies
 /// to. We can correct this by telling the compiler to act *as if* the
-/// `Slice` struct contained a borrowed reference `&'a T`:
+/// `Slice` struct contained a reference `&'a T`:
 ///
 /// ```
 /// use std::marker::PhantomData;
@@ -359,29 +443,53 @@ macro_rules! impls{
 /// struct Slice<'a, T: 'a> {
 ///     start: *const T,
 ///     end: *const T,
-///     phantom: PhantomData<&'a T>
+///     phantom: PhantomData<&'a T>,
 /// }
 /// ```
 ///
-/// This also in turn requires that we annotate `T:'a`, indicating
+/// This also in turn requires the annotation `T: 'a`, indicating
-/// that `T` is a type that can be borrowed for the lifetime `'a`.
+/// that any references in `T` are valid over the lifetime `'a`.
 ///
-/// ## Unused type parameters
+/// When initializing a `Slice` you simply provide the value
-///
+/// `PhantomData` for the field `phantom`:
-/// It sometimes happens that there are unused type parameters that
-/// indicate what type of data a struct is "tied" to, even though that
-/// data is not actually found in the struct itself. Here is an
-/// example where this arises when handling external resources over a
-/// foreign function interface. `PhantomData<T>` can prevent
-/// mismatches by enforcing types in the method implementations:
 ///
 /// ```
 /// # #![allow(dead_code)]
-/// # trait ResType { fn foo(&self); }
+/// # use std::marker::PhantomData;
+/// # struct Slice<'a, T: 'a> {
+/// #     start: *const T,
+/// #     end: *const T,
+/// #     phantom: PhantomData<&'a T>,
+/// # }
+/// fn borrow_vec<'a, T>(vec: &'a Vec<T>) -> Slice<'a, T> {
+///     let ptr = vec.as_ptr();
+///     Slice {
+///         start: ptr,
+///         end: unsafe { ptr.offset(vec.len() as isize) },
+///         phantom: PhantomData,
+///     }
+/// }
+/// ```
+///
+/// ## Unused type parameters
+///
+/// It sometimes happens that you have unused type parameters which
+/// indicate what type of data a struct is "tied" to, even though that
+/// data is not actually found in the struct itself. Here is an
+/// example where this arises with [FFI]. The foreign interface uses
+/// handles of type `*mut ()` to refer to Rust values of different
+/// types. We track the Rust type using a phantom type parameter on
+/// the struct `ExternalResource` which wraps a handle.
+///
+/// [FFI]: ../../book/ffi.html
+///
+/// ```
+/// # #![allow(dead_code)]
+/// # trait ResType { }
 /// # struct ParamType;
 /// # mod foreign_lib {
-/// # pub fn new(_: usize) -> *mut () { 42 as *mut () }
+/// #     pub fn new(_: usize) -> *mut () { 42 as *mut () }
-/// # pub fn do_stuff(_: *mut (), _: usize) {}
+/// #     pub fn do_stuff(_: *mut (), _: usize) {}
 /// # }
 /// # fn convert_params(_: ParamType) -> usize { 42 }
 /// use std::marker::PhantomData;
@@ -408,21 +516,20 @@ macro_rules! impls{
 /// }
 /// ```
 ///
-/// ## Indicating ownership
+/// ## Ownership and the drop check
 ///
-/// Adding a field of type `PhantomData<T>` also indicates that your
+/// Adding a field of type `PhantomData<T>` indicates that your
-/// struct owns data of type `T`. This in turn implies that when your
+/// type owns data of type `T`. This in turn implies that when your
-/// struct is dropped, it may in turn drop one or more instances of
+/// type is dropped, it may drop one or more instances of the type
-/// the type `T`, though that may not be apparent from the other
+/// `T`. This has bearing on the Rust compiler's [drop check]
-/// structure of the type itself. This is commonly necessary if the
+/// analysis.
-/// structure is using a raw pointer like `*mut T` whose referent
-/// may be dropped when the type is dropped, as a `*mut T` is
-/// otherwise not treated as owned.
 ///
 /// If your struct does not in fact *own* the data of type `T`, it is
 /// better to use a reference type, like `PhantomData<&'a T>`
 /// (ideally) or `PhantomData<*const T>` (if no lifetime applies), so
 /// as not to indicate ownership.
+///
+/// [drop check]: ../../nomicon/dropck.html
 #[lang = "phantom_data"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct PhantomData<T:?Sized>;
@@ -438,10 +545,13 @@ mod impls {
 
 /// Types that can be reflected over.
 ///
-/// This trait is implemented for all types. Its purpose is to ensure
+/// By "reflection" we mean use of the [`Any`][any] trait, or related
-/// that when you write a generic function that will employ
+/// machinery such as [`TypeId`][typeid].
-/// reflection, that must be reflected (no pun intended) in the
+///
-/// generic bounds of that function. Here is an example:
+/// `Reflect` is implemented for all types. Its purpose is to ensure
+/// that when you write a generic function that will employ reflection,
+/// that must be reflected (no pun intended) in the generic bounds of
+/// that function.
 ///
 /// ```
 /// #![feature(reflect_marker)]
@@ -455,21 +565,24 @@ mod impls {
 /// }
 /// ```
 ///
-/// Without the declaration `T: Reflect`, `foo` would not type check
+/// Without the bound `T: Reflect`, `foo` would not typecheck. (As
-/// (note: as a matter of style, it would be preferable to write
+/// a matter of style, it would be preferable to write `T: Any`,
-/// `T: Any`, because `T: Any` implies `T: Reflect` and `T: 'static`, but
+/// because `T: Any` implies `T: Reflect` and `T: 'static`, but we
-/// we use `Reflect` here to show how it works). The `Reflect` bound
+/// use `Reflect` here for illustrative purposes.)
-/// thus serves to alert `foo`'s caller to the fact that `foo` may
-/// behave differently depending on whether `T = u32` or not. In
-/// particular, thanks to the `Reflect` bound, callers know that a
-/// function declared like `fn bar<T>(...)` will always act in
-/// precisely the same way no matter what type `T` is supplied,
-/// because there are no bounds declared on `T`. (The ability for a
-/// caller to reason about what a function may do based solely on what
-/// generic bounds are declared is often called the ["parametricity
-/// property"][1].)
 ///
-/// [1]: http://en.wikipedia.org/wiki/Parametricity
+/// The `Reflect` bound serves to alert `foo`'s caller to the
+/// fact that `foo` may behave differently depending on whether
+/// `T` is `u32` or not. The ability for a caller to reason about what
+/// a function may do based solely on what generic bounds are declared
+/// is often called the "[parametricity property][param]". Despite the
+/// use of `Reflect`, Rust lacks true parametricity because a generic
+/// function can, at the very least, call [`mem::size_of`][size_of]
+/// without employing any trait bounds whatsoever.
+///
+/// [any]: ../any/trait.Any.html
+/// [typeid]: ../any/struct.TypeId.html
+/// [param]: http://en.wikipedia.org/wiki/Parametricity
+/// [size_of]: ../mem/fn.size_of.html
 #[rustc_reflect_like]
 #[unstable(feature = "reflect_marker",
            reason = "requires RFC and more experience",