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

Document label_break_value in the reference #1263

Merged
merged 2 commits into from
Oct 4, 2022

Conversation

jyn514
Copy link
Member

@jyn514 jyn514 commented Sep 6, 2022

r? @ehuss

@nbdd0121
Copy link
Contributor

nbdd0121 commented Sep 6, 2022

Shouldn't this be called labelled block expression instead of labelled break expression?

@ciphergoth
Copy link

Is this really a loop expression? It doesn't loop.

@Havvy
Copy link
Contributor

Havvy commented Sep 7, 2022

I take it that it is documented in loop expressions because it can only be used in loop expression context. Which I think is wrong. I don't see label-break-value as introducing a new kind of expression but rather modifies the semantics of just a block expression and break expressions. If I'm not too tired, I think I might create a competing pull request with how I think it should be documented; explaining it fully would be too much work.

Also, please oh please don't call this a labeled expression if we end up keeping this as its own expression kind. At least call it a labeled block expression or something.

@Havvy
Copy link
Contributor

Havvy commented Sep 8, 2022

I, uh, didn't write the PR today. I did think about perspectives some more, and now there's too many perspectives in my head. I wrote about them at https://rust-lang.zulipchat.com/#narrow/stream/237824-t-lang.2Fdoc/topic/Perspectives.20on.20Break.20Label.20Value

@Havvy Havvy added New Content Missing features or aspects of language not currently documented. RFC Stabilization Docs Documentation required for stabilizing a feature A-expressions Area: Expressions I-lang-nominated labels Sep 8, 2022
@Havvy
Copy link
Contributor

Havvy commented Sep 8, 2022

I'm nominating this issue as per the question raised on Zulip.

Copy link
Contributor

@ehuss ehuss left a comment

Choose a reason for hiding this comment

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

Thanks for posting this!

Posting a review now, though I know @Havvy was interested in exploring other options. Feel free to ignore until there is more consensus on how to approach this.

src/expressions/loop-expr.md Outdated Show resolved Hide resolved
src/expressions/loop-expr.md Outdated Show resolved Hide resolved
src/expressions/loop-expr.md Outdated Show resolved Hide resolved
@nikomatsakis
Copy link
Contributor

nikomatsakis commented Sep 13, 2022

My two cents--

I think the approach in this PR seems fine, but I think we should have a link from wherever blocks are documented saying "labeled blocks are described under the loop section".

It's not clear that it's the best approach (if there is such a thing).

@jyn514
Copy link
Member Author

jyn514 commented Sep 14, 2022

I tried to address @ehuss and @nikomatsakis's concerns. I renamed "label expression" to "label block expression".

@pnkfelix
Copy link
Member

pnkfelix commented Sep 20, 2022

@jyn514 It want to echo the comments of others that it feels really weird to document labelled blocks in a section named "Loop expressions"

Could we rename the "Loop expressions" chapter to something that doesn't indirectly imply that a labelled block somehow is a looping construct?

E.g. "Loop expressions and non-local jumps" or "Loop expressions and non-local control flow"? (Or even just "Non-local control flow" or "Complex control flow expressions"?)

@nbdd0121
Copy link
Contributor

Or "breakable expressions"?

@pnkfelix
Copy link
Member

pnkfelix commented Sep 20, 2022

I like "Loops and breakable expressions", that rolls off the tongue nicely.

("Loops and labelled block expressions" would also be fine, but I think "breakable expressions" jumps out with the purpose of the concept more immediately.)

I would also be happy with "Loops and other breakable expressions", to try to indicate why these things are in the same section.

@jyn514
Copy link
Member Author

jyn514 commented Sep 23, 2022

I don't have objections to @pnkfelix's suggestion, but I don't know when I'll have time to apply them. Happy for someone else to push to my branch.

@pnkfelix
Copy link
Member

Happy for someone else to push to my branch.

Done!

@pnkfelix pnkfelix self-requested a review October 4, 2022 18:46
@pnkfelix pnkfelix merged commit d6864a4 into rust-lang:master Oct 4, 2022
@jyn514 jyn514 deleted the label-break-value branch October 4, 2022 18:47
Dylan-DPC added a commit to Dylan-DPC/rust that referenced this pull request Oct 12, 2022
Update books

## nomicon

1 commits in f53bfa056929217870a5d2df1366d2e7ba35096d..9c73283775466d22208a0b28afcab44db4c0cc10
2022-09-05 07:19:02 -0700 to 2022-09-30 07:31:22 +0900
- Fix typo (rust-lang/nomicon#380)

## reference

9 commits in a7cdac33ca7356ad49d5c2b5e2c5010889b33eee..f6ed74f582bddcec73f753eafaab3749c4f7df61
2022-09-19 17:39:58 -0700 to 2022-10-08 02:43:26 -0700
- Typo 'a' -> 'an' (rust-lang/reference#1280)
- One line one sentence for expressions and statements main chapters (rust-lang/reference#1277)
- Document let else statements (rust-lang/reference#1156)
- Document `label_break_value` in the reference (rust-lang/reference#1263)
- Document target_has_atomic (rust-lang/reference#1171)
- update 'unsafe' (rust-lang/reference#1278)
- Update tokens.md (rust-lang/reference#1276)
- One sentence, one line Patterns chapter (rust-lang/reference#1275)
- Use semver-compliant example version (rust-lang/reference#1272)

## rust-by-example

9 commits in 767a6bd9727a596d7cfdbaeee475e65b2670ea3a..5e7b296d6c345addbd748f242aae28c42555c015
2022-09-14 09:17:18 -0300 to 2022-10-05 08:24:45 -0300
- Make it clear that rustdoc uses the commonmark spec (rust-lang/rust-by-example#1622)
- Update defaults.md (rust-lang/rust-by-example#1615)
- added "see also" for the @ binding sigil (rust-lang/rust-by-example#1612)
- add more precision to the effects of --bin flag (rust-lang/rust-by-example#1607)
- create bar project in cargo/dependencies example (rust-lang/rust-by-example#1606)
- use consistent wording about type annotation (rust-lang/rust-by-example#1603)
- cast.md improvements (rust-lang/rust-by-example#1599)
- Fix typo in macros.md (rust-lang/rust-by-example#1598)
- Corrected mistaken "The" instead of "There" (rust-lang/rust-by-example#1617)

## rustc-dev-guide

2 commits in 9a86c0467bbe42056f73fdf5b03fff757d7c4a9b..7518c3445dc02df0d196f5f84e568d633c5141fb
2022-10-07 18:34:51 +0200 to 2022-10-08 12:29:47 +0200
- Update debugging.md
- Use llvm subdomain for compiler-explorer link

## embedded-book

1 commits in 4ce51cb7441a6f02b5bf9b07b2eb755c21ab7954..c533348edd69f11a8f4225d633a05d7093fddbf3
2022-09-15 08:53:09 +0000 to 2022-10-10 10:16:49 +0000
- Fix a typo in registers.md  (rust-embedded/book#330)
Dylan-DPC added a commit to Dylan-DPC/rust that referenced this pull request Oct 12, 2022
Update books

## nomicon

1 commits in f53bfa056929217870a5d2df1366d2e7ba35096d..9c73283775466d22208a0b28afcab44db4c0cc10
2022-09-05 07:19:02 -0700 to 2022-09-30 07:31:22 +0900
- Fix typo (rust-lang/nomicon#380)

## reference

9 commits in a7cdac33ca7356ad49d5c2b5e2c5010889b33eee..f6ed74f582bddcec73f753eafaab3749c4f7df61
2022-09-19 17:39:58 -0700 to 2022-10-08 02:43:26 -0700
- Typo 'a' -> 'an' (rust-lang/reference#1280)
- One line one sentence for expressions and statements main chapters (rust-lang/reference#1277)
- Document let else statements (rust-lang/reference#1156)
- Document `label_break_value` in the reference (rust-lang/reference#1263)
- Document target_has_atomic (rust-lang/reference#1171)
- update 'unsafe' (rust-lang/reference#1278)
- Update tokens.md (rust-lang/reference#1276)
- One sentence, one line Patterns chapter (rust-lang/reference#1275)
- Use semver-compliant example version (rust-lang/reference#1272)

## rust-by-example

9 commits in 767a6bd9727a596d7cfdbaeee475e65b2670ea3a..5e7b296d6c345addbd748f242aae28c42555c015
2022-09-14 09:17:18 -0300 to 2022-10-05 08:24:45 -0300
- Make it clear that rustdoc uses the commonmark spec (rust-lang/rust-by-example#1622)
- Update defaults.md (rust-lang/rust-by-example#1615)
- added "see also" for the @ binding sigil (rust-lang/rust-by-example#1612)
- add more precision to the effects of --bin flag (rust-lang/rust-by-example#1607)
- create bar project in cargo/dependencies example (rust-lang/rust-by-example#1606)
- use consistent wording about type annotation (rust-lang/rust-by-example#1603)
- cast.md improvements (rust-lang/rust-by-example#1599)
- Fix typo in macros.md (rust-lang/rust-by-example#1598)
- Corrected mistaken "The" instead of "There" (rust-lang/rust-by-example#1617)

## rustc-dev-guide

2 commits in 9a86c0467bbe42056f73fdf5b03fff757d7c4a9b..7518c3445dc02df0d196f5f84e568d633c5141fb
2022-10-07 18:34:51 +0200 to 2022-10-08 12:29:47 +0200
- Update debugging.md
- Use llvm subdomain for compiler-explorer link

## embedded-book

1 commits in 4ce51cb7441a6f02b5bf9b07b2eb755c21ab7954..c533348edd69f11a8f4225d633a05d7093fddbf3
2022-09-15 08:53:09 +0000 to 2022-10-10 10:16:49 +0000
- Fix a typo in registers.md  (rust-embedded/book#330)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-expressions Area: Expressions I-lang-nominated New Content Missing features or aspects of language not currently documented. RFC Stabilization Docs Documentation required for stabilizing a feature
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

9 participants