From 4991393eb8081b86a415d153dc2846c399afface Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 5 Jul 2024 21:27:45 +0000 Subject: [PATCH] Make some editorial improvements We've merged PR #1040, so we can remove the TODO and update the link to point to the specific section. We replace some commas with semicolons where that's the right thing to do grammatically. Where we have "an X is... they are...", we replace that with "an X is... Xs are..." for reasons of avoiding a mismatch between the plurality of the pronoun and its referent. We replace "implementing type" and "defining type" with "type being implemented" and "type being defined", since there is in general a difference (e.g. "the driving force" vs "the force being driven"), and these seem more like the latter than the former. There's a place where we had said, "glob imports are allowed to import conflicting names into the same *namespaces*" (emphasis added). It makes sense what this is trying to say by using the plural there. But it just reads better to use the singular, and if it's true for the singular, it's clearly also true to the plural, so we make that change. --- src/items/use-declarations.md | 6 +++--- src/paths.md | 11 +++++------ 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index c17c6f046..397123dc1 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -320,7 +320,7 @@ m!(use std as _;); The following are restrictions for valid `use` declarations. * `use crate;` must use `as` to define the name to bind the crate root to. -* `use {self};` is an error, there must be a leading segment when using `self`. +* `use {self};` is an error; there must be a leading segment when using `self`. * As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. * `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. * `use` paths cannot refer to enum variants through a [type alias]. Example: @@ -338,9 +338,9 @@ The following are restrictions for valid `use` declarations. > **Note**: This section is incomplete. -Some situations are an error when there is an ambiguity as to which name a `use` declaration refers to, when there are two name candidates that do not resolve to the same entity. +Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity. -Glob imports are allowed to import conflicting names in the same namespaces as long as the name is not used or shadowed. +Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used or shadowed. Example: ```rust diff --git a/src/paths.md b/src/paths.md index 26acd489d..b3097dedd 100644 --- a/src/paths.md +++ b/src/paths.md @@ -1,7 +1,7 @@ # Paths A *path* is a sequence of one or more path segments separated by `::` tokens. -They are used to refer to [items], values, [types], [macros], and [attributes]. +Paths are used to refer to [items], values, [types], [macros], and [attributes]. Two examples of simple paths consisting of only identifier segments: @@ -224,13 +224,12 @@ impl S { `Self`, with a capital "S", is used to refer to the current type being implemented or defined. It may be used in the following situations: * In a [trait] definition, it refers to the type implementing the trait. -* In an [implementation], it refers to the implementing type. +* In an [implementation], it refers to the type being implemented. When implementing a tuple or unit [struct], it also refers to the constructor in the [value namespace]. -* In the definition of a [struct], [enumeration], or [union], it refers to the defining type. +* In the definition of a [struct], [enumeration], or [union], it refers to the type being defined. The definition is not allowed to be infinitely recursive (there must be an indirection). -The scope of `Self` behaves similarly to a generic parameter, see the [scopes chapter] for more details. - +The scope of `Self` behaves similarly to a generic parameter; see the [`Self` scope] section for more details. `Self` can only be used as the first segment, without a preceding `::`. The `Self` path cannot include generic arguments (as in `Self::`). @@ -425,6 +424,7 @@ mod without { // crate::without [implementations]: items/implementations.md [use declarations]: items/use-declarations.md [IDENTIFIER]: identifiers.md +[`Self` scope]: names/scopes.md#self-scope [`use`]: items/use-declarations.md [attributes]: attributes.md [enumeration]: items/enumerations.md @@ -435,7 +435,6 @@ mod without { // crate::without [macros]: macros.md [mbe]: macros-by-example.md [patterns]: patterns.md -[scopes chapter]: names/scopes.md [struct]: items/structs.md [trait implementations]: items/implementations.md#trait-implementations [trait]: items/traits.md