Editorial cleanup on expressions (part 1) #967

Havvy · 2021-02-20T08:57:59Z

Use "the syntax of" uniformly.
Use asterisks for all defined terms.
Define more terms, espcially in the syntax section.
- Reword things so that definitions are generally first.
- I did not necessarily go with the best wording; the idea is to
  improve, not perfect. I still need to dedicate time to each
  expressions individually.
Remove usage of "the compiler" and "Rust".
- This also involved rewording.
- How to deal with closure types and closure expressions is gonna be
  an interesting question to solve. I avoided solving it here.
Remove non-normative information or put them in a Note.
A few added section headers
Move links to the bottom

Note that I've left quite a few nonsensical statements alone, such as
any that use "denote". They'll be treated separately.

About halfway through the list of expressions and this PR is getting
large. So I'm gonna cut this one here, stopping at grouped expressions
in the alphabetical list.

* Use "the syntax of" uniformly. * Use asterisks for all defined terms. * Define more terms, espcially in the syntax section. ** Reword things so that definitions are generally first. ** I did not necessarily go with the best wording; the idea is to improve, not perfect. I still need to dedicate time to each expressions individually. * Remove usage of "the compiler" and "Rust". ** This also involved rewording. ** How to deal with closure types and closure expressions is gonna be an interesting question to solve. I avoided solving it here. * Remove non-normative information or put them in a `Note`. * A few added section headers * Move links to the bottom Note that I've left quite a few nonsensical statements alone, such as any that use "denote". They'll be treated separately. About halfway through the list of expressions and this PR is getting large. So I'm gonna cut this one here, stopping at grouped expressions in the alphabetical list.

ehuss

I really like the initial sentences that explain what the expression does.

ehuss · 2021-02-27T16:44:52Z

src/expressions/block-expr.md

-Statements are usually required to be followed by a semicolon, with two exceptions.
-Item declaration statements do not need to be followed by a semicolon.
-Expression statements usually require a following semicolon except if its outer expression is a flow control expression.
+The syntax for a block is `{`, then any [inner attributes], then [statements], then an optional operand, and finally a `}`.


I'm feeling a little uncomfortable with the systematic replacement of "expression" with "operand". In this particular sentence, I feel like it reduces the readability, since it is not clear what an "operand" is in this instance, whereas an "expression" is a clear description of what the syntax is.

I realize that might seem like the opposite of what I said in #888 (comment), and I'm having a hard time thinking of guidelines of which terminology to use. I think my original thoughts were, wherever the term "subexpression" was used, "operand" would probably work better. In this case, I think the original was fine.

There are a few other places like this in this PR that I won't call out specifically.

How about syntactically calling it an expression, but keeping the name operand? So, for example,

"then statements, then an optional expression, (called) the xyz operand, and finally a }."

Also, what do you think of adding the word "called" there, where we name the syntactic element?

Alternatively, we could keep operand there, and always link to its definition where we use it. Or add a tooltip for it, but that's probably not a good idea.

src/expressions/field-expr.md

src/expressions/call-expr.md

src/expressions/field-expr.md

ehuss · 2021-02-27T22:00:24Z

src/expressions/field-expr.md

 A field expression denotes a field of a [struct] or [union].
+
 To call a function stored in a struct, parentheses are needed around the field expression.


This seems to be redundant now?

src/expressions/field-expr.md

src/expressions/grouped-expr.md

ehuss · 2021-02-27T22:08:04Z

src/expressions/grouped-expr.md

+A *parenthesized expression* wrap a single expression, evaluating to that expression.
+The syntax for a parenthesized expression is a `(`, then an operand, the *enclosed operand*, and then a `)`.
+
+An expression enclosed in parentheses evaluates to the value of the enclosed operand.


This seems to repeat the first sentence, they both say that it evaluates to the enclosed expression.

src/expressions/field-expr.md

Co-authored-by: Eric Huss <[email protected]>

* Go back to calling the syntactic elements "expressions", but name them operands afterwards. * Use "called XYZ" to name something in syntax. * Trade out a few uses of expressions using letters for operand names for the actual operand names. * Pick arbitrary names for the operands. I don't like some of them, but they're not set in stone. * Say they're not set in stone in the main expressions chapter.

Havvy · 2021-03-04T05:50:44Z

This is ready for re-review.

ehuss

Sorry about slow reviews. I recently had surgery, and have been a bit distracted.

src/expressions/field-expr.md

ehuss · 2021-03-07T23:58:17Z

src/expressions/block-expr.md

+Statements are usually required to be followed by a semicolon, with two exceptions:
+
+1. Item declaration statements do not need to be followed by a semicolon.
+2. Expression statements usually require a following semicolon except if its outer expression is a flow control expression.


I think there should be a blank like after this, so that the sentence "Furthermore, extra semicolons..." is not combined with the last point. At least, the way I'm reading it, it doesn't seem like it should be combined.

src/expressions/await-expr.md

ehuss · 2021-03-08T00:13:17Z

src/expressions.md

+> **Note**: We give names to the operands of expressions so that we may discuss
+> them, but these names are not stable and may be changed.


I'm curious why this needs to be stated. Are you concerned that other people will start using these names, and you don't want that?

Mainly because I'm coming up with them off the spot without any rigorous discussion or approval from the lang team. I might try an RFC for making these terms part of the language, and dealing with the bikeshed that that entails. I also want to be able to freely change them if we do find better names.

Co-authored-by: Eric Huss <[email protected]>

Havvy · 2021-03-25T21:59:10Z

Finally stopped feeling super lazy and added the newline. That addresses review comments and should be ready to merge.

ehuss

Nice!

I still think the note about operand naming isn't necessary, since the reference introduces all sorts of names that are just a way of putting labels on what is being discussed, but don't change the language in any way. But I think it's fine to leave in, it can be removed later if desired.

Update books ## reference 4 commits in d10a0af8dca25d9d548ca6a369fd66ad06acb3c9..fd97729e2d82f8b08d68a31c9bfdf0c37a7fd542 2021-03-21 11:14:06 -0700 to 2021-03-28 14:29:19 -0700 - Editorial cleanup on expressions (part 1) (rust-lang/reference#967) - Update type casts section (rust-lang/reference#961) - Add missing "?" notion (rust-lang/reference#989) - Fix typo (rust-lang/reference#988) ## book 8 commits in fc2f690fc16592abbead2360cfc0a42f5df78052..b54090a99ec7c4b46a5203a9c927fdbc311bb1f5 2021-03-05 14:03:22 -0500 to 2021-03-24 11:21:46 -0500 - correct the signature of the `deref` method (rust-lang/book#2658) - Clarify the immutability of a reference (rust-lang/book#2646) - Tweak wording around Windows representation of enter - Ch. 02 note - Enter results in CRLF on Windows (rust-lang/book#2648) - Added an example of slicing result (rust-lang/book#2649) - Fix word wrapping, mention dictionary.txt is also in the ci dir - README: note that spellcheck.sh is in ci directory (rust-lang/book#2652) - Change someurl.com to example.org (rust-lang/book#2655) ## rust-by-example 12 commits in eead22c6c030fa4f3a167d1798658c341199e2ae..29d91f591c90dd18fdca6d23f1a9caf9c139d0d7 2021-03-04 16:26:43 -0300 to 2021-03-23 09:03:39 -0300 - Unwrap some drinks. (rust-lang/rust-by-example#1431) - doc(testcase_linked_list): add a little extra note about pattern (rust-lang/rust-by-example#1408) - Update function name in comment (rust-lang/rust-by-example#1413) - Fixes minor typo in src/types/cast.md (rust-lang/rust-by-example#1414) - Add destructuring example to generics new type (rust-lang/rust-by-example#1416) - update struct.md (rust-lang/rust-by-example#1419) - fix name from rectangle to Rectangle (rust-lang/rust-by-example#1420) - Typo "incures" in code comment (rust-lang/rust-by-example#1422) - Changed impl to use Self::Item (rust-lang/rust-by-example#1425) - Fix code highlighting in some places (rust-lang/rust-by-example#1427) - Update multi_bounds.md (rust-lang/rust-by-example#1428) - Reformulated text for redability (rust-lang/rust-by-example#1429) ## rustc-dev-guide 3 commits in 67ebd4b..0687daa 2021-03-11 13:36:25 -0800 to 2021-03-28 13:33:56 -0400 - Add notes about nightly rustc version for the rustc-driver examples - Update rustc-driver-*.rs examples (rust-lang/rustc-dev-guide#1095) - Fix rust compiler meeting info (rust-lang/rustc-dev-guide#1087) ## embedded-book 1 commits in f61685755fad7d3b88b4645adfbf461d500563a2..d3f2ace94d51610cf3e3c265705bb8416d37f8e4 2021-03-08 01:06:44 +0000 to 2021-03-17 07:53:09 +0000 - Add binary attribute to .jpeg files, closes rust-embedded/book#287 (rust-embedded/book#288)

Havvy requested a review from ehuss February 20, 2021 08:58

Havvy force-pushed the expr-cleanup branch from 1891178 to 1906552 Compare February 20, 2021 09:02

Havvy force-pushed the expr-cleanup branch from 1906552 to a065d3e Compare February 27, 2021 21:51

ehuss reviewed Feb 27, 2021

View reviewed changes

Havvy and others added 2 commits February 27, 2021 23:02

Apply suggestions from code review

3da65a1

Co-authored-by: Eric Huss <[email protected]>

ehuss reviewed Mar 8, 2021

View reviewed changes

Havvy force-pushed the expr-cleanup branch from 402b128 to 2367297 Compare March 25, 2021 21:58

Apply suggestions from code review

2367297

Co-authored-by: Eric Huss <[email protected]>

ehuss mentioned this pull request Mar 28, 2021

Fix ambiguous phrasing in 8.2.13 in paragraph on closure traits #991

Closed

ehuss approved these changes Mar 28, 2021

View reviewed changes

ehuss merged commit fd97729 into rust-lang:master Mar 28, 2021

ehuss mentioned this pull request Mar 29, 2021

Update books rust-lang/rust#83662

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editorial cleanup on expressions (part 1) #967

Editorial cleanup on expressions (part 1) #967

Havvy commented Feb 20, 2021

ehuss left a comment

ehuss Feb 27, 2021

Havvy Feb 28, 2021

ehuss Feb 27, 2021

Havvy Feb 28, 2021

ehuss Feb 27, 2021

Havvy commented Mar 4, 2021

ehuss left a comment

ehuss Mar 7, 2021

ehuss Mar 8, 2021

Havvy Mar 8, 2021

Havvy commented Mar 25, 2021

ehuss left a comment

		A field expression denotes a field of a [struct] or [union].

		To call a function stored in a struct, parentheses are needed around the field expression.

		> Note: We give names to the operands of expressions so that we may discuss
		> them, but these names are not stable and may be changed.

Editorial cleanup on expressions (part 1) #967

Editorial cleanup on expressions (part 1) #967

Conversation

Havvy commented Feb 20, 2021

ehuss left a 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

Havvy commented Mar 4, 2021

ehuss left a 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

Havvy commented Mar 25, 2021

ehuss left a comment

Choose a reason for hiding this comment