Keyword docs

Co-Authored-By: Mazdak Farrokhzad <twingoow@gmail.com>
Co-Authored-By: Tim Robinson <tim.g.robinson@gmail.com>
Co-Authored-By: Peter Todd <pete@petertodd.org>
Co-Authored-By: Dylan DPC <dylan.dpc@gmail.com>
This commit is contained in:
Giles Cope 2020-02-11 20:36:36 +00:00
parent 84d8f9ddd3
commit 8e26ad0c2c

View File

@ -1100,10 +1100,28 @@ mod trait_keyword {}
//
/// A value of type [`bool`] representing logical **true**.
///
/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
/// Logically `true` is not equal to [`false`].
///
/// ## Control structures that check for **true**
///
/// Several of Rust's control structures will check for a `bool` condition evaluating to **true**.
///
/// * The condition in an [`if`] expression must be of type `bool`.
/// Whenever that condition evaluates to **true**, the `if` expression takes
/// on the value of the first block. If however, the condition evaluates
/// to `false`, the expression takes on value of the `else` block if there is one.
///
/// * [`while`] is another control flow construct expecting a `bool`-typed condition.
/// As long as the condition evaluates to **true**, the `while` loop will continually
/// evaluate its associated block.
///
/// * [`match`] arms can have guard clauses on them.
///
/// [`if`]: keyword.if.html
/// [`while`]: keyword.while.html
/// [`match`]: ../reference/expressions/match-expr.html#match-guards
/// [`false`]: keyword.false.html
/// [`bool`]: primitive.bool.html
/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
mod true_keyword {}
#[doc(keyword = "type")]
@ -1167,12 +1185,33 @@ mod await_keyword {}
#[doc(keyword = "dyn")]
//
/// Name the type of a [trait object].
/// `dyn` is a prefix of a [trait object]'s type.
///
/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
/// The `dyn` keyword is used to highlight that calls to methods on the associated `Trait`
/// are dynamically dispatched. To use the trait this way, it must be 'object safe'.
///
/// Unlike generic parameters or `impl Trait`, the compiler does not know the concrete type that
/// is being passed. That is, the type has been [erased].
/// As such, a `dyn Trait` reference contains _two_ pointers.
/// One pointer goes to the data (e.g., an instance of a struct).
/// Another pointer goes to a map of method call names to function pointers
/// (known as a virtual method table or vtable).
///
/// At run-time, when a method needs to be called on the `dyn Trait`, the vtable is consulted to get
/// the function pointer and then that function pointer is called.
///
/// ## Trade-offs
///
/// The above indirection is the additional runtime cost of calling a function on a `dyn Trait`.
/// Methods called by dynamic dispatch generally cannot be inlined by the compiler.
///
/// However, `dyn Trait` is likely to produce smaller code than `impl Trait` / generic parameters as
/// the method won't be duplicated for each concrete type.
///
/// Read more about `object safety` and [trait object]s.
///
/// [trait object]: ../book/ch17-02-trait-objects.html
/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
/// [erased]: https://en.wikipedia.org/wiki/Type_erasure
mod dyn_keyword {}
#[doc(keyword = "union")]