From a52543267554541a95088b79f46a8bd36f487603 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 24 Mar 2019 14:36:33 -0700 Subject: [PATCH 01/37] Document the `automatically_derived` attribute. --- src/attributes.md | 3 +++ src/attributes/derive.md | 9 +++++++++ 2 files changed, 12 insertions(+) diff --git a/src/attributes.md b/src/attributes.md index df2bb460f..230313efd 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -185,6 +185,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 @@ -250,6 +252,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 diff --git a/src/attributes/derive.md b/src/attributes/derive.md index 5859ca93d..b8909ac71 100644 --- a/src/attributes/derive.md +++ b/src/attributes/derive.md @@ -33,10 +33,19 @@ impl PartialEq for Foo { 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 From 851e7f9404b0deaafece4b0bd2fe04700a7ec1a1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 30 Nov 2019 08:16:13 -0800 Subject: [PATCH 02/37] Update for nested receivers. --- src/items/associated-items.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index c1f82f62e..dc6c9faef 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -109,13 +109,15 @@ following types: - [`Arc`] - [`Pin

`] where `P` is one of the above types except `Self`. -The `Self` term can be replaced with the type being implemented. +The `Self` term can be replaced with the type being implemented, including +type aliases for the type, or any nested combination of the above types. ```rust # use std::rc::Rc; # use std::sync::Arc; # use std::pin::Pin; struct Example; +type Alias = Example; impl Example { fn by_value(self: Self) {} fn by_ref(self: &Self) {} @@ -126,6 +128,7 @@ impl Example { fn by_pin(self: Pin<&Self>) {} fn explicit_type(self: Arc) {} fn with_lifetime<'a>(self: &'a Self) {} + fn nested<'a>(self: &mut &'a Arc>>) {} } ``` @@ -360,4 +363,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 From b3d68ee51c1be4d9b865f0211692b5f9714d66ce Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 4 Dec 2019 11:22:25 -0800 Subject: [PATCH 03/37] Add elaboration of object-safe receivers. --- src/items/traits.md | 97 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/src/items/traits.md b/src/items/traits.md index 5427dbe65..b2132a7e8 100644 --- a/src/items/traits.md +++ b/src/items/traits.md @@ -95,6 +95,99 @@ Object safe traits can be the base trait of a [trait object]. A trait is * It must not have any associated constants. * All supertraits must also be object safe. +When there isn't a `Self: Sized` bound on a method, the type of a method +receiver must be one of the following types: + +* `&Self` +* `&mut Self` +* [`Box`] +* [`Rc`] +* [`Arc`] +* [`Pin

`] where `P` is one of the types above + +```rust +# use std::rc::Rc; +# use std::sync::Arc; +# use std::pin::Pin; +// Examples of object safe methods. +trait TraitMethods { + fn by_ref(self: &Self) {} + fn by_ref_mut(self: &mut Self) {} + fn by_box(self: Box) {} + fn by_rc(self: Rc) {} + fn by_arc(self: Arc) {} + fn by_pin(self: Pin<&Self>) {} + fn with_lifetime<'a>(self: &'a Self) {} + fn nested_pin(self: Pin>) {} +} +# struct S; +# impl TraitMethods for S {} +# let t: Box = Box::new(S); +``` + +```rust,compile_fail +// These are object-safe, but cannot be dispatched on a trait object. +trait NonDispatchable { + // Non-methods cannot be dispatched. + fn foo() where Self: Sized {} + // Self type isn't known until runtime. + fn returns(&self) -> Self where Self: Sized; + // `other` may be a different concrete type of the receiver. + fn param(&self, other: Self) where Self: Sized {} + // Generics are not compatible with vtables. + // Alternate solution is to use a trait object instead. + fn typed(&self, x: T) where Self: Sized {} +} + +struct S; +impl NonDispatchable for S { + fn returns(&self) -> Self where Self: Sized { S } +} +let obj: Box = Box::new(S); +obj.returns(); // ERROR: cannot call with Self return +obj.param(S); // ERROR: cannot call with Self parameter +obj.typed(1); // ERROR: cannot call with generic type +``` + +```rust,compile_fail +# use std::rc::Rc; +// Examples of non-object safe traits. +trait NotObjectSafe { + const CONST: i32 = 1; // ERROR: cannot have associated const + + fn foo() {} // ERROR: associated function without Sized + fn returns(&self) -> Self; // ERROR: Self in return type + fn typed(&self, x: T) {} // ERROR: has generic type parameters + fn nested(self: Rc>) {} // ERROR: nested receiver not yet supported +} + +struct S; +impl NotObjectSafe for S { + fn returns(&self) -> Self { S } +} +let obj: Box = Box::new(S); // ERROR +``` + +```rust,compile_fail +// Self: Sized traits are not object-safe. +trait TraitWithSize where Self: Sized {} + +struct S; +impl TraitWithSize for S {} +let obj: Box = Box::new(S); // ERROR +``` + +```rust,compile_fail +// Not object safe if `Self` is a type parameter. +trait Super {} +trait WithSelf: Super where Self: Sized {} + +struct S; +impl Super for S {} +impl WithSelf for S {} +let obj: Box = Box::new(S); // ERROR: cannot use `Self` type parameter +``` + ## Supertraits **Supertraits** are traits that are required to be implemented for a type to @@ -268,3 +361,7 @@ fn main() { [trait implementation]: implementations.md#trait-implementations [`Send`]: ../special-types-and-traits.md#send [`Sync`]: ../special-types-and-traits.md#sync +[`Arc`]: ../special-types-and-traits.md#arct +[`Box`]: ../special-types-and-traits.md#boxt +[`Pin

`]: ../special-types-and-traits.md#pinp +[`Rc`]: ../special-types-and-traits.md#rct From f183df7e64fac5e1f4b66639e1588502919303a2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 5 Feb 2020 18:32:16 -0800 Subject: [PATCH 04/37] Update from review. --- src/items/associated-items.md | 25 ++++++++++++++----------- src/items/traits.md | 5 ++--- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index dc6c9faef..eba9507c7 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -98,26 +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 semantic +types generated by the following grammar (where `'lt` denotes some arbitrary +lifetime): -- `Self` -- `&Self` -- `&mut Self` -- [`Box`] -- [`Rc`] -- [`Arc`] -- [`Pin

`] where `P` is one of the above types except `Self`. +```text +P = &'lt S | &'lt mut S | Box | Rc | Arc | Pin

+S = Self | P +``` -The `Self` term can be replaced with the type being implemented, including -type aliases for the type, or any nested combination of the above types. +The `Self` terminal in this grammar is the semantic `Self` type and can be +replaced with the type being implemented, including type aliases or associated +type projections for the 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) {} @@ -129,6 +131,7 @@ impl Example { fn explicit_type(self: Arc) {} fn with_lifetime<'a>(self: &'a Self) {} fn nested<'a>(self: &mut &'a Arc>>) {} + fn via_projection(self: ::Output) {} } ``` diff --git a/src/items/traits.md b/src/items/traits.md index b2132a7e8..1a65c9239 100644 --- a/src/items/traits.md +++ b/src/items/traits.md @@ -126,7 +126,7 @@ trait TraitMethods { ``` ```rust,compile_fail -// These are object-safe, but cannot be dispatched on a trait object. +// This trait is object-safe, but these methods cannot be dispatched on a trait object. trait NonDispatchable { // Non-methods cannot be dispatched. fn foo() where Self: Sized {} @@ -135,7 +135,6 @@ trait NonDispatchable { // `other` may be a different concrete type of the receiver. fn param(&self, other: Self) where Self: Sized {} // Generics are not compatible with vtables. - // Alternate solution is to use a trait object instead. fn typed(&self, x: T) where Self: Sized {} } @@ -178,7 +177,7 @@ let obj: Box = Box::new(S); // ERROR ``` ```rust,compile_fail -// Not object safe if `Self` is a type parameter. +// Not object safe if `Self` is a type argument. trait Super {} trait WithSelf: Super where Self: Sized {} From 91486df597a9e8060f9c67587359e9f168dea7ef Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 5 Feb 2020 19:29:40 -0800 Subject: [PATCH 05/37] Fix unstable check. --- src/types/never.md | 4 ++-- stable-check/Cargo.lock | 4 +++- stable-check/src/main.rs | 7 ++----- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/types/never.md b/src/types/never.md index 80105b1cd..e32674272 100644 --- a/src/types/never.md +++ b/src/types/never.md @@ -7,8 +7,8 @@ The never type `!` is a type with no values, representing the result of computations that never complete. Expressions of type `!` can be coerced into any other type. -```rust,should_panic -#![feature(never_type)] + +```rust,ignore let x: ! = panic!(); // Can be coerced into any type. let y: u32 = x; diff --git a/stable-check/Cargo.lock b/stable-check/Cargo.lock index 9a3b307c9..982040de4 100644 --- a/stable-check/Cargo.lock +++ b/stable-check/Cargo.lock @@ -1,4 +1,6 @@ -[root] +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +[[package]] name = "stable-check" version = "0.1.0" diff --git a/stable-check/src/main.rs b/stable-check/src/main.rs index c0b1acc83..fc56ff7bb 100644 --- a/stable-check/src/main.rs +++ b/stable-check/src/main.rs @@ -26,7 +26,7 @@ fn check_directory(dir: &Path) -> Result<(), Box> { let path = entry.path(); if path.is_dir() { - continue; + return check_directory(&path); } let mut file = File::open(&path)?; @@ -34,10 +34,7 @@ fn check_directory(dir: &Path) -> Result<(), Box> { file.read_to_string(&mut contents)?; if contents.contains("#![feature") { - // `attributes.md` contains this and it is legitimate. - if !contents.contains("#![feature(feature1, feature2, feature3)]") { - return Err(From::from(format!("Feature flag found in {:?}", path))); - } + return Err(From::from(format!("Feature flag found in {:?}", path))); } } From 43f54a0763b9c6183daedbd3e5bc7ceacc1f6734 Mon Sep 17 00:00:00 2001 From: king6cong Date: Thu, 6 Feb 2020 16:05:06 +0800 Subject: [PATCH 06/37] add MacroRepOp usage for ? --- src/tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tokens.md b/src/tokens.md index e4338f06f..3fda6cab7 100644 --- a/src/tokens.md +++ b/src/tokens.md @@ -579,7 +579,7 @@ usages and meanings are defined in the linked pages. | `=>` | FatArrow | [Match arms][match], [Macros] | `#` | Pound | [Attributes] | `$` | Dollar | [Macros] -| `?` | Question | [Question mark operator][question], [Questionably sized][sized] +| `?` | Question | [Question mark operator][question], [Questionably sized][sized], [Macro Kleene Matcher][macros] ## Delimiters From 4334f6317c2c63bba0165abe572c309382da2d39 Mon Sep 17 00:00:00 2001 From: king6cong Date: Thu, 6 Feb 2020 16:28:16 +0800 Subject: [PATCH 07/37] reorganize docs on references --- src/types/pointer.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/types/pointer.md b/src/types/pointer.md index 8ed3fa8b9..de97815d2 100644 --- a/src/types/pointer.md +++ b/src/types/pointer.md @@ -3,12 +3,14 @@ All pointers in Rust are explicit first-class values. They can be moved or copied, stored into data structs, and returned from functions. -## Shared references (`&`) +## References (`&` and `&mut`) > **Syntax**\ > _ReferenceType_ :\ >    `&` [_Lifetime_]? `mut`? [_TypeNoBounds_] +### Shared references (`&`) + These point to memory _owned by some other value_. When a shared reference to a value is created it prevents direct mutation of the value. [Interior mutability] provides an exception for this in certain circumstances. As the @@ -19,7 +21,7 @@ only copying the pointer itself, that is, pointers are `Copy`. Releasing a reference has no effect on the value it points to, but referencing of a [temporary value] will keep it alive during the scope of the reference itself. -## Mutable references (`&mut`) +### Mutable references (`&mut`) These also point to memory owned by some other value. A mutable reference type is written `&mut type` or `&'a mut type`. A mutable reference (that hasn't been From 30f6d941c8d445a395a2ac61ec0d7c580d0199a2 Mon Sep 17 00:00:00 2001 From: king6cong Date: Sun, 9 Feb 2020 18:38:12 +0800 Subject: [PATCH 08/37] fix `TypeParamBounds` link on trait objects --- src/types/trait-object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/trait-object.md b/src/types/trait-object.md index d514e4a2d..7e37e41cc 100644 --- a/src/types/trait-object.md +++ b/src/types/trait-object.md @@ -97,7 +97,7 @@ need to be expressed as part of the trait object. This lifetime is written as inferred with a sensible choice. [_TraitBound_]: ../trait-bounds.md -[_TypeParamBounds_]: ../types.md#type-expressions +[_TypeParamBounds_]: ../trait-bounds.md [auto traits]: ../special-types-and-traits.md#auto-traits [defaults]: ../lifetime-elision.md#default-trait-object-lifetimes [dynamically sized types]: ../dynamically-sized-types.md From a4cdf6d138a4b369df2ed8f0de61008edf76b56b Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Mon, 10 Feb 2020 02:37:42 +0100 Subject: [PATCH 09/37] clarify note re. leading `::` in 2018 --- src/paths.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/paths.md b/src/paths.md index af739d708..cdf8cc41a 100644 --- a/src/paths.md +++ b/src/paths.md @@ -175,7 +175,8 @@ mod a { } mod b { pub fn foo() { - ::a::foo(); // call a's foo function + ::a::foo(); // call `a`'s foo function + // In Rust 2018, `::a` would be interpreted as the crate `a`. } } # fn main() {} From 695cc003671f5a4156e67b34743dca6064e2cb6c Mon Sep 17 00:00:00 2001 From: king6cong Date: Mon, 10 Feb 2020 12:43:57 +0800 Subject: [PATCH 10/37] typo fix: add missing `by` --- src/expressions/block-expr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index 33cb42109..c35c3d678 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -22,7 +22,7 @@ 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 From 403738f99b69a6a0186c9151ef1dc846e7e61e9f Mon Sep 17 00:00:00 2001 From: AlphaHot <58410019+AlphaHot@users.noreply.github.com> Date: Mon, 10 Feb 2020 13:22:03 +0500 Subject: [PATCH 11/37] Update macro-ambiguity.md --- src/macro-ambiguity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/macro-ambiguity.md b/src/macro-ambiguity.md index f1dbb4285..531fbef0b 100644 --- a/src/macro-ambiguity.md +++ b/src/macro-ambiguity.md @@ -373,5 +373,5 @@ why particular matchers are legal and others are not. * `($($e:expr)*)` : illegal, because expr NTs are not in FOLLOW(expr NT). [Macros by Example]: macros-by-example.md -[RFC 550]: https://github.com/rust-lang/rfcs/blob/master/text/0550-macro-future-proofing.html +[RFC 550]: https://github.com/rust-lang/rfcs/blob/master/text/0550-macro-future-proofing.md [tracking issue]: https://github.com/rust-lang/rust/issues/56575 From 6e2a7b5ede40050f643593d06a906e93e17b6a8f Mon Sep 17 00:00:00 2001 From: king6cong Date: Wed, 12 Feb 2020 11:17:08 +0800 Subject: [PATCH 12/37] add behavior change of relative paths without `self` in 2018 edition --- src/items/use-declarations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 92bd78084..6de253a19 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -103,7 +103,7 @@ mod foo { } use crate::foo::example::iter; // good: foo is at crate root -// use example::iter; // bad: relative paths are not allowed without `self` +// use example::iter; // bad in 2015 edition: relative paths are not allowed without `self`; good in 2018 edition use self::baz::foobaz; // good: self refers to module 'foo' use crate::foo::bar::foobar; // good: foo is at crate root From c8d3b6c2da28876d75b71800f8233f8cff72ec25 Mon Sep 17 00:00:00 2001 From: king6cong Date: Wed, 12 Feb 2020 16:56:22 +0800 Subject: [PATCH 13/37] assignment operator expressions -> compound assignment expressions --- src/const_eval.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/const_eval.md b/src/const_eval.md index cec0145a3..809bc34a2 100644 --- a/src/const_eval.md +++ b/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 From 136bd7da8b9c509c17c9619813b57dd1a47a8e25 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Fri, 14 Feb 2020 13:48:48 +0100 Subject: [PATCH 14/37] semantic type -> resolved type --- src/items/associated-items.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/items/associated-items.md b/src/items/associated-items.md index eba9507c7..5434c0495 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -98,8 +98,8 @@ 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 semantic -types generated by the following grammar (where `'lt` denotes some arbitrary +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): ```text @@ -107,9 +107,9 @@ P = &'lt S | &'lt mut S | Box | Rc | Arc | Pin

S = Self | P ``` -The `Self` terminal in this grammar is the semantic `Self` type and can be -replaced with the type being implemented, including type aliases or associated -type projections for the type. +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; From 8c0d76bc42a4d773b5500565a5020f8c01031888 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 21 Feb 2020 09:30:42 -0800 Subject: [PATCH 15/37] Update for change in const lint name. --- src/expressions/array-expr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/expressions/array-expr.md b/src/expressions/array-expr.md index f31fbb874..4d4f567e1 100644 --- a/src/expressions/array-expr.md +++ b/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 From 5b8fed8fd8b24a67e14041aa6744c660bf34bee9 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 20 Feb 2020 17:39:30 -0800 Subject: [PATCH 16/37] Use common script for link checking. --- .github/workflows/main.yml | 7 +++++-- tests/linkcheck.sh | 28 ---------------------------- 2 files changed, 5 insertions(+), 30 deletions(-) delete mode 100755 tests/linkcheck.sh diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index dca743a23..086b907ae 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/tests/linkcheck.sh b/tests/linkcheck.sh deleted file mode 100755 index 59cab4a5d..000000000 --- a/tests/linkcheck.sh +++ /dev/null @@ -1,28 +0,0 @@ -#!/bin/sh - -set -e - -if [ ! -f book.toml ] -then - echo "Run command in root directory with book.toml" - exit 1 -fi - -rm -rf tests/linkcheck tests/linkchecker - -mkdir tests/linkchecker -curl -o tests/linkchecker/Cargo.toml \ - https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/Cargo.toml -curl -o tests/linkchecker/main.rs \ - https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/main.rs - -mdbook build - -cp -R $(rustc --print sysroot)/share/doc/rust/html tests/linkcheck -rm -rf tests/linkcheck/reference -cp -R book tests/linkcheck/reference - -cargo run --manifest-path=tests/linkchecker/Cargo.toml -- tests/linkcheck/reference - -rm -rf tests/linkcheck tests/linkchecker -echo "Linkcheck completed successfully!" From 54264237dfe4389352e76b1ebaf20af36fb30bcb Mon Sep 17 00:00:00 2001 From: Kinsey Favre Date: Sat, 22 Feb 2020 12:32:09 -0600 Subject: [PATCH 17/37] Fix incorrect pseudocode for #[repr(C)] struct alignment --- src/type-layout.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/type-layout.md b/src/type-layout.md index f6c9ca77e..dd3d58d3f 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -205,14 +205,18 @@ for field in struct.fields_in_declaration_order() { // Increase the current offset so that it's a multiple of the alignment // of this field. For the first field, this will always be zero. // The skipped bytes are called padding bytes. - current_offset += field.alignment % current_offset; + // + // padding_needed_for() is equivalent to + // std::alloc::Layout::padding_needed_for(), but takes an integer rather + // than a Layout as the first argument. + current_offset += padding_needed_for(current_offset, field.alignment); struct[field].offset = current_offset; current_offset += field.size; } -struct.size = current_offset + current_offset % struct.alignment; +struct.size = current_offset + padding_needed_for(current_offset, struct.alignment); ``` > Note: This algorithm can produce zero-sized structs. This differs from From 0e9ed9bc24ada4ddf38b43809e796995d4eabf1c Mon Sep 17 00:00:00 2001 From: vallentin Date: Sat, 22 Feb 2020 22:27:17 +0100 Subject: [PATCH 18/37] Removed repeated word --- src/behavior-considered-undefined.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/behavior-considered-undefined.md b/src/behavior-considered-undefined.md index 960fd3773..f3a27ad63 100644 --- a/src/behavior-considered-undefined.md +++ b/src/behavior-considered-undefined.md @@ -49,7 +49,7 @@ code. * Invalid metadata in a wide reference, `Box`, 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. From 2264855271fae0a915a0fa769e57f5a5d09ff5ef Mon Sep 17 00:00:00 2001 From: varkor Date: Sun, 23 Feb 2020 01:34:25 +0000 Subject: [PATCH 19/37] Replace "Field-Less" with "Fieldless" "-less" is not a suffix that is generally hyphenated, and "field-less" looks odd compared to "fieldless". There's precedent for this choice in https://rust-lang.github.io/unsafe-code-guidelines/layout/enums.html. --- src/const_eval.md | 2 +- src/items/enumerations.md | 2 +- src/type-layout.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/const_eval.md b/src/const_eval.md index 809bc34a2..5d6c367e6 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -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 diff --git a/src/items/enumerations.md b/src/items/enumerations.md index 25dfecb65..7e4795508 100644 --- a/src/items/enumerations.md +++ b/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. diff --git a/src/type-layout.md b/src/type-layout.md index f6c9ca77e..e2773081a 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -354,7 +354,7 @@ used with any other representation. [`size_of`]: ../std/mem/fn.size_of.html [`Sized`]: ../std/marker/trait.Sized.html [dynamically sized types]: dynamically-sized-types.md -[C-like enumerations]: items/enumerations.md#custom-discriminant-values-for-field-less-enumerations +[C-like enumerations]: items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations [zero-variant enumerations]: items/enumerations.md#zero-variant-enums [undefined behavior]: behavior-considered-undefined.md [27060]: https://github.com/rust-lang/rust/issues/27060 From 1c7cd729a71aa80418b18f05ce5ef19894154fe0 Mon Sep 17 00:00:00 2001 From: Bram Geron Date: Mon, 24 Feb 2020 00:29:49 +0100 Subject: [PATCH 20/37] Nit: remove erroneous duplication --- src/tokens.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/tokens.md b/src/tokens.md index 3fda6cab7..ed099ce9d 100644 --- a/src/tokens.md +++ b/src/tokens.md @@ -154,8 +154,8 @@ Line-breaks are allowed in string literals. A line-break is either a newline (`U+000A`) or a pair of carriage return and newline (`U+000D`, `U+000A`). Both byte sequences are normally translated to `U+000A`, but as a special exception, when an unescaped `U+005C` character (`\`) occurs immediately before the -line-break, the `U+005C` character, the line-break, and all whitespace at the -beginning of the next line are ignored. Thus `a` and `b` are equal: +line-break, the `U+005C` character, and all whitespace at the beginning of the +next line are ignored. Thus `a` and `b` are equal: ```rust let a = "foobar"; From bc5c540419ea98cef349a7869d0d32ef633ebce2 Mon Sep 17 00:00:00 2001 From: Kinsey Favre Date: Mon, 24 Feb 2020 08:57:34 -0600 Subject: [PATCH 21/37] Explicitly describe padding algorithm in pseudocode --- src/type-layout.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/type-layout.md b/src/type-layout.md index dd3d58d3f..7979905f0 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -197,6 +197,17 @@ Here is this algorithm described in pseudocode. ```rust,ignore +fn padding_needed_for(offset: usize, alignment: usize) -> usize { + let misalignment = offset % alignment; + if misalignment > 0 { + // round up to next multiple of `alignment` + alignment - misalignment + } else { + // already a multiple of `alignment` + 0 + } +} + struct.alignment = struct.fields().map(|field| field.alignment).max(); let current_offset = 0; @@ -205,10 +216,6 @@ for field in struct.fields_in_declaration_order() { // Increase the current offset so that it's a multiple of the alignment // of this field. For the first field, this will always be zero. // The skipped bytes are called padding bytes. - // - // padding_needed_for() is equivalent to - // std::alloc::Layout::padding_needed_for(), but takes an integer rather - // than a Layout as the first argument. current_offset += padding_needed_for(current_offset, field.alignment); struct[field].offset = current_offset; From 13e415a71c7e725a4ef32b397d338c83d7f5a9c8 Mon Sep 17 00:00:00 2001 From: Kinsey Favre Date: Mon, 24 Feb 2020 09:58:27 -0600 Subject: [PATCH 22/37] Add warning for #[repr(C)] struct alignment pseudocode --- src/type-layout.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/type-layout.md b/src/type-layout.md index 7979905f0..c572f1efe 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -226,6 +226,14 @@ for field in struct.fields_in_declaration_order() { struct.size = current_offset + padding_needed_for(current_offset, struct.alignment); ``` +

+ +Warning: This pseudocode uses a naive algorithm that ignores overflow issues for +the sake of clarity. To perform memory layout computations in actual code, use +[`Layout`]. + +
+ > Note: This algorithm can produce zero-sized structs. This differs from > C where structs without data still have a size of one byte. @@ -374,3 +382,4 @@ used with any other representation. [`C`]: #the-c-representation [primitive representations]: #primitive-representations [`transparent`]: #the-transparent-representation +[`Layout`]: ../std/alloc/struct.Layout.html From 5d5b233a13100bbde50f7b66652956c86bbb82df Mon Sep 17 00:00:00 2001 From: Kinsey Favre Date: Mon, 24 Feb 2020 10:11:49 -0600 Subject: [PATCH 23/37] Add doc comment for padding_needed_for fn in pseudocode --- src/type-layout.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/type-layout.md b/src/type-layout.md index c572f1efe..967c9ed1e 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -197,6 +197,8 @@ Here is this algorithm described in pseudocode. ```rust,ignore +/// Returns the amount of padding needed after `offset` to ensure that the +/// following address will be aligned to `alignment`. fn padding_needed_for(offset: usize, alignment: usize) -> usize { let misalignment = offset % alignment; if misalignment > 0 { From 1a0273b6e77345ce149add5e19e8fc346687935c Mon Sep 17 00:00:00 2001 From: Timur Date: Mon, 2 Mar 2020 02:48:59 +0300 Subject: [PATCH 24/37] Syntax error fix --- src/attributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index dfffe5ca0..da94428ea 100644 --- a/src/attributes.md +++ b/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]. From e7dd3618d78928322f53a20e2947e428b12eda2b Mon Sep 17 00:00:00 2001 From: Nurbol Alpysbayev Date: Tue, 3 Mar 2020 17:12:15 +0600 Subject: [PATCH 25/37] A typo? --- src/interior-mutability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/interior-mutability.md b/src/interior-mutability.md index 1133bc797..e786d5649 100644 --- a/src/interior-mutability.md +++ b/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 From 71b055152f70d6e21a75b0ddc7f5d383accdea38 Mon Sep 17 00:00:00 2001 From: Frank Steffahn Date: Wed, 4 Mar 2020 01:32:21 +0100 Subject: [PATCH 26/37] Add information about || and && to Grammar describing `while let`. Also fix italics to be consistent with other pages. --- src/expressions/loop-expr.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/src/expressions/loop-expr.md b/src/expressions/loop-expr.md index e37235a30..d1cbc636c 100644 --- a/src/expressions/loop-expr.md +++ b/src/expressions/loop-expr.md @@ -45,7 +45,7 @@ have type compatible with the value of the `break` expression(s). > **Syntax**\ > _PredicateLoopExpression_ :\ ->    `while` [_Expression_]except struct expression [_BlockExpression_] +>    `while` [_Expression_]_except struct expression_ [_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 { > **Syntax**\ > [_PredicatePatternLoopExpression_] :\ ->    `while` `let` [_MatchArmPatterns_] `=` [_Expression_]except struct expression +>    `while` `let` [_MatchArmPatterns_] `=` [_Expression_]_except struct or lazy boolean operator expression_ > [_BlockExpression_] A `while let` loop is semantically similar to a `while` loop but in place of a @@ -123,11 +123,32 @@ while let Some(v @ 1) | Some(v @ 2) = vals.pop() { } ``` +The expression cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_]. +Use of a lazy boolean operator is ambiguous with a planned feature change +of the language (the implementation of if-let chains - see [eRFC 2947][_eRFCIfLetChain_]). +When lazy boolean operator expression is desired, this can be achieved +by using parenthesis as below: + + +```rust,ignore +// Before... +while let PAT = EXPR && EXPR { .. } + +// After... +while let PAT = ( EXPR && EXPR ) { .. } + +// Before... +while let PAT = EXPR || EXPR { .. } + +// After... +while let PAT = ( EXPR || EXPR ) { .. } +``` + ## Iterator loops > **Syntax**\ > _IteratorLoopExpression_ :\ ->    `for` [_Pattern_] `in` [_Expression_]except struct expression +>    `for` [_Pattern_] `in` [_Expression_]_except struct expression_ > [_BlockExpression_] A `for` expression is a syntactic construct for looping over elements provided From 1750e2da58eedf4cf4a1a8c79c8df81b0c278c78 Mon Sep 17 00:00:00 2001 From: Frank Steffahn Date: Wed, 4 Mar 2020 05:40:25 +0100 Subject: [PATCH 27/37] Fix grammar for tuple struct patterns. --- src/patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/patterns.md b/src/patterns.md index 8947467b0..b81d8dbdb 100644 --- a/src/patterns.md +++ b/src/patterns.md @@ -556,7 +556,7 @@ A struct pattern is refutable when one of its subpatterns is refutable. > **Syntax**\ > _TupleStructPattern_ :\ ->    [_PathInExpression_] `(` _TupleStructItems_ `)` +>    [_PathInExpression_] `(` _TupleStructItems_? `)` > > _TupleStructItems_ :\ >       [_Pattern_] ( `,` [_Pattern_] )\* `,`?\ From 532060a3f2fcdef49afbe9e2c6f97d0fb61410b7 Mon Sep 17 00:00:00 2001 From: Frank Steffahn Date: Wed, 4 Mar 2020 20:00:56 +0100 Subject: [PATCH 28/37] Remove duplicated explanation about lazy boolean operators in while let, refer to the if let page instead. --- src/expressions/loop-expr.md | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/src/expressions/loop-expr.md b/src/expressions/loop-expr.md index d1cbc636c..3bff9adaf 100644 --- a/src/expressions/loop-expr.md +++ b/src/expressions/loop-expr.md @@ -123,26 +123,7 @@ while let Some(v @ 1) | Some(v @ 2) = vals.pop() { } ``` -The expression cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_]. -Use of a lazy boolean operator is ambiguous with a planned feature change -of the language (the implementation of if-let chains - see [eRFC 2947][_eRFCIfLetChain_]). -When lazy boolean operator expression is desired, this can be achieved -by using parenthesis as below: - - -```rust,ignore -// Before... -while let PAT = EXPR && EXPR { .. } - -// After... -while let PAT = ( EXPR && EXPR ) { .. } - -// Before... -while let PAT = EXPR || EXPR { .. } - -// After... -while let PAT = ( EXPR || EXPR ) { .. } -``` +As is the case in [`if let` expressions], the scrutinee cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_]. ## Iterator loops @@ -315,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 From 6b90080371ff44d0074a465945dfdb0de4b50774 Mon Sep 17 00:00:00 2001 From: Frank Steffahn Date: Wed, 4 Mar 2020 18:34:32 +0100 Subject: [PATCH 29/37] Fix expression and statement grammar. Semicolon or comma in expression statements or match arms, respectively, are optional, but part of the statement / match arm. Also remove a note about proc-macros from the page about BlockExpression. Closes #773 and closes #774. --- src/expressions/block-expr.md | 3 --- src/expressions/match-expr.md | 7 +++---- src/statements.md | 2 +- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index c35c3d678..291634f3c 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -28,9 +28,6 @@ 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. diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index dcbf69fe7..9a0cb8d61 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -9,10 +9,10 @@ > > _MatchArms_ :\ >    ( _MatchArm_ `=>` -> ( [_BlockExpression_] `,`? -> | [_Expression_] `,` ) +> ( [_ExpressionWithoutBlock_][_Expression_] `,` +> | [_ExpressionWithBlock_][_Expression_] `,`? ) > )\*\ ->    _MatchArm_ `=>` ( [_BlockExpression_] | [_Expression_] ) `,`? +>    _MatchArm_ `=>` [_Expression_] `,`? > > _MatchArm_ :\ >    [_OuterAttribute_]\* _MatchArmPatterns_ _MatchArmGuard_? @@ -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 diff --git a/src/statements.md b/src/statements.md index 9b5bd94f1..5d8e0e95d 100644 --- a/src/statements.md +++ b/src/statements.md @@ -69,7 +69,7 @@ from the point of declaration until the end of the enclosing block scope. > **Syntax**\ > _ExpressionStatement_ :\ >       [_ExpressionWithoutBlock_][expression] `;`\ ->    | [_ExpressionWithBlock_][expression] +>    | [_ExpressionWithBlock_][expression] `;`? An *expression statement* is one that evaluates an [expression] and ignores its result. As a rule, an expression statement's purpose is to trigger the effects From c72ec767a30478c4c6599c9186dfb2353c5f1d81 Mon Sep 17 00:00:00 2001 From: Chris Simpkins Date: Thu, 5 Mar 2020 22:39:09 -0500 Subject: [PATCH 30/37] update rustc-guide to rustc-dev-guide --- src/types/inferred.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/inferred.md b/src/types/inferred.md index c754f310b..2cc3125da 100644 --- a/src/types/inferred.md +++ b/src/types/inferred.md @@ -13,6 +13,6 @@ let x: Vec<_> = (0..10).collect(); From 43dc1a42f19026f580e34a095e91804c3d6da186 Mon Sep 17 00:00:00 2001 From: Chris Simpkins Date: Mon, 9 Mar 2020 17:46:25 -0400 Subject: [PATCH 31/37] rust-lang.github.io to rustc-dev-guide.rust-lang.org --- src/types/inferred.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/inferred.md b/src/types/inferred.md index 2cc3125da..c33ebd91c 100644 --- a/src/types/inferred.md +++ b/src/types/inferred.md @@ -13,6 +13,6 @@ let x: Vec<_> = (0..10).collect(); From 01ca752265ef2a1cf4af8174788e8bcefb64e235 Mon Sep 17 00:00:00 2001 From: GeeF Date: Wed, 11 Mar 2020 16:20:02 +0100 Subject: [PATCH 32/37] Fix and clarify section on re-export Section on use-visibility fixed to compile under Rust 2018, since they are not absolute paths by default anymore. --- src/items/use-declarations.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 6de253a19..6db98ab2e 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -60,21 +60,26 @@ default. Also like items, a `use` declaration can be public, if qualified by the `pub` keyword. Such a `use` declaration serves to _re-export_ a name. A public `use` declaration can therefore _redirect_ some public name to a different target definition: even a definition with a private canonical path, -inside a different module. If a sequence of such redirections form a cycle or -cannot be resolved unambiguously, they represent a compile-time error. +inside a different module. This allows to present an external interface to a +user of the crate that is different from the internal organization of the code. +If a sequence of such redirections form a cycle or cannot be resolved unambiguously, +they represent a compile-time error. An example of re-exporting: ```rust -# fn main() { } mod quux { - pub use quux::foo::{bar, baz}; - + pub use self::foo::{bar, baz}; pub mod foo { - pub fn bar() { } - pub fn baz() { } + pub fn bar() {} + pub fn baz() {} } } + +fn main() { + quux::bar(); + quux::baz(); +} ``` In this example, the module `quux` re-exports two public names defined in From 702bc78049313d8186ccc8753aad993dd2ae6485 Mon Sep 17 00:00:00 2001 From: GeeF Date: Fri, 13 Mar 2020 10:25:37 +0100 Subject: [PATCH 33/37] remove sentence --- src/items/use-declarations.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 6db98ab2e..89542ce6a 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -60,10 +60,8 @@ default. Also like items, a `use` declaration can be public, if qualified by the `pub` keyword. Such a `use` declaration serves to _re-export_ a name. A public `use` declaration can therefore _redirect_ some public name to a different target definition: even a definition with a private canonical path, -inside a different module. This allows to present an external interface to a -user of the crate that is different from the internal organization of the code. -If a sequence of such redirections form a cycle or cannot be resolved unambiguously, -they represent a compile-time error. +inside a different module. If a sequence of such redirections form a cycle or +cannot be resolved unambiguously, they represent a compile-time error. An example of re-exporting: From 091a595c8f44bab27a31ff43a8a2f93204404e7d Mon Sep 17 00:00:00 2001 From: Donough Liu Date: Fri, 13 Mar 2020 19:27:10 +0800 Subject: [PATCH 34/37] Size fo empty structs in C is zero byte. --- src/type-layout.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/type-layout.md b/src/type-layout.md index 51ba859ef..003a3ce63 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -236,8 +236,9 @@ the sake of clarity. To perform memory layout computations in actual code, use -> Note: This algorithm can produce zero-sized structs. This differs from -> C where structs without data still have a size of one byte. +> Note: This algorithm can produce zero-sized structs. In C, the size of +> structs without data is zero. This is not the same as C++ where structs +> without data still have a size of one byte. #### \#[repr(C)] Unions From 30af09147d38d63aed24a7d707df9aeb5524d5b2 Mon Sep 17 00:00:00 2001 From: Donough Liu Date: Fri, 13 Mar 2020 21:55:21 +0800 Subject: [PATCH 35/37] Further improvement --- src/type-layout.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/type-layout.md b/src/type-layout.md index 003a3ce63..7557d951c 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -236,9 +236,12 @@ the sake of clarity. To perform memory layout computations in actual code, use -> Note: This algorithm can produce zero-sized structs. In C, the size of -> structs without data is zero. This is not the same as C++ where structs -> without data still have a size of one byte. +> Note: This algorithm can produce zero-sized structs. In C, an empty struct +> declaration like `struct Foo { }` is illegal. However, both gcc and clang +> support options to enable such structs, and assign them size zero. C++, in +> contrast, gives empty structs a size of 1, unless they are inherited from or +> they are fields that have the `[[no_unique_address]]` attribute, in which +> case they do not increase the overall size of the struct. #### \#[repr(C)] Unions From d69a6d13c917856aa7da839647dcdbde6d9dde46 Mon Sep 17 00:00:00 2001 From: Bram Geron Date: Mon, 23 Mar 2020 21:17:00 +0100 Subject: [PATCH 36/37] Undo regression, clarify instead (thanks @ehuss!) --- src/tokens.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/tokens.md b/src/tokens.md index ed099ce9d..0b0c29cf8 100644 --- a/src/tokens.md +++ b/src/tokens.md @@ -154,8 +154,8 @@ Line-breaks are allowed in string literals. A line-break is either a newline (`U+000A`) or a pair of carriage return and newline (`U+000D`, `U+000A`). Both byte sequences are normally translated to `U+000A`, but as a special exception, when an unescaped `U+005C` character (`\`) occurs immediately before the -line-break, the `U+005C` character, and all whitespace at the beginning of the -next line are ignored. Thus `a` and `b` are equal: +line-break, then the `U+005C` character, the line-break, and all whitespace at the +beginning of the next line are ignored. Thus `a` and `b` are equal: ```rust let a = "foobar"; From 77a81ee3cb90a7fb5c899af808cafcc84d73cc65 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 4 Apr 2020 10:58:01 -0700 Subject: [PATCH 37/37] Add a basic style guide. --- CONTRIBUTING.md | 7 +++++ STYLE.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 STYLE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75a7e83a8..179730b57 100644 --- a/CONTRIBUTING.md +++ b/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/ diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 000000000..b70eb8808 --- /dev/null +++ b/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 + `` 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