Merge branch 'master' into transparent-enum

.github/workflows/main.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Install mdbook
       run: |
         mkdir bin
-        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.3.4/mdbook-v0.3.4-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.3.5/mdbook-v0.3.5-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
         echo "##[add-path]$(pwd)/bin"
     - name: Report versions
       run: |
@@ -29,4 +29,7 @@ jobs:
     - name: Check for unstable features
       run: (cd stable-check && cargo run -- ../src)
     - name: Check for broken links
-      run: tests/linkcheck.sh
+      run: |
+        curl -sSLo linkcheck.sh \
+          https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
+        sh linkcheck.sh --all reference

CONTRIBUTING.md

@@ -14,6 +14,11 @@ for the Reference. As such, we have the warning saying there's work that needs
 to be done. Eventually, we plan to make sure everything is well documented
 enough that we can remove the warning.
 
+It is encouraged for you to read the [introduction] to familiarize yourself
+with the kind of content the reference is expected to contain and the
+conventions it uses. Also, the [style guide] provides more detailed guidelines
+for formatting and content.
+
 ## Critiquing the Reference
 
 This is the easiest way to contribute. Basically, as you read the reference, if
@@ -63,7 +68,9 @@ This should include links to any relevant information, such as the
 stabilization PR, the RFC, the tracking issue, and anything else that would be
 helpful for writing the documentation.
 
+[introduction]: src/introduction.md
 [issue tracker]: https://github.com/rust-lang/reference/issues
 [playpen]: https://play.rust-lang.org/
 [rust-lang/rust]: https://github.com/rust-lang/rust/
+[style guide]: STYLE.md
 [unstable]: https://doc.rust-lang.org/nightly/unstable-book/

STYLE.md

@@ -0,0 +1,80 @@
+# Rust reference style guide
+
+Some conventions and content guidelines are specified in the [introduction].
+This document serves as a guide for editors and reviewers.
+
+## Markdown formatting
+
+* Use ATX-style heading with sentence case.
+* Wrap long lines, preferably at 80-columns.
+* Use reference links, with shortcuts if appropriate. Place the sorted link
+  reference definitions at the bottom of the file, or at the bottom of a
+  section if there is an unusually large number of links that are specific to
+  the section.
+
+    ```
+    Example of shortcut link: [enumerations]
+    Example of reference link with label: [block expression][block]
+
+    [block]: expressions/block-expr.md
+    [enumerations]: types/enum.md
+    ```
+
+* Links should be relative with the `.md` extension. Links to other rust-lang
+  books that are published with the reference or the standard library API
+  should also be relative so that the linkchecker can validate them.
+* See the [Conventions] section for formatting callouts such as notes, edition
+  differences, and warnings.
+* Formatting to avoid:
+    * Avoid trailing spaces.
+    * Avoid double blank lines.
+
+### Code examples
+
+Code examples should use code blocks with triple backticks. The language
+should always be specified (such as `rust`).
+
+```rust
+println!("Hello!");
+```
+
+See https://highlightjs.org/ for a list of supported languages.
+
+Rust examples are tested via rustdoc, and should include the appropriate
+annotations when tests are expected to fail:
+
+* `edition2018` — If it is edition-specific.
+* `no_run` — The example should compile successfully, but should not be
+  executed.
+* `should_panic` — The example should compile and run, but produce a panic.
+* `compile_fail` — The example is expected to fail to compile.
+* `ignore` — The example shouldn't be built or tested. This should be avoided
+  if possible. Usually this is only necessary when the testing framework does
+  not support it (such as external crates or modules, or a proc-macro), or it
+  contains psuedo-code which is not valid Rust. An HTML comment such as
+  `<!-- ignore: requires extern crate -->` should be placed before the example
+  to explain why it is ignored.
+
+See the [rustdoc documentation] for more detail.
+
+## Language and grammar
+
+* Use American English spelling.
+* Use Oxford commas.
+* Idioms and styling to avoid:
+    * Avoid slashes for alternatives ("program/binary"), use conjunctions or
+      rewrite it ("program or binary").
+    * Avoid qualifying something as "in Rust", the entire reference is about
+      Rust.
+
+## Content
+
+* Whenever there is a difference between editions, the differences should be
+  called out with an "Edition Differences" block. The main text should stick
+  to what is common between the editions. However, for large differences (such
+  as "async"), the main text may contain edition-specific content as long as
+  it is made clear which editions it applies to.
+
+[conventions]: src/introduction.md#conventions
+[introduction]: src/introduction.md
+[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html

src/attributes.md

@@ -50,7 +50,7 @@ Attributes may be applied to many things in the language:
 * [Generic lifetime or type parameter][generics] accept outer attributes.
 * Expressions accept outer attributes in limited situations, see [Expression
   Attributes] for details.
-* [Function][functions], [closure]] and [function pointer]
+* [Function][functions], [closure] and [function pointer]
   parameters accept outer attributes. This includes attributes on variadic parameters
   denoted with `...` in function pointers and [external blocks][variadic functions].
 
@@ -187,6 +187,8 @@ The following is an index of all built-in attributes.
   - [`should_panic`] — Indicates a test should generate a panic.
 - Derive
   - [`derive`] — Automatic trait implementations.
+  - [`automatically_derived`] — Marker for implementations created by
+    `derive`.
 - Macros
   - [`macro_export`] — Exports a `macro_rules` macro for cross-crate usage.
   - [`macro_use`] — Expands macro visibility, or imports macros from other
@@ -255,6 +257,7 @@ The following is an index of all built-in attributes.
 [_LiteralExpression_]: expressions/literal-expr.md
 [_SimplePath_]: paths.md#simple-paths
 [`allow`]: attributes/diagnostics.md#lint-check-attributes
+[`automatically_derived`]: attributes/derive.md#the-automatically_derived-attribute
 [`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute
 [`cfg`]: conditional-compilation.md#the-cfg-attribute
 [`cold`]: attributes/codegen.md#the-cold-attribute

src/attributes/derive.md

@@ -33,10 +33,19 @@ impl<T: PartialEq> PartialEq for Foo<T> {
 
 You can implement `derive` for your own traits through [procedural macros].
 
+## The `automatically_derived` attribute
+
+The *`automatically_derived` attribute* is automatically added to
+[implementations] created by the `derive` attribute for built-in traits. It
+has no direct effect, but it may be used by tools and diagnostic lints to
+detect these automatically generated implementations.
+
 [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax
 [`Clone`]: ../../std/clone/trait.Clone.html
 [`PartialEq`]: ../../std/cmp/trait.PartialEq.html
 [`impl` item]: ../items/implementations.md
 [items]: ../items.md
 [derive macros]: ../procedural-macros.md#derive-macros
+[implementations]: ../items/implementations.md
+[items]: ../items.md
 [procedural macros]: ../procedural-macros.md#derive-macros

src/behavior-considered-undefined.md

@@ -49,7 +49,7 @@ code.
   * Invalid metadata in a wide reference, `Box<T>`, or raw pointer:
     * `dyn Trait` metadata is invalid if it is not a pointer to a vtable for
       `Trait` that matches the actual dynamic trait the pointer or reference points to.
-    * Slice metadata is invalid if if the length is not a valid `usize`
+    * Slice metadata is invalid if the length is not a valid `usize`
       (i.e., it must not be read from uninitialized memory).
   * Non-UTF-8 byte sequences in a `str`.
   * Invalid values for a type with a custom definition of invalid values.

src/const_eval.md

@@ -31,7 +31,7 @@ to be run.
     are implemented, one cannot use both short circuiting operators (`&&` and `||`) and let
     statements within the same constant.
     * [assignment expressions]
-    * [assignment operator expressions]
+    * [compound assignment expressions]
     * [expression statements]
 * [Field] expressions.
 * Index expressions, [array indexing] or [slice] with a `usize`.
@@ -63,7 +63,7 @@ A _const context_ is one of the following:
 [array indexing]:       expressions/array-expr.md#array-and-slice-indexing-expressions
 [array type length expressions]: types/array.md
 [assignment expressions]: expressions/operator-expr.md#assignment-expressions
-[assignment operator expressions]: expressions/operator-expr.md#compound-assignment-expressions
+[compound assignment expressions]: expressions/operator-expr.md#compound-assignment-expressions
 [block expressions]:    expressions/block-expr.md
 [borrow]:               expressions/operator-expr.md#borrow-operators
 [cast]:                 expressions/operator-expr.md#type-cast-expressions
@@ -73,7 +73,7 @@ A _const context_ is one of the following:
 [constants]:            items/constant-items.md
 [dereference operator]: expressions/operator-expr.md#the-dereference-operator
 [destructors]:          destructors.md
-[enum discriminants]:   items/enumerations.md#custom-discriminant-values-for-field-less-enumerations
+[enum discriminants]:   items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations
 [enum variant]:         expressions/enum-variant-expr.md
 [expression statements]: statements.md#expression-statements
 [expressions]:          expressions.md

src/expressions/array-expr.md

@@ -62,7 +62,7 @@ in a _panicked state_ if it fails.
 
 ```rust,should_panic
 // lint is deny by default.
-#![warn(const_err)]
+#![warn(unconditional_panic)]
 
 ([1, 2, 3, 4])[2];        // Evaluates to 3
 

src/expressions/block-expr.md

@@ -22,15 +22,12 @@ of the block.
 
 Blocks are written as `{`, then any [inner attributes], then [statements],
 then an optional expression, and finally a `}`. Statements are usually required
-to be followed a semicolon, with two exceptions. Item declaration statements do
+to be followed by a semicolon, with two exceptions. Item declaration statements do
 not need to be followed by a semicolon. Expression statements usually require
 a following semicolon except if its outer expression is a flow control
 expression. Furthermore, extra semicolons between statements are allowed, but
 these semicolons do not affect semantics.
 
-> Note: The semicolon following a statement is not a part of the statement
-> itself. They are invalid when using the `stmt` macro matcher.
-
 When evaluating a block expression, each statement, except for item declaration
 statements, is executed sequentially. Then the final expression is executed,
 if given.

src/expressions/loop-expr.md

@@ -45,7 +45,7 @@ have type compatible with the value of the `break` expression(s).
 
 > **<sup>Syntax</sup>**\
 > _PredicateLoopExpression_ :\
-> &nbsp;&nbsp; `while` [_Expression_]<sub>except struct expression</sub> [_BlockExpression_]
+> &nbsp;&nbsp; `while` [_Expression_]<sub>_except struct expression_</sub> [_BlockExpression_]
 
 A `while` loop begins by evaluating the boolean loop conditional expression. If
 the loop conditional expression evaluates to `true`, the loop body block
@@ -67,7 +67,7 @@ while i < 10 {
 
 > **<sup>Syntax</sup>**\
 > [_PredicatePatternLoopExpression_] :\
-> &nbsp;&nbsp; `while` `let` [_MatchArmPatterns_] `=` [_Expression_]<sub>except struct expression</sub>
+> &nbsp;&nbsp; `while` `let` [_MatchArmPatterns_] `=` [_Expression_]<sub>_except struct or lazy boolean operator expression_</sub>
 >              [_BlockExpression_]
 
 A `while let` loop is semantically similar to a `while` loop but in place of a
@@ -123,11 +123,13 @@ while let Some(v @ 1) | Some(v @ 2) = vals.pop() {
 }
 ```
 
+As is the case in [`if let` expressions], the scrutinee cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_].
+
 ## Iterator loops
 
 > **<sup>Syntax</sup>**\
 > _IteratorLoopExpression_ :\
-> &nbsp;&nbsp; `for` [_Pattern_] `in` [_Expression_]<sub>except struct expression</sub>
+> &nbsp;&nbsp; `for` [_Pattern_] `in` [_Expression_]<sub>_except struct expression_</sub>
 >              [_BlockExpression_]
 
 A `for` expression is a syntactic construct for looping over elements provided
@@ -294,3 +296,5 @@ expression `()`.
 [`match` expression]: match-expr.md
 [scrutinee]: ../glossary.md#scrutinee
 [temporary values]: ../expressions.md#temporary-lifetimes
+[_LazyBooleanOperatorExpression_]: operator-expr.md#lazy-boolean-operators
+[`if let` expressions]: if-expr.md#if-let-expressions

src/expressions/match-expr.md

@@ -9,10 +9,10 @@
 >
 > _MatchArms_ :\
 >    ( _MatchArm_ `=>`
->                             ( [_BlockExpression_] `,`<sup>?</sup>
->                             | [_Expression_] `,` )
+>                             ( [_ExpressionWithoutBlock_][_Expression_] `,`
+>                             | [_ExpressionWithBlock_][_Expression_] `,`<sup>?</sup> )
 >                           )<sup>\*</sup>\
-> &nbsp;&nbsp; _MatchArm_ `=>` ( [_BlockExpression_] | [_Expression_] ) `,`<sup>?</sup>
+> &nbsp;&nbsp; _MatchArm_ `=>` [_Expression_] `,`<sup>?</sup>
 >
 > _MatchArm_ :\
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> _MatchArmPatterns_ _MatchArmGuard_<sup>?</sup>
@@ -146,7 +146,6 @@ expression in the same expression contexts as [attributes on block
 expressions].
 
 [_Expression_]: ../expressions.md
-[_BlockExpression_]: block-expr.md#block-expressions
 [place expression]: ../expressions.md#place-expressions-and-value-expressions
 [value expression]: ../expressions.md#place-expressions-and-value-expressions
 [_InnerAttribute_]: ../attributes.md

src/interior-mutability.md

@@ -1,6 +1,6 @@
 # Interior Mutability
 
-Sometimes a type needs be mutated while having multiple aliases. In Rust this
+Sometimes a type needs to be mutated while having multiple aliases. In Rust this
 is achieved using a pattern called _interior mutability_. A type has interior
 mutability if its internal state can be changed through a [shared reference] to
 it. This goes against the usual [requirement][ub] that the value pointed to by a

src/items/associated-items.md

@@ -98,24 +98,28 @@ Associated functions whose first parameter is named `self` are called *methods*
 and may be invoked using the [method call operator], for example, `x.foo()`, as
 well as the usual function call notation.
 
-If the type of the `self` parameter is specified, it is limited to one of the
-following types:
+If the type of the `self` parameter is specified, it is limited to types resolving
+to one generated by the following grammar (where `'lt` denotes some arbitrary
+lifetime):
 
-- `Self`
-- `&Self`
-- `&mut Self`
-- [`Box<Self>`]
-- [`Rc<Self>`]
-- [`Arc<Self>`]
-- [`Pin<P>`] where `P` is one of the above types except `Self`.
+```text
+P = &'lt S | &'lt mut S | Box<S> | Rc<S> | Arc<S> | Pin<P>
+S = Self | P
+```
 
-The `Self` term can be replaced with the type being implemented.
+The `Self` terminal in this grammar denotes a type resolving to the implementing type.
+This can also include the contextual type alias `Self`, other type aliases,
+or associated type projections resolving to the implementing type.
 
 ```rust
 # use std::rc::Rc;
 # use std::sync::Arc;
 # use std::pin::Pin;
+// Examples of methods implemented on struct `Example`.
 struct Example;
+type Alias = Example;
+trait Trait { type Output; }
+impl Trait for Example { type Output = Example; }
 impl Example {
     fn by_value(self: Self) {}
     fn by_ref(self: &Self) {}
@@ -126,6 +130,8 @@ impl Example {
     fn by_pin(self: Pin<&Self>) {}
     fn explicit_type(self: Arc<Example>) {}
     fn with_lifetime<'a>(self: &'a Self) {}
+    fn nested<'a>(self: &mut &'a Arc<Rc<Box<Alias>>>) {}
+    fn via_projection(self: <Example as Trait>::Output) {}
 }
 ```
 
@@ -360,4 +366,4 @@ fn main() {
 [function item]: ../types/function-item.md
 [method call operator]: ../expressions/method-call-expr.md
 [path]: ../paths.md
-[regular function parameters]: functions.md#attributes-on-function-parameters 
+[regular function parameters]: functions.md#attributes-on-function-parameters

src/items/enumerations.md

@@ -61,7 +61,7 @@ integer associated to it that is used to determine which variant it holds. An
 opaque reference to this discriminant can be obtained with the
 [`mem::discriminant`] function.
 
-## Custom Discriminant Values for Field-Less Enumerations
+## Custom Discriminant Values for Fieldless Enumerations
 
 If there is no data attached to *any* of the variants of an enumeration,
 then the discriminant can be directly chosen and accessed.