From c2aa49b4bebbafdb750a52c598ec3bf8da5a5357 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Sun, 30 Dec 2018 14:28:36 -0800 Subject: [PATCH 01/10] Reorder awkward sentence about generic params to functions --- src/items/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/generics.md b/src/items/generics.md index c86d227bc0235..17e612758543f 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -23,7 +23,7 @@ Functions, type aliases, structs, enumerations, unions, traits and implementations may be *parameterized* by types and lifetimes. These parameters are listed in angle brackets (`<...>`), -usually immediately after and before its definition the name of the item. For +usually immediately after the name of the item and before its definition. For implementations, which don't have a name, they come directly after `impl`. Lifetime parameters must be declared before type parameters. Some examples of items with type and lifetime parameters: From d4a3c3bd637c365c2db243ffec33fc90b4fd0811 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Sun, 30 Dec 2018 14:44:55 -0800 Subject: [PATCH 02/10] Clarify wording describing trait associated item paths --- src/items/implementations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 6e1352ff767f9..38a81a1df1b6a 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -51,7 +51,7 @@ The nominal type is called the _implementing type_ and the associable items are the _associated items_ to the implementing type. Inherent implementations associate the contained items to the implementing type. -The associated item has a path of a path to the implementing type followed by +The path of an associated item consists of a path to the implementing type followed by the associate item's path component. Inherent implementations cannot contain associated type aliases. From 693a91aeb7975db6471018a50d24b2e008feae5c Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Sun, 30 Dec 2018 21:12:11 -0800 Subject: [PATCH 03/10] Add an example and more explanation about associate item paths --- src/items/implementations.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 38a81a1df1b6a..c2dc790f5d6e6 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -51,10 +51,36 @@ The nominal type is called the _implementing type_ and the associable items are the _associated items_ to the implementing type. Inherent implementations associate the contained items to the implementing type. -The path of an associated item consists of a path to the implementing type followed by +The path to an associated item is: any path to the implementing type followed by the associate item's path component. Inherent implementations cannot contain associated type aliases. +Note that the path to the module containing the inherent +implementation does not allow access to the associate item, unless the +implementing type is re-exported from the same location. + +``` rust +pub mod color { + pub struct Color(pub u8, pub u8, pub u8); +} + +mod values { + use super::color::Color; + impl Color { + pub fn red() -> Color { + Color(255, 0, 0) + } + } +} + +pub use self::color::Color; +fn main() { + color::Color::red(); // actual path to the implementing type + Color::red(); // rexported paths to the implementing type also work + // bright_theme::Color::red(); // Does not work, because use in `theme` is not pub +} +``` + A type can also have multiple inherent implementations. An implementing type must be defined within the same crate as the original type definition. From 24b514e35f94818a13ff4592a54f183e3d517de7 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Sun, 30 Dec 2018 21:21:25 -0800 Subject: [PATCH 04/10] Expand on what can be associate items (with links) --- src/items/implementations.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index c2dc790f5d6e6..dcbcd303b2e9c 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -50,10 +50,18 @@ bracketed set of associable items. The nominal type is called the _implementing type_ and the associable items are the _associated items_ to the implementing type. -Inherent implementations associate the contained items to the implementing type. -The path to an associated item is: any path to the implementing type followed by -the associate item's path component. Inherent implementations cannot contain -associated type aliases. +Inherent implementations associate the contained items to the +implementing type. Inherent implementations can contain [associated +functions] (including methods), [associated types], and [associated +constants]. They cannot contain associated type aliases. + +[associated functions]: associated-items.html#associated-functions-and-methods +[associated types]: associated-items.html#associated-types +[associated constants]: associated-items.html#associated-constants + +The path to an associated item is: any path to the implementing type, +followed by the path to the associate item within the inherent +implementation. Note that the path to the module containing the inherent implementation does not allow access to the associate item, unless the From 71d16ebfb1606f1f0085818d74ffb8807996fb2b Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Mon, 31 Dec 2018 08:58:27 -0800 Subject: [PATCH 05/10] Incorporate PR feedback --- src/items/implementations.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index dcbcd303b2e9c..a5eb96881417e 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -52,24 +52,20 @@ the _associated items_ to the implementing type. Inherent implementations associate the contained items to the implementing type. Inherent implementations can contain [associated -functions] (including methods), [associated types], and [associated -constants]. They cannot contain associated type aliases. +functions] (including methods) and [associated constants]. They cannot +contain associated type aliases. -[associated functions]: associated-items.html#associated-functions-and-methods -[associated types]: associated-items.html#associated-types -[associated constants]: associated-items.html#associated-constants - -The path to an associated item is: any path to the implementing type, +The [path] to an associated item is: any path to the implementing type, followed by the path to the associate item within the inherent implementation. -Note that the path to the module containing the inherent -implementation does not allow access to the associate item, unless the -implementing type is re-exported from the same location. - ``` rust pub mod color { pub struct Color(pub u8, pub u8, pub u8); + + impl Color { + pub const WHITE: Color = Color(255, 255, 255); + } } mod values { @@ -83,9 +79,10 @@ mod values { pub use self::color::Color; fn main() { - color::Color::red(); // actual path to the implementing type + color::Color::WHITE; // actual path to the implementing type and impl in the same module + color::Color::red(); // impl blocks in different modules are still accessed through a path to the type Color::red(); // rexported paths to the implementing type also work - // bright_theme::Color::red(); // Does not work, because use in `theme` is not pub + // values::Color::red(); // Does not work, because use in `values` is not pub } ``` @@ -225,9 +222,12 @@ attributes]. [_Visibility_]: visibility-and-privacy.html [_WhereClause_]: items/generics.html#where-clauses [trait]: items/traits.html +[associated functions]: associated-items.html#associated-functions-and-methods +[associated constants]: associated-items.html#associated-constants [attributes]: attributes.html [`cfg`]: conditional-compilation.html [`deprecated`]: attributes.html#deprecation [`doc`]: attributes.html#documentation +[path]: paths.html [the lint check attributes]: attributes.html#lint-check-attributes [Unsafe traits]: items/traits.html#unsafe-traits From d9281b8165f7bb1712e2be2d2c93136e6c7abe88 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Mon, 31 Dec 2018 09:02:24 -0800 Subject: [PATCH 06/10] Remove old smaller code example and group all prose --- src/items/implementations.md | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index a5eb96881417e..8b8b7e4b61ed0 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -59,6 +59,9 @@ The [path] to an associated item is: any path to the implementing type, followed by the path to the associate item within the inherent implementation. +A type can also have multiple inherent implementations. An implementing type +must be defined within the same crate as the original type definition. + ``` rust pub mod color { pub struct Color(pub u8, pub u8, pub u8); @@ -86,22 +89,6 @@ fn main() { } ``` -A type can also have multiple inherent implementations. An implementing type -must be defined within the same crate as the original type definition. - -```rust -struct Point {x: i32, y: i32} - -impl Point { - fn log(&self) { - println!("Point is at ({}, {})", self.x, self.y); - } -} - -let my_point = Point {x: 10, y:11}; -my_point.log(); -``` - ## Trait Implementations A _trait implementation_ is defined like an inherent implementation except that From f91d94a3231d81f725a62864ecd822a5de276f23 Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Tue, 1 Jan 2019 13:37:57 -0800 Subject: [PATCH 07/10] Remove unneeded "an" --- src/items/generics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/generics.md b/src/items/generics.md index 17e612758543f..39303ae507148 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -57,7 +57,7 @@ referred to with path syntax. > _ForLifetimes_ :\ >    `for` `<` [_LifetimeParams_](#type-and-lifetime-parameters) `>` -*Where clauses* provide an another way to specify bounds on type and lifetime +*Where clauses* provide another way to specify bounds on type and lifetime parameters as well as a way to specify bounds on types that aren't type parameters. From 79ca06003bc627f55a2c84f06e6379982bc9ef7e Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Thu, 21 Feb 2019 10:28:05 -0800 Subject: [PATCH 08/10] Improve structure of path description sentence --- src/items/implementations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 8b8b7e4b61ed0..1e7f493490b11 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -55,9 +55,9 @@ implementing type. Inherent implementations can contain [associated functions] (including methods) and [associated constants]. They cannot contain associated type aliases. -The [path] to an associated item is: any path to the implementing type, -followed by the path to the associate item within the inherent -implementation. +The [path] to an associated item has the following structure: any path +to the implementing type, followed by the type path to the associate item +within the inherent implementation. A type can also have multiple inherent implementations. An implementing type must be defined within the same crate as the original type definition. From e641c6f0976c26a9da58fa7b6ed747888db8136d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 22 Feb 2019 01:23:11 -0800 Subject: [PATCH 09/10] Apply suggestions from review feedback Co-Authored-By: Geoff Shannon --- src/items/implementations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 1e7f493490b11..5df8750d02b90 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -55,9 +55,9 @@ implementing type. Inherent implementations can contain [associated functions] (including methods) and [associated constants]. They cannot contain associated type aliases. -The [path] to an associated item has the following structure: any path -to the implementing type, followed by the type path to the associate item -within the inherent implementation. +The [path] to an associated item is any path to the implementing type, +followed by the associated item's identifier as the final path +component. A type can also have multiple inherent implementations. An implementing type must be defined within the same crate as the original type definition. @@ -209,8 +209,8 @@ attributes]. [_Visibility_]: visibility-and-privacy.html [_WhereClause_]: items/generics.html#where-clauses [trait]: items/traits.html -[associated functions]: associated-items.html#associated-functions-and-methods -[associated constants]: associated-items.html#associated-constants +[associated functions]: items/associated-items.html#associated-functions-and-methods +[associated constants]: items/associated-items.html#associated-constants [attributes]: attributes.html [`cfg`]: conditional-compilation.html [`deprecated`]: attributes.html#deprecation From 83cb5606fde408b0a9bb4f1eadd384d644a4d5fe Mon Sep 17 00:00:00 2001 From: Geoff Shannon Date: Fri, 22 Feb 2019 01:24:12 -0800 Subject: [PATCH 10/10] Reformat doc comments for less width --- src/items/implementations.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/items/implementations.md b/src/items/implementations.md index 5df8750d02b90..8d6df033a7cc8 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -82,10 +82,17 @@ mod values { pub use self::color::Color; fn main() { - color::Color::WHITE; // actual path to the implementing type and impl in the same module - color::Color::red(); // impl blocks in different modules are still accessed through a path to the type - Color::red(); // rexported paths to the implementing type also work - // values::Color::red(); // Does not work, because use in `values` is not pub + // Actual path to the implementing type and impl in the same module. + color::Color::WHITE; + + // Impl blocks in different modules are still accessed through a path to the type. + color::Color::red(); + + // Re-exported paths to the implementing type also work. + Color::red(); + + // Does not work, because use in `values` is not pub. + // values::Color::red(); } ```