From 047aac5cc60016b7c7f2a92f335b4a82b07ec59c Mon Sep 17 00:00:00 2001 From: iirelu Date: Mon, 3 Sep 2018 16:25:51 +0200 Subject: Flesh out struct keyword docs The whole keyword docs thing is pretty new in Rust's history and needs some work before it's a shining gem. Here's hoping I can provide that. I basically shoved in a bunch of the most important information from the reference and the book, along with leaving links to both at the end. I don't think keyword docs need to have complete detail, just all the broad strokes, so if someone's confused about a usage of a keyword they can look at the std documentation for that keyword. --- src/libstd/keyword_docs.rs | 104 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 96 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index d70cf132b3c..b5593e44f8b 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -59,21 +59,109 @@ mod let_keyword { } #[doc(keyword = "struct")] // -/// The `struct` keyword. +/// The keyword used to define structs. /// -/// The `struct` keyword is used to define a struct type. +/// Structs in Rust come in three flavours: Regular structs, tuple structs, +/// and empty structs. /// -/// Example: +/// ```rust +/// struct Regular { +/// field1: f32, +/// field2: String, +/// pub field3: bool +/// } /// +/// struct Tuple(u32, String); +/// +/// struct Empty; /// ``` -/// struct Foo { -/// field1: u32, -/// field2: String, +/// +/// Regular structs are the most commonly used. Each field defined within them has a name and a +/// type, and once defined can be accessed using `example_struct.field` syntax. The fields of a +/// struct share its mutability, so `foo.bar = 2;` would only be valid if `foo` was mutable. Adding +/// `pub` to a field makes it visible to code in other modules, as well as allowing it to be +/// directly accessed and modified. +/// +/// Tuple structs are similar to regular structs, but its fields have no names. They are used like +/// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax. For accessing +/// individual variables, the same syntax is used as with regular tuples, namely `foo.0`, `foo.1`, +/// etc, starting at zero. +/// +/// Empty structs, or unit-like structs, are most commonly used as markers, for example +/// [`PhantomData`]. Empty structs have a size of zero bytes, but unlike empty enums they can be +/// instantiated, making them similar to the unit type `()`. Unit-like structs are useful when you +/// need to implement a trait on something, but don't need to store any data inside it. +/// +/// # Instantiation +/// +/// Structs can be instantiated in a manner of different ways, each of which can be mixed and +/// matched as needed. The most common way to make a new struct is via a constructor method such as +/// `new()`, but when that isn't available (or you're writing the constructor itself), struct +/// literal syntax is used: +/// +/// ```rust +/// # struct Foo { field1: f32, field2: String, etc: bool } +/// let example = Foo { +/// field1: 42.0, +/// field2: "blah".to_string(), +/// etc: true, +/// }; +/// ``` +/// +/// It's only possible to directly instantiate a struct using struct literal syntax when all of its +/// fields are visible to you. +/// +/// There are a handful of shortcuts provided to make writing constructors more convenient, most +/// common of which is the Field Init shorthand. When there is a variable and a field of the same +/// name, the assignment can be simplified from `field: field` into simply `field`. The following +/// example of a hypothetical constructor demonstrates this: +/// +/// ```rust +/// struct User { +/// name: String, +/// admin: bool, +/// } +/// +/// impl User { +/// pub fn new(name: String) -> Self { +/// Self { +/// name, +/// admin: false, +/// } +/// } /// } /// ``` /// -/// There are different kinds of structs. For more information, take a look at the -/// [Rust Book][book]. +/// Another shortcut for struct instantiation is available when you need to make a new struct that +/// shares most of a previous struct's values called struct update syntax: +/// +/// ```rust +/// # struct Foo { field1: String, field2: () } +/// # let thing = Foo { field1: "".to_string(), field2: () }; +/// let updated_thing = Foo { +/// field1: "a new value".to_string(), +/// ..thing +/// }; +/// ``` /// +/// Tuple structs are instantiated in the same way as tuples themselves, except with the struct's +/// name as a prefix: `Foo(123, false, 0.1)`. +/// +/// Empty structs are instantiated with just their name and nothing else. `let thing = +/// EmptyStruct;` +/// +/// +/// # Style conventions +/// +/// Structs are always written in CamelCase, with few exceptions. While the trailing comma on a +/// struct's list of fields can be omitted, it's usually kept for convenience in adding and +/// removing fields down the line. +/// +/// For more information on structs, take a look at the [Rust Book][book] or the +/// [Reference][reference]. +/// +/// [`PhantomData`]: marker/struct.PhantomData.html /// [book]: https://doc.rust-lang.org/book/second-edition/ch05-01-defining-structs.html +/// [reference]: https://doc.rust-lang.org/reference/items/structs.html + mod struct_keyword { } -- cgit 1.4.1-3-g733a5 From 1142bbdfc4e9ae48045e9b7a2c6b507aa0626e84 Mon Sep 17 00:00:00 2001 From: iirelu Date: Mon, 3 Sep 2018 19:41:01 +0200 Subject: Add docs for `as` keyword It's pretty basic and could do with more details, but it's a good starter until someone else improves it. --- src/libstd/keyword_docs.rs | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index b5593e44f8b..db447c1b363 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -8,6 +8,33 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +#[doc(keyword = "as")] +// +/// The type coercion keyword +/// +/// `as` is most commonly used to turn primitive types into other primitive types, but it has other +/// uses that include turning pointers into addresses, addresses into pointers, and pointers into +/// other pointers. +/// +/// ```rust +/// let thing1: u8 = 89.0 as u8; +/// assert_eq!('B' as u32, 66); +/// assert_eq!(thing1 as char, 'Y'); +/// let thing2: f32 = thing1 as f32 + 10.5; +/// assert_eq!(true as u8 + thing2 as u8, 100); +/// ``` +/// +/// In general, any coercion that can be performed via writing out type hints can also be done +/// using `as`, so instead of writing `let x: u32 = 123`, you can write `let x = 123 as u32` (Note: +/// `let x = 123u32` would be best in that situation). The same is not true in the other direction, +/// however, explicitly using `as` allows a few more coercions that aren't allowed implicitly, such +/// as changing the type of a raw pointer or turning closures into raw pointers. +/// +/// For more information on what `as` is capable of, see the [Reference] +/// +/// [Reference]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions +mod as_keyword { } + #[doc(keyword = "fn")] // /// The `fn` keyword. -- cgit 1.4.1-3-g733a5 From c1bd8a9c615b6ec9124c9525c8d0898c806b62c8 Mon Sep 17 00:00:00 2001 From: iirelu Date: Mon, 3 Sep 2018 20:23:53 +0200 Subject: Add keyword docs on const Turns out writing docs on keywords that are used in multiple different places in entirely different contexts gets a little harder. I put a footnote on `*const` syntax just to make sure you can find it if need be, but it might need more detail. --- src/libstd/keyword_docs.rs | 57 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index db447c1b363..5c3a2b18e1c 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -10,7 +10,7 @@ #[doc(keyword = "as")] // -/// The type coercion keyword +/// The type coercion keyword. /// /// `as` is most commonly used to turn primitive types into other primitive types, but it has other /// uses that include turning pointers into addresses, addresses into pointers, and pointers into @@ -35,6 +35,61 @@ /// [Reference]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions mod as_keyword { } +#[doc(keyword = "const")] +// +/// The keyword for defining constants. +/// +/// Sometimes a certain value is used many times throughout a program, and it can become +/// inconvenient to copy it over and over. What's more, it's not always possible or desirable to +/// make it a variable that gets carried around to each function that needs it. In these cases, the +/// `const` keyword provides a convenient alternative to code duplication. +/// +/// ```rust +/// const THING: u32 = 0xABAD1DEA; +/// +/// let foo = 123 + THING; +/// ``` +/// +/// Constants must be explicitly typed, unlike with `let` you can't ignore its type and let the +/// compiler figure it out. Any constant value can be defined in a const, which in practice happens +/// to be most things that would be reasonable to have a constant. For example, you can't have a +/// File as a const. +/// +/// The only lifetime allowed in a constant is 'static, which is the lifetime that encompasses all +/// others in a Rust program. For example, if you wanted to define a constant string, it would look +/// like this: +/// +/// ```rust +/// const WORDS: &'static str = "hello rust!"; +/// ``` +/// +/// Thanks to static lifetime elision, you usually don't have to explicitly use 'static: +/// +/// ```rust +/// const WORDS: &str = "hello convenience!"; +/// ``` +/// +/// `const` items looks remarkably similar to [`static`] items, which introduces some confusion as +/// to which one should be used at which times. To put it simply, constants are inlined wherever +/// they're used, making using them identical to simply replacing the name of the const with its +/// value. Static variables on the other hand point to a single location in memory, which all +/// accesses share. This means that, unlike with constants, they can't have destructors, but it +/// also means that (via unsafe code) they can be mutable, which is useful for the rare situations +/// in which you can't avoid using global state. +/// +/// Constants, as with statics, should always be in SCREAMING_SNAKE_CASE. +/// +/// The `const` keyword is also used in raw pointers in combination with `mut`, as seen in `*const +/// T` and `*mut T`. More about that can be read at the [pointer] primitive part of the Rust docs. +/// +/// For more detail on `const`, see the [Rust Book] or the [Reference] +/// +/// [`static`]: keyword.static.html +/// [pointer]: primitive.pointer.html +/// [Rust Book]: https://doc.rust-lang.org/stable/book/2018-edition/ch03-01-variables-and-mutability.html#differences-between-variables-and-constants +/// [Reference]: https://doc.rust-lang.org/reference/items/constant-items.html +mod const_keyword { } + #[doc(keyword = "fn")] // /// The `fn` keyword. -- cgit 1.4.1-3-g733a5 From 6cbcfa276185d650ca04fb96ddec15f1b82c5806 Mon Sep 17 00:00:00 2001 From: iirelu Date: Mon, 3 Sep 2018 21:56:30 +0200 Subject: Fix a few small things, re-word others Mostly addressing notes on ambiguous syntax and spurious newlines. --- src/libstd/keyword_docs.rs | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 5c3a2b18e1c..a1f594d5244 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -53,7 +53,7 @@ mod as_keyword { } /// Constants must be explicitly typed, unlike with `let` you can't ignore its type and let the /// compiler figure it out. Any constant value can be defined in a const, which in practice happens /// to be most things that would be reasonable to have a constant. For example, you can't have a -/// File as a const. +/// File as a `const`. /// /// The only lifetime allowed in a constant is 'static, which is the lifetime that encompasses all /// others in a Rust program. For example, if you wanted to define a constant string, it would look @@ -214,8 +214,9 @@ mod let_keyword { } /// } /// ``` /// -/// Another shortcut for struct instantiation is available when you need to make a new struct that -/// shares most of a previous struct's values called struct update syntax: +/// Another shortcut for struct instantiation is available, used when you need to make a new +/// struct that has the same values as most of a previous struct of the same type, called struct +/// update syntax: /// /// ```rust /// # struct Foo { field1: String, field2: () } @@ -229,10 +230,9 @@ mod let_keyword { } /// Tuple structs are instantiated in the same way as tuples themselves, except with the struct's /// name as a prefix: `Foo(123, false, 0.1)`. /// -/// Empty structs are instantiated with just their name and nothing else. `let thing = +/// Empty structs are instantiated with just their name, and don't need anything else. `let thing = /// EmptyStruct;` /// -/// /// # Style conventions /// /// Structs are always written in CamelCase, with few exceptions. While the trailing comma on a @@ -245,5 +245,4 @@ mod let_keyword { } /// [`PhantomData`]: marker/struct.PhantomData.html /// [book]: https://doc.rust-lang.org/book/second-edition/ch05-01-defining-structs.html /// [reference]: https://doc.rust-lang.org/reference/items/structs.html - mod struct_keyword { } -- cgit 1.4.1-3-g733a5 From f8d6261f9bc3ae9d11a34f194d8593556965a537 Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 5 Sep 2018 19:12:20 +0200 Subject: Add docs for `crate` keyword I think it might be used in some other things, but I'm not fluent enough at sifting through the rust compiler's source code to find every use of a specific keyword. This leaves the question of how to document the `extern` keyword, what with how much overlap it has with `crate`, but that's used with ABI stuff so that should be fine. --- src/libstd/keyword_docs.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index a1f594d5244..61b30d94e5a 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -90,6 +90,40 @@ mod as_keyword { } /// [Reference]: https://doc.rust-lang.org/reference/items/constant-items.html mod const_keyword { } +#[doc(keyword = "crate")] +// +/// The `crate` keyword. +/// +/// The primary use of the `crate` keyword is as a part of `extern crate` declarations, which are +/// used to specify a dependency on a crate external to the one it's declared in. Crates are the +/// fundamental compilation unit of Rust code, and can be seen as libraries or projects. More can +/// be read about crates in the [Reference]. +/// +/// ```rust ignore +/// extern crate rand; +/// extern crate my_crate as thing; +/// extern crate std; // implicitly added to the root of every Rust project +/// ``` +/// +/// The `as` keyword can be used to change what the crate is referred to as in your project. If a +/// crate name includes a dash, it is implicitly imported with the dashes replaced by underscores. +/// +/// `crate` is also used as in conjunction with [`pub`] to signify that the item it's attached to +/// is public only to other members of the same crate it's in. +/// +/// ```rust +/// # #[allow(unused_imports)] +/// pub(crate) use std::io::Error as IoError; +/// pub(crate) enum CoolMarkerType { } +/// pub struct PublicThing { +/// pub(crate) semi_secret_thing: bool, +/// } +/// ``` +/// +/// [Reference]: https://doc.rust-lang.org/reference/items/extern-crates.html +/// [`pub`]: keyword.pub.html +mod crate_keyword { } + #[doc(keyword = "fn")] // /// The `fn` keyword. -- cgit 1.4.1-3-g733a5 From f15a1ec45dbc0f24bdc2eef3e4d7d5a16fa4af1a Mon Sep 17 00:00:00 2001 From: iirelu Date: Thu, 6 Sep 2018 20:44:29 +0200 Subject: Add keyword docs on `enum` --- src/libstd/keyword_docs.rs | 55 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 61b30d94e5a..5026ca4d722 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -124,6 +124,61 @@ mod const_keyword { } /// [`pub`]: keyword.pub.html mod crate_keyword { } +#[doc(keyword = "enum")] +// +/// For defining enumerations. +/// +/// Enums in Rust are similar to those of other compiled languages like C, but have important +/// differences that make them considerably more powerful. What Rust calls enums are more commonly +/// known as Algebraic Data Types if you're coming from a functional programming background, but +/// the important part is that data can go with the enum variants. +/// +/// ```rust +/// # struct Coord; +/// enum SimpleEnum { +/// FirstVariant, +/// SecondVariant, +/// ThirdVariant, +/// } +/// +/// enum Location { +/// Unknown, +/// Anonymous, +/// Known(Coord), +/// } +/// +/// enum ComplexEnum { +/// Nothing, +/// Something(u32), +/// LotsOfThings { +/// usual_struct_stuff: bool, +/// blah: String, +/// } +/// } +/// +/// enum EmptyEnum { } +/// ``` +/// +/// The first enum shown is the usual kind of enum you'd find in a C-style language. The second +/// shows off a hypothetical example of something storing location data, with Coord being any other +/// type that's needed, for example a struct. The third example demonstrates the kind of variant a +/// variant can store, ranging from nothing, to a tuple, to an anonymous struct. +/// +/// Instantiating enum variants involves explicitly using the enum's name as its namespace, +/// followed by one of its variants. `SimpleEnum::SecondVariant` would be an example from above. +/// When data follows along with a variant, such as with rust's built-in [`Option`] type, the data +/// is added as the type describes, for example `Option::Some(123)`. The same follows with +/// struct-like variants, with things looking like `ComplexEnum::LotsOfThings { usual_struct_stuff: +/// true, blah: "hello!".to_string(), }`. Empty Enums are similar to () in that they cannot be +/// instantiated at all, and are used mainly to mess with the type system in interesting ways. +/// +/// For more information, take a look at the [Rust Book] or the [Reference] +/// +/// [`Option`]: option/enum.Option.html +/// [Rust Book]: https://doc.rust-lang.org/book/second-edition/ch06-01-defining-an-enum.html +/// [Reference]: https://doc.rust-lang.org/reference/items/enumerations.html +mod enum_keyword { } + #[doc(keyword = "fn")] // /// The `fn` keyword. -- cgit 1.4.1-3-g733a5 From f91ad440efdf4730946c21f17acc3e1c920dd894 Mon Sep 17 00:00:00 2001 From: iirelu Date: Sun, 9 Sep 2018 13:23:34 +0200 Subject: Add docs on `extern` keyword --- src/libstd/keyword_docs.rs | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 5026ca4d722..a09917afbad 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -179,6 +179,48 @@ mod crate_keyword { } /// [Reference]: https://doc.rust-lang.org/reference/items/enumerations.html mod enum_keyword { } +#[doc(keyword = "extern")] +// +/// For external connections in Rust code. +/// +/// The `extern` keyword is used in two places in Rust. One is in conjunction with the [`crate`] +/// keyword to make your Rust code aware of other Rust crates in your project, i.e. `extern crate +/// lazy_static;`. The other use is in foreign function interfaces (FFI). +/// +/// `extern` is used in two different contexts within FFI. The first is in the form of external +/// blcoks, for declaring function interfaces that Rust code can call foreign code by. +/// +/// ```rust ignore +/// #[link(name = "my_c_library")] +/// extern "C" { +/// fn my_c_function(x: i32) -> bool; +/// } +/// ``` +/// +/// This code would attempt to link with libmy_c_library.so on unix-like systems and +/// my_c_library.dll on Windows at runtime, and panic if it can't find something to link to. Rust +/// code could then use `my_c_function` as if it were any other unsafe Rust function. Working with +/// non-Rust languages and FFI is inherently unsafe, so wrappers are usually built around C APIs. +/// +/// The mirror use case of FFI is also done via the `extern` keyword: +/// +/// ```rust +/// # #![allow(private_no_mangle_fns)] +/// #[no_mangle] +/// pub extern fn callable_from_c(x: i32) -> bool { +/// x % 3 == 0 +/// } +/// ``` +/// +/// If compiled as a dylib, the resulting .so could then be linked to from a C library, and the +/// function could be used as if it was from any other library. +/// +/// For more information on FFI, check the [Rust book] or the [Reference]. +/// +/// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code +/// [Reference]: https://doc.rust-lang.org/reference/items/external-blocks.html +mod extern_keyword { } + #[doc(keyword = "fn")] // /// The `fn` keyword. -- cgit 1.4.1-3-g733a5 From a5c4a382b7f0f9bb6a98001a6e5ffd9ab8ff3d70 Mon Sep 17 00:00:00 2001 From: iirelu Date: Sun, 9 Sep 2018 15:44:59 +0200 Subject: Expand fn keyword docs --- src/libstd/keyword_docs.rs | 66 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 59 insertions(+), 7 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index a09917afbad..0cf524ab0dc 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -223,21 +223,73 @@ mod extern_keyword { } #[doc(keyword = "fn")] // -/// The `fn` keyword. +/// The keyword for defining functions. /// -/// The `fn` keyword is used to declare a function. +/// Functions are the primary way code is executed within Rust. Function blocks, usually just +/// called functions, can be defined in a variety of different places and be assigned many +/// different attributes and modifiers. /// -/// Example: +/// Standalone functions that just sit within a module not attached to anything else are common, +/// but most functions will end up being inside [`impl`] blocks, either on another type itself, or +/// as a trait impl for that type. /// /// ```rust -/// fn some_function() { -/// // code goes in here +/// fn standalone_function() { +/// // code +/// } +/// +/// pub fn public_thing(argument: bool) -> String { +/// // code +/// # "".to_string() +/// } +/// +/// struct Thing { +/// foo: i32, +/// } +/// +/// impl Thing { +/// pub fn new() -> Self { +/// Self { +/// foo: 42, +/// } +/// } /// } /// ``` /// -/// For more information about functions, take a look at the [Rust Book][book]. +/// See docs on [`impl`] and [`self`] for relevant details on those. +/// +/// In addition to presenting fixed types in the form of `fn name(arg: type, ..) -> return_type`, +/// functions can also declare a list of type parameters along with trait bounds that they fall +/// into. /// -/// [book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html +/// ```rust +/// fn generic_function(x: T) -> (T, T, T) { +/// (x.clone(), x.clone(), x.clone()) +/// } +/// +/// fn generic_where(x: T) -> T +/// where T: std::ops::Add + Copy +/// { +/// x + x + x +/// } +/// ``` +/// +/// Declaring trait bounds in the angle brackets is functionally identical to using a [`where`] +/// clause, but `where` is preferred due to it being easier to understand at a glance. +/// +/// Along with being made public via [`pub`], `fn` can also have an [`extern`] added for use in +/// FFI. +/// +/// For more information on the various types of functions and how they're used, consult the [Rust +/// book] or the [Reference]. +/// +/// [`impl`]: keyword.impl.html +/// [`self`]: keyword.self.html +/// [`where`]: keyword.where.html +/// [`pub`]: keyword.pub.html +/// [`extern`]: keyword.extern.html +/// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html +/// [Reference]: https://doc.rust-lang.org/reference/items/functions.html mod fn_keyword { } #[doc(keyword = "let")] -- cgit 1.4.1-3-g733a5 From f7a66388f3f58d679eaee4c89dbde1f8b26a009e Mon Sep 17 00:00:00 2001 From: iirelu Date: Mon, 10 Sep 2018 19:36:27 +0200 Subject: Document `for` keyword --- src/libstd/keyword_docs.rs | 71 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 0cf524ab0dc..74dcf665c03 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -292,6 +292,77 @@ mod extern_keyword { } /// [Reference]: https://doc.rust-lang.org/reference/items/functions.html mod fn_keyword { } +#[doc(keyword = "for")] +// +/// The `for` keyword. +/// +/// `for` is primarily used in for-in-loops, but it has a few other pieces of syntactic uses such as +/// `impl Trait for Type` (see [`impl`] for more info on that). for-in-loops, or to be more +/// precise, iterator loops, are a simple syntactic sugar over an exceedingly common practice +/// within Rust, which is to loop over an iterator until that iterator returns None (or [`break`] +/// is called). +/// +/// ```rust +/// for i in 0..5 { +/// println!("{}", i * 2); +/// } +/// +/// for i in std::iter::repeat(5) { +/// println!("turns out {} never stops being 5", i); +/// break; // would loop forever otherwise +/// } +/// +/// 'outer: for x in 5..50 { +/// for y in 0..10 { +/// if x == y { +/// break 'outer; +/// } +/// } +/// } +/// ``` +/// +/// As shown in the example above, `for` loops (along with all other loops) can be tagged, using +/// similar syntax to lifetimes (only visually similar, entirely distinct in practice). Giving the +/// same tag to `break` breaks the tagged loop, which is useful for inner loops. It is definitely +/// not a goto. +/// +/// A `for` loop expands as shown: +/// +/// ```rust +/// # fn code() { } +/// # let iterator = 0..2; +/// for loop_variable in iterator { +/// code() +/// } +/// ``` +/// +/// ```rust +/// # fn code() { } +/// # let iterator = 0..2; +/// { +/// let mut _iter = std::iter::IntoIterator::into_iter(iterator); +/// loop { +/// match _iter.next() { +/// Some(loop_variable) => { +/// code() +/// }, +/// None => break, +/// } +/// } +/// } +/// ``` +/// +/// More details on the functionality shown can be seen at the [`IntoIterator`] docs. +/// +/// For more information on for-loops, see the [Rust book] or the [Reference]. +/// +/// [`impl`]: keyword.impl.html +/// [`break`]: keyword.break.html +/// [`IntoIterator`]: iter/trait.IntoIterator.html +/// [Rust book]: https://doc.rust-lang.org/book/2018-edition/ch03-05-control-flow.html#looping-through-a-collection-with-for +/// [Reference]: https://doc.rust-lang.org/reference/expressions/loop-expr.html#iterator-loops +mod for_keyword { } + #[doc(keyword = "let")] // /// The `let` keyword. -- cgit 1.4.1-3-g733a5 From 5d05ae7235743c150ca1aa96c31f0421caf5440f Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 12 Sep 2018 16:43:13 +0200 Subject: Document `if` keyword. --- src/libstd/keyword_docs.rs | 78 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 74dcf665c03..d1f799fc980 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -363,6 +363,84 @@ mod fn_keyword { } /// [Reference]: https://doc.rust-lang.org/reference/expressions/loop-expr.html#iterator-loops mod for_keyword { } +#[doc(keyword = "if")] +// +/// If statements and expressions. +/// +/// `if` is a familiar construct to most programmers, and is the main way you'll often do logic in +/// your code. However, unlike in most languages, `if` blocks can also act as expressions. +/// +/// ```rust +/// # let rude = true; +/// if 1 == 2 { +/// println!("whoops, mathematics broke"); +/// } else { +/// println!("everything's fine!"); +/// } +/// +/// let greeting = if rude { +/// "sup nerd." +/// } else { +/// "hello, friend!" +/// }; +/// +/// if let Ok(x) = "123".parse::() { +/// println!("{} double that and you get {}!", greeting, x * 2); +/// } +/// ``` +/// +/// Shown above are the three typical forms an `if` block comes in. First is the usual kind of +/// thing you'd see in many languages, with an optional `else` block. Second uses `if` as an +/// expression, which is only possible if all branches return the same type. An `if` expression can +/// be used everywhere you'd expect. The third kind of `if` block is an `if let` block, which +/// behaves similarly to using a [`match`] expression: +/// +/// ```rust +/// if let Some(x) = Some(123) { +/// // code +/// # let _ = x; +/// } else { +/// // something else +/// } +/// +/// match Some(123) { +/// Some(x) => { +/// // code +/// # let _ = x; +/// }, +/// _ => { +/// // something else +/// }, +/// } +/// ``` +/// +/// See [`let`] for more information on pattern bindings. +/// +/// Each kind of `if` expression can be mixed and matched as needed. +/// +/// ```rust +/// if true == false { +/// println!("oh no"); +/// } else if "something" == "other thing" { +/// println!("oh dear"); +/// } else if let Some(200) = "blarg".parse::().ok() { +/// println!("uh oh"); +/// } else { +/// println!("phew, nothing's broken"); +/// } +/// ``` +/// +/// The `if` keyword is used in one other place in Rust, namely as a part of pattern matching +/// itself, allowing patterns such as `Some(x) if x > 200` to be used. +/// +/// For more information on `if` expressions, see the [Rust book] or the [Reference]. +/// +/// [`match`]: keyword.match.html +/// [`let`]: keyword.let.html +/// [Rust book]: https://doc.rust-lang.org/stable/book/2018-edition/ch03-05-control-flow.html#if-expressions +/// [Reference]: https://doc.rust-lang.org/reference/expressions/if-expr.html +mod if_keyword { } + #[doc(keyword = "let")] // /// The `let` keyword. -- cgit 1.4.1-3-g733a5 From 5393b277aa769b6d5eab2a18f13cb99a333b4f88 Mon Sep 17 00:00:00 2001 From: iirelu Date: Fri, 14 Sep 2018 14:40:26 +0200 Subject: Incorporate keyword doc PR critique --- src/libstd/keyword_docs.rs | 67 +++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 31 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index d1f799fc980..fbe7e244381 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -10,7 +10,7 @@ #[doc(keyword = "as")] // -/// The type coercion keyword. +/// The keyword for casting types. /// /// `as` is most commonly used to turn primitive types into other primitive types, but it has other /// uses that include turning pointers into addresses, addresses into pointers, and pointers into @@ -24,15 +24,20 @@ /// assert_eq!(true as u8 + thing2 as u8, 100); /// ``` /// -/// In general, any coercion that can be performed via writing out type hints can also be done -/// using `as`, so instead of writing `let x: u32 = 123`, you can write `let x = 123 as u32` (Note: -/// `let x = 123u32` would be best in that situation). The same is not true in the other direction, -/// however, explicitly using `as` allows a few more coercions that aren't allowed implicitly, such -/// as changing the type of a raw pointer or turning closures into raw pointers. +/// In general, any cast that can be performed via ascribing the type can also be done using `as`, +/// so instead of writing `let x: u32 = 123`, you can write `let x = 123 as u32` (Note: `let x: u32 +/// = 123` would be best in that situation). The same is not true in the other direction, however, +/// explicitly using `as` allows a few more coercions that aren't allowed implicitly, such as +/// changing the type of a raw pointer or turning closures into raw pointers. +/// +/// Other places `as` is used include as extra syntax for [`crate`] and [`use`], to change the name +/// something is imported as. /// /// For more information on what `as` is capable of, see the [Reference] /// /// [Reference]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions +/// [`crate`]: keyword.crate.html +/// [`use`]: keyword.use.html mod as_keyword { } #[doc(keyword = "const")] @@ -52,12 +57,12 @@ mod as_keyword { } /// /// Constants must be explicitly typed, unlike with `let` you can't ignore its type and let the /// compiler figure it out. Any constant value can be defined in a const, which in practice happens -/// to be most things that would be reasonable to have a constant. For example, you can't have a -/// File as a `const`. +/// to be most things that would be reasonable to have a constant (barring `const fn`s, coming +/// soon). For example, you can't have a File as a `const`. /// -/// The only lifetime allowed in a constant is 'static, which is the lifetime that encompasses all -/// others in a Rust program. For example, if you wanted to define a constant string, it would look -/// like this: +/// The only lifetime allowed in a constant is `'static`, which is the lifetime that encompasses +/// all others in a Rust program. For example, if you wanted to define a constant string, it would +/// look like this: /// /// ```rust /// const WORDS: &'static str = "hello rust!"; @@ -73,9 +78,8 @@ mod as_keyword { } /// to which one should be used at which times. To put it simply, constants are inlined wherever /// they're used, making using them identical to simply replacing the name of the const with its /// value. Static variables on the other hand point to a single location in memory, which all -/// accesses share. This means that, unlike with constants, they can't have destructors, but it -/// also means that (via unsafe code) they can be mutable, which is useful for the rare situations -/// in which you can't avoid using global state. +/// accesses share. This means that, unlike with constants, they can't have destructors, and act as +/// a single value across the entire codebase. /// /// Constants, as with statics, should always be in SCREAMING_SNAKE_CASE. /// @@ -130,8 +134,8 @@ mod crate_keyword { } /// /// Enums in Rust are similar to those of other compiled languages like C, but have important /// differences that make them considerably more powerful. What Rust calls enums are more commonly -/// known as Algebraic Data Types if you're coming from a functional programming background, but -/// the important part is that data can go with the enum variants. +/// known as Algebraic Data Types if you're coming from a functional programming background. The +/// important detail is that each enum variant can have data to go along with it. /// /// ```rust /// # struct Coord; @@ -160,9 +164,9 @@ mod crate_keyword { } /// ``` /// /// The first enum shown is the usual kind of enum you'd find in a C-style language. The second -/// shows off a hypothetical example of something storing location data, with Coord being any other -/// type that's needed, for example a struct. The third example demonstrates the kind of variant a -/// variant can store, ranging from nothing, to a tuple, to an anonymous struct. +/// shows off a hypothetical example of something storing location data, with `Coord` being any +/// other type that's needed, for example a struct. The third example demonstrates the kind of +/// data a variant can store, ranging from nothing, to a tuple, to an anonymous struct. /// /// Instantiating enum variants involves explicitly using the enum's name as its namespace, /// followed by one of its variants. `SimpleEnum::SecondVariant` would be an example from above. @@ -188,7 +192,7 @@ mod enum_keyword { } /// lazy_static;`. The other use is in foreign function interfaces (FFI). /// /// `extern` is used in two different contexts within FFI. The first is in the form of external -/// blcoks, for declaring function interfaces that Rust code can call foreign code by. +/// blocks, for declaring function interfaces that Rust code can call foreign code by. /// /// ```rust ignore /// #[link(name = "my_c_library")] @@ -197,8 +201,8 @@ mod enum_keyword { } /// } /// ``` /// -/// This code would attempt to link with libmy_c_library.so on unix-like systems and -/// my_c_library.dll on Windows at runtime, and panic if it can't find something to link to. Rust +/// This code would attempt to link with `libmy_c_library.so` on unix-like systems and +/// `my_c_library.dll` on Windows at runtime, and panic if it can't find something to link to. Rust /// code could then use `my_c_function` as if it were any other unsafe Rust function. Working with /// non-Rust languages and FFI is inherently unsafe, so wrappers are usually built around C APIs. /// @@ -275,7 +279,8 @@ mod extern_keyword { } /// ``` /// /// Declaring trait bounds in the angle brackets is functionally identical to using a [`where`] -/// clause, but `where` is preferred due to it being easier to understand at a glance. +/// clause. It's up to the programmer to decide which works better in each situation, but `where` +/// tends to be better when things get longer than one line. /// /// Along with being made public via [`pub`], `fn` can also have an [`extern`] added for use in /// FFI. @@ -475,8 +480,8 @@ mod let_keyword { } // /// The keyword used to define structs. /// -/// Structs in Rust come in three flavours: Regular structs, tuple structs, -/// and empty structs. +/// Structs in Rust come in three flavours: Structs with named fields, tuple structs, and unit +/// structs. /// /// ```rust /// struct Regular { @@ -487,7 +492,7 @@ mod let_keyword { } /// /// struct Tuple(u32, String); /// -/// struct Empty; +/// struct Unit; /// ``` /// /// Regular structs are the most commonly used. Each field defined within them has a name and a @@ -501,14 +506,14 @@ mod let_keyword { } /// individual variables, the same syntax is used as with regular tuples, namely `foo.0`, `foo.1`, /// etc, starting at zero. /// -/// Empty structs, or unit-like structs, are most commonly used as markers, for example -/// [`PhantomData`]. Empty structs have a size of zero bytes, but unlike empty enums they can be -/// instantiated, making them similar to the unit type `()`. Unit-like structs are useful when you -/// need to implement a trait on something, but don't need to store any data inside it. +/// Unit structs are most commonly used as marker. They have a size of zero bytes, but unlike empty +/// enums they can be instantiated, making them isomorphic to the unit type `()`. Unit structs are +/// useful when you need to implement a trait on something, but don't need to store any data inside +/// it. /// /// # Instantiation /// -/// Structs can be instantiated in a manner of different ways, each of which can be mixed and +/// Structs can be instantiated in different ways, all of which can be mixed and /// matched as needed. The most common way to make a new struct is via a constructor method such as /// `new()`, but when that isn't available (or you're writing the constructor itself), struct /// literal syntax is used: -- cgit 1.4.1-3-g733a5 From 738e58d57e0911a02c076f2b6064a7f471ecb0c1 Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 19 Sep 2018 17:01:07 +0200 Subject: Document impl keyword This commit also splits out linky-line-thingies into two lines, which judging from the source code for tidy, should be enough to make it shut up and accept me for who I am, dammit. --- src/libstd/keyword_docs.rs | 76 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 5 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index fbe7e244381..6f8ff1a4b71 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -35,7 +35,8 @@ /// /// For more information on what `as` is capable of, see the [Reference] /// -/// [Reference]: https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions +/// [Reference]: +/// https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions /// [`crate`]: keyword.crate.html /// [`use`]: keyword.use.html mod as_keyword { } @@ -90,7 +91,8 @@ mod as_keyword { } /// /// [`static`]: keyword.static.html /// [pointer]: primitive.pointer.html -/// [Rust Book]: https://doc.rust-lang.org/stable/book/2018-edition/ch03-01-variables-and-mutability.html#differences-between-variables-and-constants +/// [Rust Book]: +/// https://doc.rust-lang.org/stable/book/2018-edition/ch03-01-variables-and-mutability.html#differences-between-variables-and-constants /// [Reference]: https://doc.rust-lang.org/reference/items/constant-items.html mod const_keyword { } @@ -221,7 +223,8 @@ mod enum_keyword { } /// /// For more information on FFI, check the [Rust book] or the [Reference]. /// -/// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code +/// [Rust book]: +/// https://doc.rust-lang.org/book/second-edition/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code /// [Reference]: https://doc.rust-lang.org/reference/items/external-blocks.html mod extern_keyword { } @@ -364,7 +367,8 @@ mod fn_keyword { } /// [`impl`]: keyword.impl.html /// [`break`]: keyword.break.html /// [`IntoIterator`]: iter/trait.IntoIterator.html -/// [Rust book]: https://doc.rust-lang.org/book/2018-edition/ch03-05-control-flow.html#looping-through-a-collection-with-for +/// [Rust book]: +/// https://doc.rust-lang.org/book/2018-edition/ch03-05-control-flow.html#looping-through-a-collection-with-for /// [Reference]: https://doc.rust-lang.org/reference/expressions/loop-expr.html#iterator-loops mod for_keyword { } @@ -442,10 +446,72 @@ mod for_keyword { } /// /// [`match`]: keyword.match.html /// [`let`]: keyword.let.html -/// [Rust book]: https://doc.rust-lang.org/stable/book/2018-edition/ch03-05-control-flow.html#if-expressions +/// [Rust book]: +/// https://doc.rust-lang.org/stable/book/2018-edition/ch03-05-control-flow.html#if-expressions /// [Reference]: https://doc.rust-lang.org/reference/expressions/if-expr.html mod if_keyword { } +#[doc(keyword = "impl")] +// +/// The implementation-defining keyword. +/// +/// The `impl` keyword is primarily used for defining implementations on types. There are two kinds +/// of implementations: Inherent implementations and trait implementations. Inherent +/// implementations define functions that operate on a type, known in object-oriented languages as +/// methods. Trait implementations are used to give a type a trait, and implement any of the +/// required associated items or methods that it requires. +/// +/// ```rust +/// struct Example { +/// number: i32, +/// } +/// +/// impl Example { +/// fn boo() { +/// println!("boo! Example::boo() was called!"); +/// } +/// +/// fn answer(&mut self) { +/// self.number += 42; +/// } +/// +/// fn get_number(&self) -> i32 { +/// self.number +/// } +/// } +/// +/// trait Thingy { +/// fn do_thingy(&self); +/// } +/// +/// impl Thingy for Example { +/// fn do_thingy(&self) { +/// println!("doing a thing! also, number is {}!", self.number); +/// } +/// } +/// ``` +/// +/// For more information on implementations, see the [Rust book][book1] or the [Reference]. +/// +/// The other use of the `impl` keyword is in `impl Trait` syntax, which can be seen as a shorthand +/// for "a concrete type that implements this trait". Its primary use is working with closures, +/// which have type definitions generated at compile time that can't be simply typed out. +/// +/// ```rust +/// fn thing_returning_closure() -> impl Fn(i32) -> bool { +/// println!("here's a closure for you!"); +/// |x: i32| x % 3 == 0 +/// } +/// ``` +/// +/// For more information on `impl Trait` syntax, see the [Rust book][book2]. +/// +/// [book1]: https://doc.rust-lang.org/stable/book/2018-edition/ch05-03-method-syntax.html +/// [Reference]: https://doc.rust-lang.org/reference/items/implementations.html +/// [book2]: +/// https://doc.rust-lang.org/stable/book/2018-edition/ch10-02-traits.html#returning-traits +mod impl_keyword { } + #[doc(keyword = "let")] // /// The `let` keyword. -- cgit 1.4.1-3-g733a5 From 165690b7db9183945230d43f73c2042a34ed09cf Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 19 Sep 2018 18:08:22 +0200 Subject: Rework `let` keyword docs It didn't strictly need to be reworked and I'm not sure my version is better, but oh well, I'm doing it for consistency. --- src/libstd/keyword_docs.rs | 62 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 14 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 6f8ff1a4b71..d2a22334a95 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -514,32 +514,66 @@ mod impl_keyword { } #[doc(keyword = "let")] // -/// The `let` keyword. +/// The variable binding keyword. /// -/// The `let` keyword is used to declare a variable. -/// -/// Example: +/// The primary use for the `let` keyword is in `let` statements, which are used to introduce a new +/// set of variables into the current scope, as given by a pattern. /// /// ```rust /// # #![allow(unused_assignments)] -/// let x = 3; // We create a variable named `x` with the value `3`. +/// let thing1: i32 = 100; +/// let thing2 = 200 + thing1; +/// +/// let mut changing_thing = true; +/// changing_thing = false; +/// +/// let (part1, part2) = ("first", "second"); +/// +/// struct Example { +/// a: bool, +/// b: u64, +/// } +/// +/// let Example { a, b: _ } = Example { +/// a: true, +/// b: 10004, +/// }; +/// assert!(a); /// ``` /// -/// By default, all variables are **not** mutable. If you want a mutable variable, -/// you'll have to use the `mut` keyword. +/// The pattern is most commonly a single variable, which means no pattern matching is done and +/// the expression given is bound to the variable. Apart from that, patterns used in `let` bindings +/// can be as complicated as needed, given that the pattern is exhaustive. See the [Rust +/// book][book1] for more information on pattern matching. The type of the pattern is optionally +/// given afterwards, but if left blank is automatically inferred by the compiler if possible. /// -/// Example: +/// Variables in Rust are immutable by default, and require the [`mut`] keyword to be made mutable. /// -/// ```rust -/// # #![allow(unused_assignments)] -/// let mut x = 3; // We create a mutable variable named `x` with the value `3`. +/// Multiple variables can be defined with the same name, known as shadowing. This doesn't affect +/// the original variable in any way beyond being unable to directly access it beyond the point of +/// shadowing. It continues to remain in scope, getting dropped only when it falls out of scope. +/// Shadowed variables don't need to have the same type as the variables shadowing them. /// -/// x += 4; // `x` is now equal to `7`. +/// ```rust +/// let shadowing_example = true; +/// let shadowing_example = 123.4; +/// let shadowing_example = shadowing_example as u32; +/// let mut shadowing_example = format!("cool! {}", shadowing_example); +/// shadowing_example += " something else!"; // not shadowing /// ``` /// -/// For more information about the `let` keyword, take a look at the [Rust Book][book]. +/// Other places the `let` keyword is used include along with [`if`], in the form of `if let` +/// expressions. They're useful if the pattern being matched isn't exhaustive, such as with +/// enumerations. +/// +/// For more information on the `let` keyword, see the [Rust book] or the [Reference] /// -/// [book]: https://doc.rust-lang.org/book/second-edition/ch03-01-variables-and-mutability.html +/// [book1]: https://doc.rust-lang.org/stable/book/2018-edition/ch06-02-match.html +/// [`mut`]: keyword.mut.html +/// [`if`]: keyword.if.html +/// [book2]: +/// https://doc.rust-lang.org/stable/book/2018-edition/ch18-01-all-the-places-for-patterns.html#let-statements +/// [Reference]: https://doc.rust-lang.org/reference/statements.html#let-statements mod let_keyword { } #[doc(keyword = "struct")] -- cgit 1.4.1-3-g733a5 From 76a353b160cdb8551eac8affc8299df85da50558 Mon Sep 17 00:00:00 2001 From: iirelu Date: Mon, 24 Sep 2018 16:42:43 +0200 Subject: Add keyword docs for `loop`. --- src/libstd/keyword_docs.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index d2a22334a95..63df5401b92 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -576,6 +576,51 @@ mod impl_keyword { } /// [Reference]: https://doc.rust-lang.org/reference/statements.html#let-statements mod let_keyword { } +#[doc(keyword = "loop")] +// +/// The loop-defining keyword. +/// +/// `loop` is used to define the simplest kind of loop supported in Rust. It runs the code inside +/// it until the code uses `break` or the program exits. +/// +/// ```rust +/// loop { +/// println!("hello world forever!"); +/// # break; +/// } +/// +/// let mut i = 0; +/// loop { +/// println!("i is {}", i); +/// if i > 10 { +/// break; +/// } +/// i += 1; +/// } +/// ``` +/// +/// Unlike the other kinds of loops in Rust (`while`, `while let`, and `for`), loops can be used as +/// expressions that return values via `break`. +/// +/// ```rust +/// let mut i = 1; +/// let something = loop { +/// i *= 2; +/// if i > 100 { +/// break i; +/// } +/// }; +/// assert_eq!(something, 128); +/// ``` +/// +/// Every `break` in a loop has to have the same type. When it's not explicitly giving something, +/// `break;` returns `()`. +/// +/// For more information on `loop` and loops in general, see the [Reference]. +/// +/// [Reference]: https://doc.rust-lang.org/reference/expressions/loop-expr.html +mod loop_keyword { } + #[doc(keyword = "struct")] // /// The keyword used to define structs. -- cgit 1.4.1-3-g733a5 From 50f631ce80ac3d04d52e4d6b3b4c5126ac9c1009 Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 26 Sep 2018 16:52:47 +0200 Subject: Removed dead links to unwritten keyword docs Most of these will eventually be filled, but right now travis-ci enjoys complaining about the fact that there's links that lead nowhere, so they're gone. Hopefully someone remembers to re-add them later. --- src/libstd/keyword_docs.rs | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 63df5401b92..cd7b3895289 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -30,7 +30,7 @@ /// explicitly using `as` allows a few more coercions that aren't allowed implicitly, such as /// changing the type of a raw pointer or turning closures into raw pointers. /// -/// Other places `as` is used include as extra syntax for [`crate`] and [`use`], to change the name +/// Other places `as` is used include as extra syntax for [`crate`] and `use`, to change the name /// something is imported as. /// /// For more information on what `as` is capable of, see the [Reference] @@ -38,7 +38,6 @@ /// [Reference]: /// https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions /// [`crate`]: keyword.crate.html -/// [`use`]: keyword.use.html mod as_keyword { } #[doc(keyword = "const")] @@ -75,7 +74,7 @@ mod as_keyword { } /// const WORDS: &str = "hello convenience!"; /// ``` /// -/// `const` items looks remarkably similar to [`static`] items, which introduces some confusion as +/// `const` items looks remarkably similar to `static` items, which introduces some confusion as /// to which one should be used at which times. To put it simply, constants are inlined wherever /// they're used, making using them identical to simply replacing the name of the const with its /// value. Static variables on the other hand point to a single location in memory, which all @@ -89,7 +88,6 @@ mod as_keyword { } /// /// For more detail on `const`, see the [Rust Book] or the [Reference] /// -/// [`static`]: keyword.static.html /// [pointer]: primitive.pointer.html /// [Rust Book]: /// https://doc.rust-lang.org/stable/book/2018-edition/ch03-01-variables-and-mutability.html#differences-between-variables-and-constants @@ -114,7 +112,7 @@ mod const_keyword { } /// The `as` keyword can be used to change what the crate is referred to as in your project. If a /// crate name includes a dash, it is implicitly imported with the dashes replaced by underscores. /// -/// `crate` is also used as in conjunction with [`pub`] to signify that the item it's attached to +/// `crate` is also used as in conjunction with `pub` to signify that the item it's attached to /// is public only to other members of the same crate it's in. /// /// ```rust @@ -127,7 +125,6 @@ mod const_keyword { } /// ``` /// /// [Reference]: https://doc.rust-lang.org/reference/items/extern-crates.html -/// [`pub`]: keyword.pub.html mod crate_keyword { } #[doc(keyword = "enum")] @@ -263,8 +260,6 @@ mod extern_keyword { } /// } /// ``` /// -/// See docs on [`impl`] and [`self`] for relevant details on those. -/// /// In addition to presenting fixed types in the form of `fn name(arg: type, ..) -> return_type`, /// functions can also declare a list of type parameters along with trait bounds that they fall /// into. @@ -281,20 +276,17 @@ mod extern_keyword { } /// } /// ``` /// -/// Declaring trait bounds in the angle brackets is functionally identical to using a [`where`] +/// Declaring trait bounds in the angle brackets is functionally identical to using a `where` /// clause. It's up to the programmer to decide which works better in each situation, but `where` /// tends to be better when things get longer than one line. /// -/// Along with being made public via [`pub`], `fn` can also have an [`extern`] added for use in +/// Along with being made public via `pub`, `fn` can also have an [`extern`] added for use in /// FFI. /// /// For more information on the various types of functions and how they're used, consult the [Rust /// book] or the [Reference]. /// /// [`impl`]: keyword.impl.html -/// [`self`]: keyword.self.html -/// [`where`]: keyword.where.html -/// [`pub`]: keyword.pub.html /// [`extern`]: keyword.extern.html /// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html /// [Reference]: https://doc.rust-lang.org/reference/items/functions.html @@ -307,7 +299,7 @@ mod fn_keyword { } /// `for` is primarily used in for-in-loops, but it has a few other pieces of syntactic uses such as /// `impl Trait for Type` (see [`impl`] for more info on that). for-in-loops, or to be more /// precise, iterator loops, are a simple syntactic sugar over an exceedingly common practice -/// within Rust, which is to loop over an iterator until that iterator returns None (or [`break`] +/// within Rust, which is to loop over an iterator until that iterator returns None (or `break` /// is called). /// /// ```rust @@ -365,7 +357,6 @@ mod fn_keyword { } /// For more information on for-loops, see the [Rust book] or the [Reference]. /// /// [`impl`]: keyword.impl.html -/// [`break`]: keyword.break.html /// [`IntoIterator`]: iter/trait.IntoIterator.html /// [Rust book]: /// https://doc.rust-lang.org/book/2018-edition/ch03-05-control-flow.html#looping-through-a-collection-with-for @@ -402,7 +393,7 @@ mod for_keyword { } /// thing you'd see in many languages, with an optional `else` block. Second uses `if` as an /// expression, which is only possible if all branches return the same type. An `if` expression can /// be used everywhere you'd expect. The third kind of `if` block is an `if let` block, which -/// behaves similarly to using a [`match`] expression: +/// behaves similarly to using a `match` expression: /// /// ```rust /// if let Some(x) = Some(123) { @@ -423,8 +414,6 @@ mod for_keyword { } /// } /// ``` /// -/// See [`let`] for more information on pattern bindings. -/// /// Each kind of `if` expression can be mixed and matched as needed. /// /// ```rust @@ -444,8 +433,6 @@ mod for_keyword { } /// /// For more information on `if` expressions, see the [Rust book] or the [Reference]. /// -/// [`match`]: keyword.match.html -/// [`let`]: keyword.let.html /// [Rust book]: /// https://doc.rust-lang.org/stable/book/2018-edition/ch03-05-control-flow.html#if-expressions /// [Reference]: https://doc.rust-lang.org/reference/expressions/if-expr.html -- cgit 1.4.1-3-g733a5 From 577dbc8519be61c1318b242c6c7fc15bbdf3b4b7 Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 26 Sep 2018 17:06:11 +0200 Subject: Incorporate criticisms into keyword docs Thanks to @Centril for these. --- src/libstd/keyword_docs.rs | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index cd7b3895289..dc78accc69f 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -10,7 +10,7 @@ #[doc(keyword = "as")] // -/// The keyword for casting types. +/// The keyword for casting a value to a type. /// /// `as` is most commonly used to turn primitive types into other primitive types, but it has other /// uses that include turning pointers into addresses, addresses into pointers, and pointers into @@ -133,7 +133,7 @@ mod crate_keyword { } /// /// Enums in Rust are similar to those of other compiled languages like C, but have important /// differences that make them considerably more powerful. What Rust calls enums are more commonly -/// known as Algebraic Data Types if you're coming from a functional programming background. The +/// known as [Algebraic Data Types] if you're coming from a functional programming background. The /// important detail is that each enum variant can have data to go along with it. /// /// ```rust @@ -177,6 +177,7 @@ mod crate_keyword { } /// /// For more information, take a look at the [Rust Book] or the [Reference] /// +/// [Algebraic Data Types]: https://en.wikipedia.org/wiki/Algebraic_data_type /// [`Option`]: option/enum.Option.html /// [Rust Book]: https://doc.rust-lang.org/book/second-edition/ch06-01-defining-an-enum.html /// [Reference]: https://doc.rust-lang.org/reference/items/enumerations.html @@ -442,11 +443,14 @@ mod if_keyword { } // /// The implementation-defining keyword. /// -/// The `impl` keyword is primarily used for defining implementations on types. There are two kinds -/// of implementations: Inherent implementations and trait implementations. Inherent -/// implementations define functions that operate on a type, known in object-oriented languages as -/// methods. Trait implementations are used to give a type a trait, and implement any of the -/// required associated items or methods that it requires. +/// The `impl` keyword is primarily used to define implementations on types. Inherent +/// implementations are standalone, while trait implementations are used to implement traits for +/// types, or other traits. +/// +/// Functions and consts can both be defined in an implementation. A function defined in an +/// `impl` block can be standalone, meaning it would be called like `Foo::bar()`. If the function +/// takes `self`, `&self`, or `&mut self` as its first argument, it can also be called using +/// method-call syntax, a familiar feature to any object oriented programmer, like `foo.bar()`. /// /// ```rust /// struct Example { @@ -551,7 +555,8 @@ mod impl_keyword { } /// /// Other places the `let` keyword is used include along with [`if`], in the form of `if let` /// expressions. They're useful if the pattern being matched isn't exhaustive, such as with -/// enumerations. +/// enumerations. `while let` also exists, which runs a loop with a pattern matched value until +/// that pattern can't be matched. /// /// For more information on the `let` keyword, see the [Rust book] or the [Reference] /// -- cgit 1.4.1-3-g733a5 From 619dfeb514d101ea167a850ef1cd338dc4759e23 Mon Sep 17 00:00:00 2001 From: iirelu Date: Wed, 26 Sep 2018 18:37:46 +0200 Subject: Remove the last broken link. Dangit. I really thought I got them all. --- src/libstd/keyword_docs.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index dc78accc69f..1e801373736 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -538,7 +538,7 @@ mod impl_keyword { } /// book][book1] for more information on pattern matching. The type of the pattern is optionally /// given afterwards, but if left blank is automatically inferred by the compiler if possible. /// -/// Variables in Rust are immutable by default, and require the [`mut`] keyword to be made mutable. +/// Variables in Rust are immutable by default, and require the `mut` keyword to be made mutable. /// /// Multiple variables can be defined with the same name, known as shadowing. This doesn't affect /// the original variable in any way beyond being unable to directly access it beyond the point of @@ -561,7 +561,6 @@ mod impl_keyword { } /// For more information on the `let` keyword, see the [Rust book] or the [Reference] /// /// [book1]: https://doc.rust-lang.org/stable/book/2018-edition/ch06-02-match.html -/// [`mut`]: keyword.mut.html /// [`if`]: keyword.if.html /// [book2]: /// https://doc.rust-lang.org/stable/book/2018-edition/ch18-01-all-the-places-for-patterns.html#let-statements -- cgit 1.4.1-3-g733a5 From c514b627e4bea768fe8560b96ce585689d008017 Mon Sep 17 00:00:00 2001 From: Charles Hathaway Date: Wed, 10 Oct 2018 11:13:35 -0400 Subject: update tcp stream documentation --- src/libstd/net/tcp.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 75c7a3d9280..848570e75e7 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -44,11 +44,10 @@ use time::Duration; /// use std::net::TcpStream; /// /// { -/// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap(); +/// let mut stream = TcpStream::connect("127.0.0.1:34254")?; /// -/// // ignore the Result -/// let _ = stream.write(&[1]); -/// let _ = stream.read(&mut [0; 128]); // ignore here too +/// stream.write(&[1])?; +/// stream.read(&mut [0; 128])?; /// } // the stream is closed here /// ``` #[stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From 4530b8c56cb7c1e539472e09c1e2704f67814912 Mon Sep 17 00:00:00 2001 From: Charles Hathaway Date: Thu, 11 Oct 2018 15:35:48 -0400 Subject: Small changes to fix documentation auto compile issues --- src/libstd/net/tcp.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 848570e75e7..ad212a54757 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -43,11 +43,12 @@ use time::Duration; /// use std::io::prelude::*; /// use std::net::TcpStream; /// -/// { +/// fn main() -> std::io::Result<()> { /// let mut stream = TcpStream::connect("127.0.0.1:34254")?; /// /// stream.write(&[1])?; /// stream.read(&mut [0; 128])?; +/// Ok(()) /// } // the stream is closed here /// ``` #[stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From 0f6e2741f692add6d1995b630e2073d18aa2b2ba Mon Sep 17 00:00:00 2001 From: Peter Hall Date: Sun, 21 Oct 2018 18:53:09 +0100 Subject: Clarified code example The example was not as clear as it could be because it was making an assumption about the structure of the data in order to multiply the number of collection elements by the item size. This change demonstrates the idea more straightforwardly, without the calculation. --- src/libstd/primitive_docs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index 7074928eaf6..79ccd593914 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -322,8 +322,8 @@ mod prim_never { } /// let s = String::from("love: ❤️"); /// let v: Vec = s.chars().collect(); /// -/// assert_eq!(12, s.len() * std::mem::size_of::()); -/// assert_eq!(32, v.len() * std::mem::size_of::()); +/// assert_eq!(12, std::mem::size_of_val(&s[..])); +/// assert_eq!(32, std::mem::size_of_val(&v[..])); /// ``` #[stable(feature = "rust1", since = "1.0.0")] mod prim_char { } -- cgit 1.4.1-3-g733a5 From 4972beaf65cad992a6ed791fdefe90e46c09aa7b Mon Sep 17 00:00:00 2001 From: Matthias Krüger Date: Mon, 22 Oct 2018 18:21:55 +0200 Subject: fix typos in various places --- src/bootstrap/bootstrap.py | 2 +- src/etc/lldb_rust_formatters.py | 2 +- src/liballoc/collections/btree/map.rs | 2 +- src/libcore/alloc.rs | 2 +- src/libcore/intrinsics.rs | 2 +- src/libcore/pin.rs | 2 +- src/libcore/ptr.rs | 2 +- src/librustc/hir/def_id.rs | 4 ++-- src/librustc/mir/interpret/mod.rs | 2 +- src/librustc/mir/mod.rs | 2 +- src/librustc/traits/error_reporting.rs | 2 +- src/librustc_codegen_llvm/builder.rs | 2 +- src/librustc_metadata/cstore_impl.rs | 2 +- src/librustc_mir/const_eval.rs | 2 +- src/librustc_mir/diagnostics.rs | 2 +- src/librustc_mir/interpret/eval_context.rs | 2 +- src/librustc_mir/interpret/memory.rs | 6 +++--- src/librustc_mir/interpret/operand.rs | 4 ++-- src/librustc_mir/interpret/validity.rs | 4 ++-- src/librustc_passes/ast_validation.rs | 16 ++++++++-------- src/librustc_target/abi/mod.rs | 2 +- src/librustc_typeck/check/mod.rs | 2 +- src/librustc_typeck/check/wfcheck.rs | 2 +- src/librustc_typeck/coherence/builtin.rs | 2 +- src/libstd/sync/mod.rs | 2 +- src/libstd/sync/once.rs | 4 ++-- src/libsyntax/config.rs | 4 ++-- src/test/run-pass/issues/issue-18804/main.rs | 2 +- src/test/ui/block-result/unexpected-return-on-unit.rs | 2 +- .../ui/conditional-compilation/cfg-attr-multi-false.rs | 2 +- src/test/ui/nll/issue-21232-partial-init-and-use.rs | 2 +- .../issue-52059-report-when-borrow-and-drop-conflict.rs | 2 +- src/test/ui/resolve/token-error-correct-2.rs | 2 +- src/test/ui/resolve/token-error-correct-3.rs | 2 +- src/test/ui/resolve/token-error-correct.rs | 2 +- .../ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.rs | 12 ++++++------ .../rfc-2497-if-let-chains/syntax-ambiguity-2015.stderr | 12 ++++++------ .../ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.rs | 12 ++++++------ .../rfc-2497-if-let-chains/syntax-ambiguity-2018.stderr | 12 ++++++------ src/test/ui/rust-2018/edition-lint-infer-outlives.fixed | 2 +- src/test/ui/rust-2018/edition-lint-infer-outlives.rs | 2 +- src/test/ui/specialization/issue-52050.rs | 2 +- src/tools/tidy/src/pal.rs | 2 +- 43 files changed, 77 insertions(+), 77 deletions(-) (limited to 'src/libstd') diff --git a/src/bootstrap/bootstrap.py b/src/bootstrap/bootstrap.py index c27f4f056d7..ffc5adbebb3 100644 --- a/src/bootstrap/bootstrap.py +++ b/src/bootstrap/bootstrap.py @@ -594,7 +594,7 @@ class RustBuild(object): return '' def bootstrap_binary(self): - """Return the path of the boostrap binary + """Return the path of the bootstrap binary >>> rb = RustBuild() >>> rb.build_dir = "build" diff --git a/src/etc/lldb_rust_formatters.py b/src/etc/lldb_rust_formatters.py index 4427313f9e5..2bbd4372721 100644 --- a/src/etc/lldb_rust_formatters.py +++ b/src/etc/lldb_rust_formatters.py @@ -277,7 +277,7 @@ def print_std_string_val(val, internal_dict): #=-------------------------------------------------------------------------------------------------- def print_array_of_values(array_name, data_ptr_val, length, internal_dict): - """Prints a contigous memory range, interpreting it as values of the + """Prints a contiguous memory range, interpreting it as values of the pointee-type of data_ptr_val.""" data_ptr_type = data_ptr_val.type diff --git a/src/liballoc/collections/btree/map.rs b/src/liballoc/collections/btree/map.rs index 8c950cd06d9..24c8fd3a969 100644 --- a/src/liballoc/collections/btree/map.rs +++ b/src/liballoc/collections/btree/map.rs @@ -77,7 +77,7 @@ use self::Entry::*; /// movie_reviews.insert("Office Space", "Deals with real issues in the workplace."); /// movie_reviews.insert("Pulp Fiction", "Masterpiece."); /// movie_reviews.insert("The Godfather", "Very enjoyable."); -/// movie_reviews.insert("The Blues Brothers", "Eye lyked it alot."); +/// movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot."); /// /// // check for a specific one. /// if !movie_reviews.contains_key("Les Misérables") { diff --git a/src/libcore/alloc.rs b/src/libcore/alloc.rs index 35e4eea756d..4efcaae59b0 100644 --- a/src/libcore/alloc.rs +++ b/src/libcore/alloc.rs @@ -518,7 +518,7 @@ pub unsafe trait GlobalAlloc { /// The block is described by the given `ptr` pointer and `layout`. /// /// If this returns a non-null pointer, then ownership of the memory block - /// referenced by `ptr` has been transferred to this alloctor. + /// referenced by `ptr` has been transferred to this allocator. /// The memory may or may not have been deallocated, /// and should be considered unusable (unless of course it was /// transferred back to the caller again via the return value of diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs index 56a24168e28..cceae9249e4 100644 --- a/src/libcore/intrinsics.rs +++ b/src/libcore/intrinsics.rs @@ -1025,7 +1025,7 @@ extern "rust-intrinsic" { /// // to avoid problems in case something further down panics. /// src.set_len(0); /// - /// // The two regions cannot overlap becuase mutable references do + /// // The two regions cannot overlap because mutable references do /// // not alias, and two different vectors cannot own the same /// // memory. /// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len); diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs index 0224560af4c..a03c080fb3f 100644 --- a/src/libcore/pin.rs +++ b/src/libcore/pin.rs @@ -102,7 +102,7 @@ pub use marker::Unpin; /// value in place, preventing the value referenced by that pointer from being moved /// unless it implements [`Unpin`]. /// -/// See the [`pin` module] documentation for furthur explanation on pinning. +/// See the [`pin` module] documentation for further explanation on pinning. /// /// [`Unpin`]: ../../std/marker/trait.Unpin.html /// [`pin` module]: ../../std/pin/index.html diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs index 1c761ba21b3..b699cb02884 100644 --- a/src/libcore/ptr.rs +++ b/src/libcore/ptr.rs @@ -38,7 +38,7 @@ //! underlying object is live and no reference (just raw pointers) is used to //! access the same memory. //! -//! These axioms, along with careful use of [`offset`] for pointer arithmentic, +//! These axioms, along with careful use of [`offset`] for pointer arithmetic, //! are enough to correctly implement many useful things in unsafe code. Stronger guarantees //! will be provided eventually, as the [aliasing] rules are being determined. For more //! information, see the [book] as well as the section in the reference devoted diff --git a/src/librustc/hir/def_id.rs b/src/librustc/hir/def_id.rs index a09fd5df557..e378e1b8be0 100644 --- a/src/librustc/hir/def_id.rs +++ b/src/librustc/hir/def_id.rs @@ -40,7 +40,7 @@ impl ::std::fmt::Debug for CrateNum { match self { CrateNum::Index(id) => write!(fmt, "crate{}", id.private), CrateNum::Invalid => write!(fmt, "invalid crate"), - CrateNum::BuiltinMacros => write!(fmt, "bultin macros crate"), + CrateNum::BuiltinMacros => write!(fmt, "builtin macros crate"), CrateNum::ReservedForIncrCompCache => write!(fmt, "crate for decoding incr comp cache"), } } @@ -101,7 +101,7 @@ impl fmt::Display for CrateNum { match self { CrateNum::Index(id) => fmt::Display::fmt(&id.private, f), CrateNum::Invalid => write!(f, "invalid crate"), - CrateNum::BuiltinMacros => write!(f, "bultin macros crate"), + CrateNum::BuiltinMacros => write!(f, "builtin macros crate"), CrateNum::ReservedForIncrCompCache => write!(f, "crate for decoding incr comp cache"), } } diff --git a/src/librustc/mir/interpret/mod.rs b/src/librustc/mir/interpret/mod.rs index 4c2b2b2d41d..5054f522778 100644 --- a/src/librustc/mir/interpret/mod.rs +++ b/src/librustc/mir/interpret/mod.rs @@ -632,7 +632,7 @@ pub fn read_target_uint(endianness: layout::Endian, mut source: &[u8]) -> Result } //////////////////////////////////////////////////////////////////////////////// -// Methods to faciliate working with signed integers stored in a u128 +// Methods to facilitate working with signed integers stored in a u128 //////////////////////////////////////////////////////////////////////////////// pub fn sign_extend(value: u128, size: Size) -> u128 { diff --git a/src/librustc/mir/mod.rs b/src/librustc/mir/mod.rs index 62b5327ae46..f1c5030c641 100644 --- a/src/librustc/mir/mod.rs +++ b/src/librustc/mir/mod.rs @@ -469,7 +469,7 @@ pub enum BorrowKind { /// } /// /// This can't be a shared borrow because mutably borrowing (*x as Some).0 - /// should not prevent `if let None = x { ... }`, for example, becase the + /// should not prevent `if let None = x { ... }`, for example, because the /// mutating `(*x as Some).0` can't affect the discriminant of `x`. /// We can also report errors with this kind of borrow differently. Shallow, diff --git a/src/librustc/traits/error_reporting.rs b/src/librustc/traits/error_reporting.rs index dc003992644..ea30752a820 100644 --- a/src/librustc/traits/error_reporting.rs +++ b/src/librustc/traits/error_reporting.rs @@ -412,7 +412,7 @@ impl<'a, 'gcx, 'tcx> InferCtxt<'a, 'gcx, 'tcx> { flags.push(("crate_local".to_owned(), None)); } - // Allow targetting all integers using `{integral}`, even if the exact type was resolved + // Allow targeting all integers using `{integral}`, even if the exact type was resolved if self_ty.is_integral() { flags.push(("_Self".to_owned(), Some("{integral}".to_owned()))); } diff --git a/src/librustc_codegen_llvm/builder.rs b/src/librustc_codegen_llvm/builder.rs index 169bd9a8466..2fe6a0377f8 100644 --- a/src/librustc_codegen_llvm/builder.rs +++ b/src/librustc_codegen_llvm/builder.rs @@ -761,7 +761,7 @@ impl Builder<'a, 'll, 'tcx> { fty, asm, cons, volatile, alignstack, dia); Some(self.call(v, inputs, None)) } else { - // LLVM has detected an issue with our constaints, bail out + // LLVM has detected an issue with our constraints, bail out None } } diff --git a/src/librustc_metadata/cstore_impl.rs b/src/librustc_metadata/cstore_impl.rs index 7988de28b5d..e6e1367b592 100644 --- a/src/librustc_metadata/cstore_impl.rs +++ b/src/librustc_metadata/cstore_impl.rs @@ -68,7 +68,7 @@ macro_rules! provide { let $cdata = $tcx.crate_data_as_rc_any($def_id.krate); let $cdata = $cdata.downcast_ref::() - .expect("CrateStore crated ata is not a CrateMetadata"); + .expect("CrateStore created data is not a CrateMetadata"); $compute })* diff --git a/src/librustc_mir/const_eval.rs b/src/librustc_mir/const_eval.rs index bc917140bbd..9702e94a9e0 100644 --- a/src/librustc_mir/const_eval.rs +++ b/src/librustc_mir/const_eval.rs @@ -129,7 +129,7 @@ pub fn op_to_const<'tcx>( assert!(alloc.bytes.len() as u64 - ptr.offset.bytes() >= op.layout.size.bytes()); let mut alloc = alloc.clone(); alloc.align = align; - // FIXME shouldnt it be the case that `mark_static_initialized` has already + // FIXME shouldn't it be the case that `mark_static_initialized` has already // interned this? I thought that is the entire point of that `FinishStatic` stuff? let alloc = ecx.tcx.intern_const_alloc(alloc); ConstValue::ByRef(ptr.alloc_id, alloc, ptr.offset) diff --git a/src/librustc_mir/diagnostics.rs b/src/librustc_mir/diagnostics.rs index bb3e4a8d881..56a9daf84f7 100644 --- a/src/librustc_mir/diagnostics.rs +++ b/src/librustc_mir/diagnostics.rs @@ -2279,7 +2279,7 @@ fn demo<'a>(s: &'a mut S<'a>) -> &'a mut String { let p = &mut *(*s).data; p } Note that this approach needs a reference to S with lifetime `'a`. Nothing shorter than `'a` will suffice: a shorter lifetime would imply -that after `demo` finishes excuting, something else (such as the +that after `demo` finishes executing, something else (such as the destructor!) could access `s.data` after the end of that shorter lifetime, which would again violate the `&mut`-borrow's exclusive access. diff --git a/src/librustc_mir/interpret/eval_context.rs b/src/librustc_mir/interpret/eval_context.rs index 18938892165..64ad4c2eec1 100644 --- a/src/librustc_mir/interpret/eval_context.rs +++ b/src/librustc_mir/interpret/eval_context.rs @@ -556,7 +556,7 @@ impl<'a, 'mir, 'tcx: 'mir, M: Machine<'a, 'mir, 'tcx>> EvalContext<'a, 'mir, 'tc )?; } } else { - // Uh, that shouln't happen... the function did not intend to return + // Uh, that shouldn't happen... the function did not intend to return return err!(Unreachable); } diff --git a/src/librustc_mir/interpret/memory.rs b/src/librustc_mir/interpret/memory.rs index 9adca6c4297..6fe490c6efc 100644 --- a/src/librustc_mir/interpret/memory.rs +++ b/src/librustc_mir/interpret/memory.rs @@ -94,7 +94,7 @@ impl<'a, 'b, 'c, 'mir, 'tcx, M: Machine<'a, 'mir, 'tcx>> HasDataLayout } } -// FIXME: Really we shouldnt clone memory, ever. Snapshot machinery should instad +// FIXME: Really we shouldn't clone memory, ever. Snapshot machinery should instead // carefully copy only the reachable parts. impl<'a, 'mir, 'tcx: 'a + 'mir, M: Machine<'a, 'mir, 'tcx>> Clone for Memory<'a, 'mir, 'tcx, M> @@ -658,7 +658,7 @@ impl<'a, 'mir, 'tcx, M: Machine<'a, 'mir, 'tcx>> Memory<'a, 'mir, 'tcx, M> { } /// It is the caller's responsibility to handle undefined and pointer bytes. - /// However, this still checks that there are no relocations on the *egdes*. + /// However, this still checks that there are no relocations on the *edges*. #[inline] fn get_bytes_with_undef_and_ptr( &self, @@ -1098,7 +1098,7 @@ impl<'a, 'mir, 'tcx, M: Machine<'a, 'mir, 'tcx>> Memory<'a, 'mir, 'tcx, M> { Ok(()) } - /// Error if there are relocations overlapping with the egdes of the + /// Error if there are relocations overlapping with the edges of the /// given memory range. #[inline] fn check_relocation_edges(&self, ptr: Pointer, size: Size) -> EvalResult<'tcx> { diff --git a/src/librustc_mir/interpret/operand.rs b/src/librustc_mir/interpret/operand.rs index 71b2f4b53a6..021e2d58f84 100644 --- a/src/librustc_mir/interpret/operand.rs +++ b/src/librustc_mir/interpret/operand.rs @@ -357,14 +357,14 @@ fn from_known_layout<'tcx>( } impl<'a, 'mir, 'tcx, M: Machine<'a, 'mir, 'tcx>> EvalContext<'a, 'mir, 'tcx, M> { - /// Try reading a value in memory; this is interesting particularily for ScalarPair. + /// Try reading a value in memory; this is interesting particularly for ScalarPair. /// Return None if the layout does not permit loading this as a value. pub(super) fn try_read_value_from_mplace( &self, mplace: MPlaceTy<'tcx, M::PointerTag>, ) -> EvalResult<'tcx, Option>> { if mplace.layout.is_unsized() { - // Dont touch unsized + // Don't touch unsized return Ok(None); } let (ptr, ptr_align) = mplace.to_scalar_ptr_align(); diff --git a/src/librustc_mir/interpret/validity.rs b/src/librustc_mir/interpret/validity.rs index 38cf79d8fa0..ac1ba0edc3b 100644 --- a/src/librustc_mir/interpret/validity.rs +++ b/src/librustc_mir/interpret/validity.rs @@ -230,7 +230,7 @@ impl<'a, 'mir, 'tcx, M: Machine<'a, 'mir, 'tcx>> EvalContext<'a, 'mir, 'tcx, M> ), } } - // non-ZST also have to be dereferencable + // non-ZST also have to be dereferenceable if size != Size::ZERO { let ptr = try_validation!(place.ptr.to_ptr(), "integer pointer in non-ZST reference", path); @@ -272,7 +272,7 @@ impl<'a, 'mir, 'tcx, M: Machine<'a, 'mir, 'tcx>> EvalContext<'a, 'mir, 'tcx, M> // FIXME: Check if the signature matches } // This should be all the primitive types - ty::Never => bug!("Uninhabited type should have been catched earlier"), + ty::Never => bug!("Uninhabited type should have been caught earlier"), _ => bug!("Unexpected primitive type {}", value.layout.ty) } Ok(()) diff --git a/src/librustc_passes/ast_validation.rs b/src/librustc_passes/ast_validation.rs index f6ace57f5e0..0e9596244cd 100644 --- a/src/librustc_passes/ast_validation.rs +++ b/src/librustc_passes/ast_validation.rs @@ -166,12 +166,12 @@ impl<'a> AstValidator<'a> { } } - /// With eRFC 2497, we need to check whether an expression is ambigious and warn or error + /// With eRFC 2497, we need to check whether an expression is ambiguous and warn or error /// depending on the edition, this function handles that. fn while_if_let_ambiguity(&self, expr: &P) { if let Some((span, op_kind)) = self.while_if_let_expr_ambiguity(&expr) { let mut err = self.err_handler().struct_span_err( - span, &format!("ambigious use of `{}`", op_kind.to_string()) + span, &format!("ambiguous use of `{}`", op_kind.to_string()) ); err.note( @@ -193,9 +193,9 @@ impl<'a> AstValidator<'a> { } /// With eRFC 2497 adding if-let chains, there is a requirement that the parsing of - /// `&&` and `||` in a if-let statement be unambigious. This function returns a span and - /// a `BinOpKind` (either `&&` or `||` depending on what was ambigious) if it is determined - /// that the current expression parsed is ambigious and will break in future. + /// `&&` and `||` in a if-let statement be unambiguous. This function returns a span and + /// a `BinOpKind` (either `&&` or `||` depending on what was ambiguous) if it is determined + /// that the current expression parsed is ambiguous and will break in future. fn while_if_let_expr_ambiguity(&self, expr: &P) -> Option<(Span, BinOpKind)> { debug!("while_if_let_expr_ambiguity: expr.node: {:?}", expr.node); match &expr.node { @@ -203,12 +203,12 @@ impl<'a> AstValidator<'a> { Some((expr.span, op.node)) }, ExprKind::Range(ref lhs, ref rhs, _) => { - let lhs_ambigious = lhs.as_ref() + let lhs_ambiguous = lhs.as_ref() .and_then(|lhs| self.while_if_let_expr_ambiguity(lhs)); - let rhs_ambigious = rhs.as_ref() + let rhs_ambiguous = rhs.as_ref() .and_then(|rhs| self.while_if_let_expr_ambiguity(rhs)); - lhs_ambigious.or(rhs_ambigious) + lhs_ambiguous.or(rhs_ambiguous) } _ => None, } diff --git a/src/librustc_target/abi/mod.rs b/src/librustc_target/abi/mod.rs index 6b28fd09174..1a5d2801af0 100644 --- a/src/librustc_target/abi/mod.rs +++ b/src/librustc_target/abi/mod.rs @@ -430,7 +430,7 @@ impl Align { } /// Lower the alignment, if necessary, such that the given offset - /// is aligned to it (the offset is a multiple of the aligment). + /// is aligned to it (the offset is a multiple of the alignment). pub fn restrict_for_offset(self, offset: Size) -> Align { self.min(Align::max_for_offset(offset)) } diff --git a/src/librustc_typeck/check/mod.rs b/src/librustc_typeck/check/mod.rs index 1c562859bb4..77151351d08 100644 --- a/src/librustc_typeck/check/mod.rs +++ b/src/librustc_typeck/check/mod.rs @@ -5198,7 +5198,7 @@ impl<'a, 'gcx, 'tcx> FnCtxt<'a, 'gcx, 'tcx> { } else { // If no type arguments were provided, we have to infer them. // This case also occurs as a result of some malformed input, e.g. - // a lifetime argument being given instead of a type paramter. + // a lifetime argument being given instead of a type parameter. // Using inference instead of `Error` gives better error messages. self.var_for_def(span, param) } diff --git a/src/librustc_typeck/check/wfcheck.rs b/src/librustc_typeck/check/wfcheck.rs index ec773e384af..9990d2ee2b6 100644 --- a/src/librustc_typeck/check/wfcheck.rs +++ b/src/librustc_typeck/check/wfcheck.rs @@ -674,7 +674,7 @@ fn check_existential_types<'a, 'fcx, 'gcx, 'tcx>( } // if may_define_existential_type // now register the bounds on the parameters of the existential type - // so the parameters given by the function need to fulfil them + // so the parameters given by the function need to fulfill them // ```rust // existential type Foo: 'static; // fn foo() -> Foo { .. *} diff --git a/src/librustc_typeck/coherence/builtin.rs b/src/librustc_typeck/coherence/builtin.rs index c54d9e4b475..05a83dd307c 100644 --- a/src/librustc_typeck/coherence/builtin.rs +++ b/src/librustc_typeck/coherence/builtin.rs @@ -269,7 +269,7 @@ pub fn coerce_unsized_info<'a, 'gcx>(gcx: TyCtxt<'a, 'gcx, 'gcx>, // exactly one (non-phantom) field has changed its // type, which we will expect to be the pointer that // is becoming fat (we could probably generalize this - // to mutiple thin pointers of the same type becoming + // to multiple thin pointers of the same type becoming // fat, but we don't). In this case: // // - `extra` has type `T` before and type `T` after diff --git a/src/libstd/sync/mod.rs b/src/libstd/sync/mod.rs index d69ebc17622..a7db372a0e2 100644 --- a/src/libstd/sync/mod.rs +++ b/src/libstd/sync/mod.rs @@ -97,7 +97,7 @@ //! - A **multiprocessor** system executing multiple hardware threads //! at the same time: In multi-threaded scenarios, you can use two //! kinds of primitives to deal with synchronization: -//! - [memory fences] to ensure memory accesses are made visibile to +//! - [memory fences] to ensure memory accesses are made visible to //! other CPUs in the right order. //! - [atomic operations] to ensure simultaneous access to the same //! memory location doesn't lead to undefined behavior. diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs index 98845e457b2..cf9698cb2a9 100644 --- a/src/libstd/sync/once.rs +++ b/src/libstd/sync/once.rs @@ -290,8 +290,8 @@ impl Once { } /// Returns true if some `call_once` call has completed - /// successfuly. Specifically, `is_completed` will return false in - /// the following situtations: + /// successfully. Specifically, `is_completed` will return false in + /// the following situations: /// * `call_once` was not called at all, /// * `call_once` was called, but has not yet completed, /// * the `Once` instance is poisoned diff --git a/src/libsyntax/config.rs b/src/libsyntax/config.rs index e611eb86dc1..d8fb20d4250 100644 --- a/src/libsyntax/config.rs +++ b/src/libsyntax/config.rs @@ -96,7 +96,7 @@ impl<'a> StripUnconfigured<'a> { /// when the configuration predicate is true, or otherwise expand into an /// empty list of attributes. /// - /// Gives a compiler warning when the `cfg_attr` contains no attribtes and + /// Gives a compiler warning when the `cfg_attr` contains no attributes and /// is in the original source file. Gives a compiler error if the syntax of /// the attribute is incorrect fn process_cfg_attr(&mut self, attr: ast::Attribute) -> Vec { @@ -138,7 +138,7 @@ impl<'a> StripUnconfigured<'a> { }; // Check feature gate and lint on zero attributes in source. Even if the feature is gated, - // we still compute as if it wasn't, since the emitted error will stop compilation futher + // we still compute as if it wasn't, since the emitted error will stop compilation further // along the compilation. match (expanded_attrs.len(), gate_cfg_attr_multi) { (0, false) => { diff --git a/src/test/run-pass/issues/issue-18804/main.rs b/src/test/run-pass/issues/issue-18804/main.rs index a3a5337077c..2abcd4b7ba9 100644 --- a/src/test/run-pass/issues/issue-18804/main.rs +++ b/src/test/run-pass/issues/issue-18804/main.rs @@ -9,7 +9,7 @@ // except according to those terms. // run-pass -// Test for issue #18804, #[linkage] does not propagate thorugh generic +// Test for issue #18804, #[linkage] does not propagate through generic // functions. Failure results in a linker error. // ignore-asmjs no weak symbol support diff --git a/src/test/ui/block-result/unexpected-return-on-unit.rs b/src/test/ui/block-result/unexpected-return-on-unit.rs index 3cf76365c77..b116888d63c 100644 --- a/src/test/ui/block-result/unexpected-return-on-unit.rs +++ b/src/test/ui/block-result/unexpected-return-on-unit.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -// Test that we do some basic error correcton in the tokeniser (and don't spew +// Test that we do some basic error correction in the tokeniser (and don't spew // too many bogus errors). fn foo() -> usize { diff --git a/src/test/ui/conditional-compilation/cfg-attr-multi-false.rs b/src/test/ui/conditional-compilation/cfg-attr-multi-false.rs index 84bd33fc0e7..ec4ee80b498 100644 --- a/src/test/ui/conditional-compilation/cfg-attr-multi-false.rs +++ b/src/test/ui/conditional-compilation/cfg-attr-multi-false.rs @@ -1,5 +1,5 @@ // Test that cfg_attr doesn't emit any attributes when the -// configuation variable is false. This mirrors `cfg-attr-multi-true.rs` +// configuration variable is false. This mirrors `cfg-attr-multi-true.rs` // compile-pass diff --git a/src/test/ui/nll/issue-21232-partial-init-and-use.rs b/src/test/ui/nll/issue-21232-partial-init-and-use.rs index e3ae4c0dcbe..186ecc54827 100644 --- a/src/test/ui/nll/issue-21232-partial-init-and-use.rs +++ b/src/test/ui/nll/issue-21232-partial-init-and-use.rs @@ -66,7 +66,7 @@ impl R { fn new(f: F) -> Self { R { w: 0, f } } } // It got pretty monotonous writing the same code over and over, and I // feared I would forget details. So I abstracted some desiderata into // macros. But I left the initialization code inline, because that's -// where the errors for #54986 will be emited. +// where the errors for #54986 will be emitted. macro_rules! use_fully { (struct $s:expr) => { { diff --git a/src/test/ui/nll/issue-52059-report-when-borrow-and-drop-conflict.rs b/src/test/ui/nll/issue-52059-report-when-borrow-and-drop-conflict.rs index fff73c6d0fa..eaa809d2b37 100644 --- a/src/test/ui/nll/issue-52059-report-when-borrow-and-drop-conflict.rs +++ b/src/test/ui/nll/issue-52059-report-when-borrow-and-drop-conflict.rs @@ -1,5 +1,5 @@ // rust-lang/rust#52059: Regardless of whether you are moving out of a -// Drop type or just introducing an inadvertant alias via a borrow of +// Drop type or just introducing an inadvertent alias via a borrow of // one of its fields, it is useful to be reminded of the significance // of the fact that the type implements Drop. diff --git a/src/test/ui/resolve/token-error-correct-2.rs b/src/test/ui/resolve/token-error-correct-2.rs index e49374f9ce6..55803e4034b 100644 --- a/src/test/ui/resolve/token-error-correct-2.rs +++ b/src/test/ui/resolve/token-error-correct-2.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -// Test that we do some basic error correcton in the tokeniser (and don't ICE). +// Test that we do some basic error correction in the tokeniser (and don't ICE). fn main() { if foo { diff --git a/src/test/ui/resolve/token-error-correct-3.rs b/src/test/ui/resolve/token-error-correct-3.rs index 8881b965f94..fd4bbde2866 100644 --- a/src/test/ui/resolve/token-error-correct-3.rs +++ b/src/test/ui/resolve/token-error-correct-3.rs @@ -10,7 +10,7 @@ // ignore-cloudabi no std::fs support -// Test that we do some basic error correcton in the tokeniser (and don't spew +// Test that we do some basic error correction in the tokeniser (and don't spew // too many bogus errors). pub mod raw { diff --git a/src/test/ui/resolve/token-error-correct.rs b/src/test/ui/resolve/token-error-correct.rs index 39c664e270c..099ead93beb 100644 --- a/src/test/ui/resolve/token-error-correct.rs +++ b/src/test/ui/resolve/token-error-correct.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -// Test that we do some basic error correcton in the tokeniser. +// Test that we do some basic error correction in the tokeniser. fn main() { foo(bar(; diff --git a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.rs b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.rs index 339d49104b0..31a34a9e6fb 100644 --- a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.rs +++ b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.rs @@ -19,22 +19,22 @@ fn main() { use std::ops::Range; if let Range { start: _, end: _ } = true..true && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` if let Range { start: _, end: _ } = true..true || false { } - //~^ ERROR ambigious use of `||` + //~^ ERROR ambiguous use of `||` while let Range { start: _, end: _ } = true..true && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` while let Range { start: _, end: _ } = true..true || false { } - //~^ ERROR ambigious use of `||` + //~^ ERROR ambiguous use of `||` if let true = false && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` while let true = (1 == 2) && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` // The following cases are not an error as parenthesis are used to // clarify intent: diff --git a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.stderr b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.stderr index 8597294913f..411cb99fbca 100644 --- a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.stderr +++ b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2015.stderr @@ -1,4 +1,4 @@ -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2015.rs:21:47 | LL | if let Range { start: _, end: _ } = true..true && false { } @@ -7,7 +7,7 @@ LL | if let Range { start: _, end: _ } = true..true && false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `||` +error: ambiguous use of `||` --> $DIR/syntax-ambiguity-2015.rs:24:47 | LL | if let Range { start: _, end: _ } = true..true || false { } @@ -16,7 +16,7 @@ LL | if let Range { start: _, end: _ } = true..true || false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2015.rs:27:50 | LL | while let Range { start: _, end: _ } = true..true && false { } @@ -25,7 +25,7 @@ LL | while let Range { start: _, end: _ } = true..true && false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `||` +error: ambiguous use of `||` --> $DIR/syntax-ambiguity-2015.rs:30:50 | LL | while let Range { start: _, end: _ } = true..true || false { } @@ -34,7 +34,7 @@ LL | while let Range { start: _, end: _ } = true..true || false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2015.rs:33:19 | LL | if let true = false && false { } @@ -43,7 +43,7 @@ LL | if let true = false && false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2015.rs:36:22 | LL | while let true = (1 == 2) && false { } diff --git a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.rs b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.rs index baa90bcf8e9..99495717c3a 100644 --- a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.rs +++ b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.rs @@ -19,22 +19,22 @@ fn main() { use std::ops::Range; if let Range { start: _, end: _ } = true..true && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` if let Range { start: _, end: _ } = true..true || false { } - //~^ ERROR ambigious use of `||` + //~^ ERROR ambiguous use of `||` while let Range { start: _, end: _ } = true..true && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` while let Range { start: _, end: _ } = true..true || false { } - //~^ ERROR ambigious use of `||` + //~^ ERROR ambiguous use of `||` if let true = false && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` while let true = (1 == 2) && false { } - //~^ ERROR ambigious use of `&&` + //~^ ERROR ambiguous use of `&&` // The following cases are not an error as parenthesis are used to // clarify intent: diff --git a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.stderr b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.stderr index 86ee04747b2..bd49abeb7b2 100644 --- a/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.stderr +++ b/src/test/ui/rfc-2497-if-let-chains/syntax-ambiguity-2018.stderr @@ -1,4 +1,4 @@ -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2018.rs:21:47 | LL | if let Range { start: _, end: _ } = true..true && false { } @@ -7,7 +7,7 @@ LL | if let Range { start: _, end: _ } = true..true && false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `||` +error: ambiguous use of `||` --> $DIR/syntax-ambiguity-2018.rs:24:47 | LL | if let Range { start: _, end: _ } = true..true || false { } @@ -16,7 +16,7 @@ LL | if let Range { start: _, end: _ } = true..true || false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2018.rs:27:50 | LL | while let Range { start: _, end: _ } = true..true && false { } @@ -25,7 +25,7 @@ LL | while let Range { start: _, end: _ } = true..true && false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `||` +error: ambiguous use of `||` --> $DIR/syntax-ambiguity-2018.rs:30:50 | LL | while let Range { start: _, end: _ } = true..true || false { } @@ -34,7 +34,7 @@ LL | while let Range { start: _, end: _ } = true..true || false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2018.rs:33:19 | LL | if let true = false && false { } @@ -43,7 +43,7 @@ LL | if let true = false && false { } = note: this will be a error until the `let_chains` feature is stabilized = note: see rust-lang/rust#53668 for more information -error: ambigious use of `&&` +error: ambiguous use of `&&` --> $DIR/syntax-ambiguity-2018.rs:36:22 | LL | while let true = (1 == 2) && false { } diff --git a/src/test/ui/rust-2018/edition-lint-infer-outlives.fixed b/src/test/ui/rust-2018/edition-lint-infer-outlives.fixed index d70c847e9fe..f13f8ef2bb4 100644 --- a/src/test/ui/rust-2018/edition-lint-infer-outlives.fixed +++ b/src/test/ui/rust-2018/edition-lint-infer-outlives.fixed @@ -24,7 +24,7 @@ use std::fmt::{Debug, Display}; // • one generic parameter (T) bound inline // • one parameter (T) with a where clause // • two parameters (T and U), both bound inline -// • two paramters (T and U), one bound inline, one with a where clause +// • two parameters (T and U), one bound inline, one with a where clause // • two parameters (T and U), both with where clauses // // —and for every permutation of 0, 1, or 2 lifetimes to outlive and 0 or 1 diff --git a/src/test/ui/rust-2018/edition-lint-infer-outlives.rs b/src/test/ui/rust-2018/edition-lint-infer-outlives.rs index 0e4436fe163..f47b3fcb9be 100644 --- a/src/test/ui/rust-2018/edition-lint-infer-outlives.rs +++ b/src/test/ui/rust-2018/edition-lint-infer-outlives.rs @@ -24,7 +24,7 @@ use std::fmt::{Debug, Display}; // • one generic parameter (T) bound inline // • one parameter (T) with a where clause // • two parameters (T and U), both bound inline -// • two paramters (T and U), one bound inline, one with a where clause +// • two parameters (T and U), one bound inline, one with a where clause // • two parameters (T and U), both with where clauses // // —and for every permutation of 0, 1, or 2 lifetimes to outlive and 0 or 1 diff --git a/src/test/ui/specialization/issue-52050.rs b/src/test/ui/specialization/issue-52050.rs index 70cdb4899c4..00d8d126e05 100644 --- a/src/test/ui/specialization/issue-52050.rs +++ b/src/test/ui/specialization/issue-52050.rs @@ -12,7 +12,7 @@ // Regression test for #52050: when inserting the blanket impl `I` // into the tree, we had to replace the child node for `Foo`, which -// led to the struture of the tree being messed up. +// led to the structure of the tree being messed up. use std::iter::Iterator; diff --git a/src/tools/tidy/src/pal.rs b/src/tools/tidy/src/pal.rs index 69a4c09c228..3d5e18e37b0 100644 --- a/src/tools/tidy/src/pal.rs +++ b/src/tools/tidy/src/pal.rs @@ -163,7 +163,7 @@ fn check_cfgs(contents: &mut String, file: &Path, fn find_test_mod(contents: &str) -> usize { if let Some(mod_tests_idx) = contents.find("mod tests") { - // Also capture a previos line indicating "mod tests" in cfg-ed out + // Also capture a previous line indicating "mod tests" in cfg-ed out let prev_newline_idx = contents[..mod_tests_idx].rfind('\n').unwrap_or(mod_tests_idx); let prev_newline_idx = contents[..prev_newline_idx].rfind('\n'); if let Some(nl) = prev_newline_idx { -- cgit 1.4.1-3-g733a5 From 320ec8137e90bf6dd13b62df033372a33f261bb8 Mon Sep 17 00:00:00 2001 From: iirelu Date: Tue, 23 Oct 2018 22:27:02 +0200 Subject: Hopefully fix compile error This was added in the fortnight this PR spent stale. I'm hoping this one-liner fixes it. --- src/libstd/keyword_docs.rs | 1 - 1 file changed, 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 1e801373736..6c95854c66c 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -209,7 +209,6 @@ mod enum_keyword { } /// The mirror use case of FFI is also done via the `extern` keyword: /// /// ```rust -/// # #![allow(private_no_mangle_fns)] /// #[no_mangle] /// pub extern fn callable_from_c(x: i32) -> bool { /// x % 3 == 0 -- cgit 1.4.1-3-g733a5 From 0b82e03a88af4fccfd64a62288a9066cadc2e603 Mon Sep 17 00:00:00 2001 From: OCTronics Date: Fri, 19 Oct 2018 12:00:45 +0200 Subject: Documents `From` implementations for `Stdio` Add a basic summary and an example to From `ChildStdin`, `ChildStdout`, `ChildStderr`, `File` implementations. --- src/libstd/process.rs | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 58ac4e94408..a9219f75362 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1016,6 +1016,28 @@ impl fmt::Debug for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { + /// Converts a `ChildStdin` into a `Stdio` + /// + /// # Examples + /// + /// `ChildStdin` will be converted to `Stdio` using `Stdio::from` under the hood. + /// + /// ```rust + /// use std::process::{Command, Stdio}; + /// + /// let reverse = Command::new("rev") + /// .stdin(Stdio::piped()) + /// .spawn() + /// .expect("failed reverse command"); + /// + /// let _echo = Command::new("echo") + /// .arg("Hello, world!") + /// .stdout(reverse.stdin.unwrap()) // Converted into a Stdio here + /// .output() + /// .expect("failed echo command"); + /// + /// // "!dlrow ,olleH" echoed to console + /// ``` fn from(child: ChildStdin) -> Stdio { Stdio::from_inner(child.into_inner().into()) } @@ -1023,6 +1045,28 @@ impl From for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { + /// Converts a `ChildStdout` into a `Stdio` + /// + /// # Examples + /// + /// `ChildStdout` will be converted to `Stdio` using `Stdio::from` under the hood. + /// + /// ```rust + /// use std::process::{Command, Stdio}; + /// + /// let hello = Command::new("echo") + /// .arg("Hello, world!") + /// .stdout(Stdio::piped()) + /// .spawn() + /// .expect("failed echo command"); + /// + /// let reverse = Command::new("rev") + /// .stdin(hello.stdout.unwrap()) // Converted into a Stdio here + /// .output() + /// .expect("failed reverse command"); + /// + /// assert_eq!(reverse.stdout, b"!dlrow ,olleH\n"); + /// ``` fn from(child: ChildStdout) -> Stdio { Stdio::from_inner(child.into_inner().into()) } @@ -1030,6 +1074,30 @@ impl From for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { + /// Converts a `ChildStderr` into a `Stdio` + /// + /// # Examples + /// + /// ```rust,no_run + /// use std::process::{Command, Stdio}; + /// + /// let reverse = Command::new("rev") + /// .arg("non_existing_file.txt") + /// .stderr(Stdio::piped()) + /// .spawn() + /// .expect("failed reverse command"); + /// + /// let cat = Command::new("cat") + /// .arg("-") + /// .stdin(reverse.stderr.unwrap()) // Converted into a Stdio here + /// .output() + /// .expect("failed echo command"); + /// + /// assert_eq!( + /// String::from_utf8_lossy(&cat.stdout), + /// "rev: cannot open non_existing_file.txt: No such file or directory\n" + /// ); + /// ``` fn from(child: ChildStderr) -> Stdio { Stdio::from_inner(child.into_inner().into()) } @@ -1037,6 +1105,26 @@ impl From for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { + /// Converts a `File` into a `Stdio` + /// + /// # Examples + /// + /// `File` will be converted to `Stdio` using `Stdio::from` under the hood. + /// + /// ```rust,no_run + /// use std::fs::File; + /// use std::process::Command; + /// + /// // With the `foo.txt` file containing `Hello, world!" + /// let file = File::open("foo.txt").unwrap(); + /// + /// let reverse = Command::new("rev") + /// .stdin(file) // Implicit File convertion into a Stdio + /// .output() + /// .expect("failed reverse command"); + /// + /// assert_eq!(reverse.stdout, b"!dlrow ,olleH"); + /// ``` fn from(file: fs::File) -> Stdio { Stdio::from_inner(file.into_inner().into()) } -- cgit 1.4.1-3-g733a5 From 538f65eb617f5d4596cf0d263e48998a70137ce1 Mon Sep 17 00:00:00 2001 From: Raph Levien Date: Wed, 24 Oct 2018 15:19:23 -0700 Subject: Fix doc for new copysign functions Thanks to @LukasKalbertodt for catching this. Addresses a comment raised in #55169 after it was merged. --- src/libstd/f32.rs | 8 ++++---- src/libstd/f64.rs | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/f32.rs b/src/libstd/f32.rs index c3f225d1eb0..7d17aaf2f26 100644 --- a/src/libstd/f32.rs +++ b/src/libstd/f32.rs @@ -198,12 +198,12 @@ impl f32 { } } - /// Returns a number composed of the magnitude of one number and the sign of - /// another. + /// Returns a number composed of the magnitude of `self` and the sign of + /// `y`. /// /// Equal to `self` if the sign of `self` and `y` are the same, otherwise - /// equal to `-y`. If `self` is a `NAN`, then a `NAN` with the sign of `y` - /// is returned. + /// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of + /// `y` is returned. /// /// # Examples /// diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs index da062dda77a..ecaaf8323ab 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -176,12 +176,12 @@ impl f64 { } } - /// Returns a number composed of the magnitude of one number and the sign of - /// another. + /// Returns a number composed of the magnitude of `self` and the sign of + /// `y`. /// /// Equal to `self` if the sign of `self` and `y` are the same, otherwise - /// equal to `-y`. If `self` is a `NAN`, then a `NAN` with the sign of `y` - /// is returned. + /// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of + /// `y` is returned. /// /// # Examples /// -- cgit 1.4.1-3-g733a5