Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "scopes" chapter. #1040

Merged
merged 472 commits into from
May 28, 2024
Merged

Add "scopes" chapter. #1040

merged 472 commits into from
May 28, 2024

Conversation

ehuss
Copy link
Contributor

@ehuss ehuss commented Jun 4, 2021

This adds the chapter on scopes.

I tried to make this accurate and complete, but it is probably neither. There are some things that are intentionally not covered, such as some ambiguities (will handle in other places or at a later date), peculiarities with macros (perhaps deferred for more explicit "expansion" docs?), details regarding use (will add to use chapter), and known bugs (hopefully they will get fixed some day).

cc #568

Copy link
Member

@JohnTitor JohnTitor left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall LGTM 👍

src/names/scopes.md Outdated Show resolved Hide resolved
@ehuss
Copy link
Contributor Author

ehuss commented Jun 21, 2021

@petrochenkov Is this something you could potentially review/look over?

src/names/scopes.md Outdated Show resolved Hide resolved
src/names/scopes.md Show resolved Hide resolved
src/names/scopes.md Show resolved Hide resolved
src/items.md Outdated
item (in the case of functions). The grammar specifies the exact locations in
which sub-item declarations may appear.
Items may be declared in the [root of the crate], a [module][modules], or a [statement].
Additionally, a subset of items, called [associated items], may be declared in [traits] and [implementations].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, a subset of items, called foreign items, may be declared in extern blocks.

src/items.md Outdated
qualified by the name of the enclosing item, or is private to the enclosing
item (in the case of functions). The grammar specifies the exact locations in
which sub-item declarations may appear.
Items may be declared in the [root of the crate], a [module][modules], or a [statement].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Items may be declared in the [root of the crate], a [module][modules], or a [statement].
Items may be declared in the [root of the crate], a [module][modules], or a block [statement].

?

"declared in a statement" would be a weird wording.
An item is either a statement itself, or lives in a block statement (or other similar thing like a function body).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, that was a bit awkward. I switched to a block expression.

src/names/scopes.md Outdated Show resolved Hide resolved
{}
```

Generic scopes do not extend into [items] declared inside a function.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is kind of a philosophical question, but they do extend (*), it's just an error to use a parameter from an outer item.

(*) until a mod item is encountered, which is a true barrier for names.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems to be an implementation choice, though? Like, the choice is:

  1. Generic names do not extend into an inner item. Using a parent name will be a "name not found" error.
  2. Generic names do extend into an inner item, but can be shadowed. Using a parent name without shadowing it will be a "can't use generic parameter from outer function" error.

I felt like the first approach was a little easier to explain, even if that's not how rustc works (which I see as just a way to provide better errors, or maybe just easier to implement).

That being said, I reworded it to say it is an error.

### Generic parameter shadowing

It is an error to shadow a generic parameter.
Items declared within functions are allowed to reuse generic parameter names from the function because generic scopes do not extend to inner items.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The motivation after "because" is artificial.
This is allowed because shadowing of names is allowed in general, items in inner scopes can shadow items from outer scopes, et cetera.

The restrictions on generic parameters that appear in some cases are exceptions.
They exist for historical reasons, but technically nothing prevents removing them at any moment.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reworded this a bit.

```rust,compile_fail
trait SomeTrait<'a> {
fn example<'a>() {} // ERROR: 'a is already in scope
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to add type and const parameters to these examples.
I'm not actually sure that the rules here are enforced consistently for all of them.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not aware of any inconsistent rules, but if any come to mind, let me know.

'a: for outer in 0..5 {
// This will break the outer loop, skipping the inner loop and stopping
// the outer loop.
'a: for inner in { break 'a; 0..1 } {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fascinating.


The implicit `Self` type in the definition of a [struct], [enum], [union], [trait], or [implementation] is treated similarly to a [generic parameter](#generic-parameter-scopes), and is in scope in the same way as a generic type parameter.
For structs, enums, and unions, it is in scope starting after the generic parameters.
For traits and implementations, it is in scope starting just before the generic parameters.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that this difference is not a bug.
The original implementation of Self is for traits and impls, and it is certainly correct.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I made a mistake here, I'm not sure what I was thinking at the time. Perhaps I got confused by this code, but based on this I'm almost certain that struct/enum/union have the same behavior as traits and impls.

struct S<T: Into<Self>> { // OK
    f1: T,
}

I have pushed an update, does that seem correct?

@ehuss
Copy link
Contributor Author

ehuss commented May 7, 2022

Thanks for the reviews!

conradludgate and others added 19 commits April 16, 2024 06:55
These changes are intended to make the section more informative and readable, without making any new normative claims.

* Specify that the alignment might be _less_ than the size, rather than just that it might be different. This is mandatory and stated in the previous section, but I think it's useful to reiterate here.
* Mention `u128`/`i128` as another example of alignment less than size, so that this doesn't sound like a mainly 32-bit thing.
* Add `usize`/`isize` to the size table, so it can be spotted at a glance.
Update clone reference to include closures
Expand and clarify primitive alignment
…hase-4-5

Stabilize Wasm target features that are in phase 4 and 5
Add docs for `#[collapse_debuginfo]` attribute
…atterns

patterns: include yet unstable exclusive range patterns
Document inline const/const block expression
document guarantee about evaluation of associated consts and const blocks
update patterns.md for const pattern RFC
@traviscross traviscross added this pull request to the merge queue May 28, 2024
Merged via the queue into rust-lang:master with commit 02674ce May 28, 2024
1 check passed
compiler-errors added a commit to compiler-errors/rust that referenced this pull request Jun 4, 2024
Update books

## rust-lang/book

6 commits in 85442a608426d3667f1c9458ad457b241a36b569..5228bfac8267ad24659a81b92ec5417976b5edbc
2024-05-29 20:55:49 UTC to 2024-05-27 17:22:03 UTC

- Fix typo in ch10-03 (rust-lang/book#3539)
- Backport changes to ch 9 and 10 (rust-lang/book#3946)
- infra: correctly support preprocessors for nostarch (rust-lang/book#3944)
- Use `<kbd>` instead of `<span class="keystroke">` (rust-lang/book#3945)
- infra: Fix clippy warning in remove_markup (rust-lang/book#3943)
- fix: ch10-03 - misleading use of expect on .split (rust-lang/book#3939)

## rust-lang/edition-guide

2 commits in 0c68e90acaae5a611f8f5098a3c2980de9845ab2..bbaabbe088e21a81a0d9ae6757705020d5d7b416
2024-05-24 19:07:18 UTC to 2024-05-21 22:40:52 UTC

- 2024: Document reserving `gen` keyword (rust-lang/edition-guide#300)
- 2024: Document cargo changes (rust-lang/edition-guide#301)

## rust-embedded/book

1 commits in dd962bb82865a5284f2404e5234f1e3222b9c022..b10c6acaf0f43481f6600e95d4b5013446e29f7a
2024-05-31 08:51:50 UTC to 2024-05-31 08:51:50 UTC

- Add some explanations as to why exception re-entrancy may still be an issue in a multicore-environment. (rust-embedded/book#367)

## rust-lang/reference

6 commits in e356977fceaa8591c762312d8d446769166d4b3e..6019b76f5b28938565b251bbba0bf5cc5c43d863
2024-06-03 15:58:57 UTC to 2024-05-25 18:35:54 UTC

- Add Apple `target_abi` values to the example values (rust-lang/reference#1507)
- this needs a space (rust-lang/reference#1506)
- Mention Variadics With No Fixed Parameter (rust-lang/reference#1494)
- Add "scopes" chapter. (rust-lang/reference#1040)
- update patterns.md for const pattern RFC (rust-lang/reference#1456)
- document guarantee about evaluation of associated consts and const blocks (rust-lang/reference#1497)

## rust-lang/rust-by-example

3 commits in 20482893d1a502df72f76762c97aed88854cdf81..4840dca06cadf48b305d3ce0aeafde7f80933f80
2024-05-28 13:56:12 UTC to 2024-05-27 11:51:10 UTC

- Update mdbook-i18n-helpers to 0.3.3 (rust-lang/rust-by-example#1857)
- Fix CI failure (rust-lang/rust-by-example#1856)
- Add precision on From/Into asymmetry to from_into.md (rust-lang/rust-by-example#1855)

## rust-lang/rustc-dev-guide

4 commits in b6d4a4940bab85cc91eec70cc2e3096dd48da62d..6a7374bd87cbac0f8be4fd4877d8186d9c313985
2024-05-31 00:27:28 UTC to 2024-05-21 09:56:12 UTC

- Flesh out the "representing types" chapter (rust-lang/rustc-dev-guide#1985)
- sync the stage0 filename (rust-lang/rustc-dev-guide#1979)
- Add Rust for Linux notification group entry (rust-lang/rustc-dev-guide#1984)
- fix some typos (rust-lang/rustc-dev-guide#1983)
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Jun 4, 2024
Update books

## rust-lang/book

6 commits in 85442a608426d3667f1c9458ad457b241a36b569..5228bfac8267ad24659a81b92ec5417976b5edbc
2024-05-29 20:55:49 UTC to 2024-05-27 17:22:03 UTC

- Fix typo in ch10-03 (rust-lang/book#3539)
- Backport changes to ch 9 and 10 (rust-lang/book#3946)
- infra: correctly support preprocessors for nostarch (rust-lang/book#3944)
- Use `<kbd>` instead of `<span class="keystroke">` (rust-lang/book#3945)
- infra: Fix clippy warning in remove_markup (rust-lang/book#3943)
- fix: ch10-03 - misleading use of expect on .split (rust-lang/book#3939)

## rust-lang/edition-guide

2 commits in 0c68e90acaae5a611f8f5098a3c2980de9845ab2..bbaabbe088e21a81a0d9ae6757705020d5d7b416
2024-05-24 19:07:18 UTC to 2024-05-21 22:40:52 UTC

- 2024: Document reserving `gen` keyword (rust-lang/edition-guide#300)
- 2024: Document cargo changes (rust-lang/edition-guide#301)

## rust-embedded/book

1 commits in dd962bb82865a5284f2404e5234f1e3222b9c022..b10c6acaf0f43481f6600e95d4b5013446e29f7a
2024-05-31 08:51:50 UTC to 2024-05-31 08:51:50 UTC

- Add some explanations as to why exception re-entrancy may still be an issue in a multicore-environment. (rust-embedded/book#367)

## rust-lang/reference

6 commits in e356977fceaa8591c762312d8d446769166d4b3e..6019b76f5b28938565b251bbba0bf5cc5c43d863
2024-06-03 15:58:57 UTC to 2024-05-25 18:35:54 UTC

- Add Apple `target_abi` values to the example values (rust-lang/reference#1507)
- this needs a space (rust-lang/reference#1506)
- Mention Variadics With No Fixed Parameter (rust-lang/reference#1494)
- Add "scopes" chapter. (rust-lang/reference#1040)
- update patterns.md for const pattern RFC (rust-lang/reference#1456)
- document guarantee about evaluation of associated consts and const blocks (rust-lang/reference#1497)

## rust-lang/rust-by-example

3 commits in 20482893d1a502df72f76762c97aed88854cdf81..4840dca06cadf48b305d3ce0aeafde7f80933f80
2024-05-28 13:56:12 UTC to 2024-05-27 11:51:10 UTC

- Update mdbook-i18n-helpers to 0.3.3 (rust-lang/rust-by-example#1857)
- Fix CI failure (rust-lang/rust-by-example#1856)
- Add precision on From/Into asymmetry to from_into.md (rust-lang/rust-by-example#1855)

## rust-lang/rustc-dev-guide

4 commits in b6d4a4940bab85cc91eec70cc2e3096dd48da62d..6a7374bd87cbac0f8be4fd4877d8186d9c313985
2024-05-31 00:27:28 UTC to 2024-05-21 09:56:12 UTC

- Flesh out the "representing types" chapter (rust-lang/rustc-dev-guide#1985)
- sync the stage0 filename (rust-lang/rustc-dev-guide#1979)
- Add Rust for Linux notification group entry (rust-lang/rustc-dev-guide#1984)
- fix some typos (rust-lang/rustc-dev-guide#1983)
rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Jun 4, 2024
Rollup merge of rust-lang#125933 - rustbot:docs-update, r=ehuss

Update books

## rust-lang/book

6 commits in 85442a608426d3667f1c9458ad457b241a36b569..5228bfac8267ad24659a81b92ec5417976b5edbc
2024-05-29 20:55:49 UTC to 2024-05-27 17:22:03 UTC

- Fix typo in ch10-03 (rust-lang/book#3539)
- Backport changes to ch 9 and 10 (rust-lang/book#3946)
- infra: correctly support preprocessors for nostarch (rust-lang/book#3944)
- Use `<kbd>` instead of `<span class="keystroke">` (rust-lang/book#3945)
- infra: Fix clippy warning in remove_markup (rust-lang/book#3943)
- fix: ch10-03 - misleading use of expect on .split (rust-lang/book#3939)

## rust-lang/edition-guide

2 commits in 0c68e90acaae5a611f8f5098a3c2980de9845ab2..bbaabbe088e21a81a0d9ae6757705020d5d7b416
2024-05-24 19:07:18 UTC to 2024-05-21 22:40:52 UTC

- 2024: Document reserving `gen` keyword (rust-lang/edition-guide#300)
- 2024: Document cargo changes (rust-lang/edition-guide#301)

## rust-embedded/book

1 commits in dd962bb82865a5284f2404e5234f1e3222b9c022..b10c6acaf0f43481f6600e95d4b5013446e29f7a
2024-05-31 08:51:50 UTC to 2024-05-31 08:51:50 UTC

- Add some explanations as to why exception re-entrancy may still be an issue in a multicore-environment. (rust-embedded/book#367)

## rust-lang/reference

6 commits in e356977fceaa8591c762312d8d446769166d4b3e..6019b76f5b28938565b251bbba0bf5cc5c43d863
2024-06-03 15:58:57 UTC to 2024-05-25 18:35:54 UTC

- Add Apple `target_abi` values to the example values (rust-lang/reference#1507)
- this needs a space (rust-lang/reference#1506)
- Mention Variadics With No Fixed Parameter (rust-lang/reference#1494)
- Add "scopes" chapter. (rust-lang/reference#1040)
- update patterns.md for const pattern RFC (rust-lang/reference#1456)
- document guarantee about evaluation of associated consts and const blocks (rust-lang/reference#1497)

## rust-lang/rust-by-example

3 commits in 20482893d1a502df72f76762c97aed88854cdf81..4840dca06cadf48b305d3ce0aeafde7f80933f80
2024-05-28 13:56:12 UTC to 2024-05-27 11:51:10 UTC

- Update mdbook-i18n-helpers to 0.3.3 (rust-lang/rust-by-example#1857)
- Fix CI failure (rust-lang/rust-by-example#1856)
- Add precision on From/Into asymmetry to from_into.md (rust-lang/rust-by-example#1855)

## rust-lang/rustc-dev-guide

4 commits in b6d4a4940bab85cc91eec70cc2e3096dd48da62d..6a7374bd87cbac0f8be4fd4877d8186d9c313985
2024-05-31 00:27:28 UTC to 2024-05-21 09:56:12 UTC

- Flesh out the "representing types" chapter (rust-lang/rustc-dev-guide#1985)
- sync the stage0 filename (rust-lang/rustc-dev-guide#1979)
- Add Rust for Linux notification group entry (rust-lang/rustc-dev-guide#1984)
- fix some typos (rust-lang/rustc-dev-guide#1983)
traviscross added a commit to ehuss/reference that referenced this pull request Jul 5, 2024
We've merged PR rust-lang#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.
traviscross added a commit to ehuss/reference that referenced this pull request Jul 9, 2024
We've merged PR rust-lang#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.
ehuss pushed a commit to ehuss/reference that referenced this pull request Jul 25, 2024
We've merged PR rust-lang#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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.