Rollup merge of #24740 - mbrubeck:reference, r=steveklabnik

 r? @steveklabnik

diff --combined src/doc/reference.md
index b74f1ff213973ff9021eda413cc83b61a02c2695,44266fb40505eac42825fc17e6837a779c74ddbb..3e8aa7c3ad0b474158255176fc6a9bccb8823698
--- 1/src/doc/reference.md
--- 2/src/doc/reference.md
+++ b/src/doc/reference.md
@@@ -149,9 -149,11 +149,11 @@@ sequence (`/**`), are interpreted as a 
  `#[doc="..."]` around the body of the comment (this includes the comment
  characters themselves, ie `/// Foo` turns into `#[doc="/// Foo"]`).
  
- `//!` comments apply to the parent of the comment, rather than the item that
- follows. `//!` comments are usually used to display information on the crate
- index page.
+ Line comments beginning with `//!` and block comments beginning with `/*!` are
+ doc comments that apply to the parent of the comment, rather than the item
+ that follows.  That is, they are equivalent to writing `#![doc="..."]` around
+ the body of the comment. `//!` comments are usually used to display
+ information on the crate index page.
  
  Non-doc comments are interpreted as a form of whitespace.
  
@@@ -1555,7 -1557,7 +1557,7 @@@ fn draw_twice<T: Shape>(surface: Surfac
  }
  ```
  
 -Traits also define an [object type](#object-types) with the same name as the
 +Traits also define an [trait object](#trait-objects) with the same name as the
  trait. Values of this type are created by [casting](#type-cast-expressions)
  pointer values (pointing to a type for which an implementation of the given
  trait is in scope) to pointers to the trait name, used as a type.
@@@ -2146,7 -2148,7 +2148,7 @@@ The following configurations must be de
    `"unix"` or `"windows"`. The value of this configuration option is defined
    as a configuration itself, like `unix` or `windows`.
  * `target_os = "..."`. Operating system of the target, examples include
 -  `"win32"`, `"macos"`, `"linux"`, `"android"`, `"freebsd"`, `"dragonfly"`,
 +  `"windows"`, `"macos"`, `"ios"`, `"linux"`, `"android"`, `"freebsd"`, `"dragonfly"`,
    `"bitrig"` or `"openbsd"`.
  * `target_pointer_width = "..."`. Target pointer width in bits. This is set
    to `"32"` for targets with 32-bit pointers, and likewise set to `"64"` for
@@@ -2744,7 -2746,7 +2746,7 @@@ A _method call_ consists of an expressi
  identifier, and a parenthesized expression-list. Method calls are resolved to
  methods on specific traits, either statically dispatching to a method if the
  exact `self`-type of the left-hand-side is known, or dynamically dispatching if
 -the left-hand-side expression is an indirect [object type](#object-types).
 +the left-hand-side expression is an indirect [trait object](#trait-objects).
  
  ### Field expressions
  
@@@ -3649,23 -3651,23 +3651,23 @@@ call_closure(closure_no_args, closure_a
  
  ```
  
 -### Object types
 +### Trait objects
  
  Every trait item (see [traits](#traits)) defines a type with the same name as
 -the trait. This type is called the _object type_ of the trait. Object types
 +the trait. This type is called the _trait object_ of the trait. Trait objects
  permit "late binding" of methods, dispatched using _virtual method tables_
  ("vtables"). Whereas most calls to trait methods are "early bound" (statically
  resolved) to specific implementations at compile time, a call to a method on an
 -object type is only resolved to a vtable entry at compile time. The actual
 +trait objects is only resolved to a vtable entry at compile time. The actual
  implementation for each vtable entry can vary on an object-by-object basis.
  
  Given a pointer-typed expression `E` of type `&T` or `Box<T>`, where `T`
  implements trait `R`, casting `E` to the corresponding pointer type `&R` or
 -`Box<R>` results in a value of the _object type_ `R`. This result is
 +`Box<R>` results in a value of the _trait object_ `R`. This result is
  represented as a pair of pointers: the vtable pointer for the `T`
  implementation of `R`, and the pointer value of `E`.
  
 -An example of an object type:
 +An example of a trait object:
  
  ```
  trait Printable {
@@@ -3685,7 -3687,7 +3687,7 @@@ fn main() 
  }
  ```
  
 -In this example, the trait `Printable` occurs as an object type in both the
 +In this example, the trait `Printable` occurs as a trait object in both the
  type signature of `print`, and the cast expression in `main`.
  
  ### Type parameters