Add "scopes" chapter. #1040

ehuss · 2021-06-04T12:09:01Z

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

JohnTitor

Overall LGTM 👍

src/names/scopes.md

ehuss · 2021-06-21T13:25:16Z

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

src/names/scopes.md

petrochenkov · 2022-05-03T21:47:08Z

src/items.md

-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].


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

petrochenkov · 2022-05-03T21:49:03Z

src/items.md

-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].


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).

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

src/names/scopes.md

petrochenkov · 2022-05-03T22:04:37Z

src/names/scopes.md

+{}
+```
+
+Generic scopes do not extend into [items] declared inside a function.


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.

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

Generic names do not extend into an inner item. Using a parent name will be a "name not found" error.

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.

petrochenkov · 2022-05-03T22:09:21Z

src/names/scopes.md

+### 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.


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.

I reworded this a bit.

petrochenkov · 2022-05-03T22:10:21Z

src/names/scopes.md

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


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.

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

petrochenkov · 2022-05-03T22:14:34Z

src/names/scopes.md

+'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 } {


Fascinating.

petrochenkov · 2022-05-03T22:19:13Z

src/names/scopes.md

+
+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.


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.

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 · 2022-05-07T19:24:48Z

Thanks for the reviews!

Improve labeled blocks documentation

Relax ordering rules for `asm!` operands

"struct expressions can be in used in these situations" => "struct expressions can be used in these situations"

redundant word removed

Fix coding style in example: add space between module name and bracket

Explain typos in `asm!` can be unsound

Document how `non_exhaustive` interacts with tuple and unit-like structs.

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

See also rust-lang/rust#37854.

…atterns patterns: include yet unstable exclusive range patterns

Document inline const/const block expression

…ocks

document guarantee about evaluation of associated consts and const blocks

update patterns.md for const pattern RFC

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)

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)

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 force-pushed the scopes branch from bb0e095 to 9f5694b Compare June 4, 2021 12:11

JohnTitor approved these changes Jun 21, 2021

View reviewed changes

src/names/scopes.md Outdated Show resolved Hide resolved

ehuss force-pushed the scopes branch from 2583397 to e704aaa Compare July 1, 2021 00:41

ehuss force-pushed the scopes branch from e704aaa to 8a00bdc Compare January 17, 2022 14:44

carols10cents mentioned this pull request Mar 27, 2022

'use' declarations are private to the containing *scope*, not *module* #1187

Open

ehuss mentioned this pull request May 3, 2022

Remove label/lifetime shadowing warnings rust-lang/rust#96296

Merged

jyn514 reviewed May 3, 2022

View reviewed changes

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

petrochenkov reviewed May 3, 2022

View reviewed changes

ehuss force-pushed the scopes branch from 8a00bdc to 91ce054 Compare May 7, 2022 19:24

ehuss force-pushed the scopes branch from 91ce054 to fe9eec6 Compare June 3, 2022 22:00

ehuss and others added 18 commits March 20, 2023 13:51

Merge pull request rust-lang#1342 from est31/labeled_blocks

76f771b

Improve labeled blocks documentation

Merge pull request rust-lang#1323 from Amanieu/asm-order

3c47807

Relax ordering rules for `asm!` operands

Explain typos in asm! can be unsound

0a89373

redundant word removed

6e6e8b4

"struct expressions can be in used in these situations" => "struct expressions can be used in these situations"

Merge pull request rust-lang#1346 from sam-zheng/patch-1

fcc12c7

redundant word removed

Remove note about raw-dylib being unstable on x86 Windows

f0bb14c

Fix coding style: add space between module name and bracket

fc61be0

Merge pull request rust-lang#1347 from n-eq/patch-1

5c328ef

Fix coding style in example: add space between module name and bracket

Move Correctness and Validity section

aba56b9

Merge pull request rust-lang#1344 from workingjubilee/patch-1

1f8dc72

Explain typos in `asm!` can be unsound

first pass for debugger_visualizer docs

2749bce

move to debugger page, modify style

ed69dfa

add line

e6f6ce8

add details for GDB auto-load

8db722e

fix style errors

2d45187

fix broken link

5784e53

fix rustdoc failures

c3be903

address pr comments

1c56d59

ehuss and others added 20 commits April 15, 2024 19:59

Merge pull request rust-lang#1491 from kpreid/neunit

585b9bc

Document how `non_exhaustive` interacts with tuple and unit-like structs.

Update clone reference to include closures

4f47e3f

Clone: Also mention closures that don't capture anything

330ef95

Merge pull request rust-lang#1492 from conradludgate/patch-1

735c5db

Update clone reference to include closures

Merge pull request rust-lang#1493 from kpreid/patch-1

5e68de3

Expand and clarify primitive alignment

Merge pull request rust-lang#1420 from daxpedda/wasm-target-feature-p…

5854fcc

…hase-4-5 Stabilize Wasm target features that are in phase 4 and 5

Add an example of collapse_debuginfo

2d51a2a

Merge pull request rust-lang#1468 from petrochenkov/debmac

5181795

Add docs for `#[collapse_debuginfo]` attribute

Add const blocks

01c8196

mention associated consts

c6719b5

clarifications

2f63507

patterns: include new exclusive range patterns

95ab920

See also rust-lang/rust#37854.

Merge pull request rust-lang#1484 from MultisampledNight/excl-range-p…

5e8b3f6

…atterns patterns: include yet unstable exclusive range patterns

Small editorial updates for const blocks.

efdc9b6

Merge pull request rust-lang#1295 from nbdd0121/master

e356977

Document inline const/const block expression

document guarantee about evaluation of associated consts and const bl…

d33e4b0

…ocks

Merge pull request rust-lang#1497 from RalfJung/const-eval-guarantee

1bf2cdc

document guarantee about evaluation of associated consts and const blocks

Merge pull request rust-lang#1456 from RalfJung/const-pattern

0e07fc5

update patterns.md for const pattern RFC

Merge PR rust-lang#1040: Add "scopes" chapter

8251778

traviscross approved these changes May 28, 2024

View reviewed changes

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

rustbot mentioned this pull request Jun 3, 2024

Update books rust-lang/rust#125933

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add "scopes" chapter. #1040

Add "scopes" chapter. #1040

ehuss commented Jun 4, 2021 •

edited

Loading

JohnTitor left a comment

ehuss commented Jun 21, 2021

petrochenkov May 3, 2022

petrochenkov May 3, 2022

ehuss May 7, 2022

petrochenkov May 3, 2022

ehuss May 7, 2022

petrochenkov May 3, 2022

ehuss May 7, 2022

petrochenkov May 3, 2022

ehuss May 7, 2022

petrochenkov May 3, 2022

petrochenkov May 3, 2022

ehuss May 7, 2022

ehuss commented May 7, 2022

	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].

Add "scopes" chapter. #1040

Add "scopes" chapter. #1040

Conversation

ehuss commented Jun 4, 2021 • edited Loading

JohnTitor left a comment

Choose a reason for hiding this comment

ehuss commented Jun 21, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss commented May 7, 2022

ehuss commented Jun 4, 2021 •

edited

Loading