[Concurrency] Revise Async- related files doc
#58930
Conversation
- Revise '// Prints' comments style like the other stdlib files - Remove verbose string interpolations and extra spaces - Remove some unneeded parentheses - Replace the majority of ' : ' with ': ' - Fix wrong indentation - Keep files with a single empty line at the end
Jager-yoo
force-pushed
the
revise-concurrency-doc
branch
2 times, most recently
from
4fc5bda to
b9bbe62
Compare
|
Hi, @invalidname, @phausler, @bjlanier! |
|
Overall the changes look sound to me. I defer to the folks doing documentation publishing for style guidance. |
|
Really appreciate it! 👍🏻 |
| /// return Int.random(in: 1...10) | ||
| /// } | ||
| /// onCancel: { @Sendable () in print ("Canceled.") } | ||
| /// ) |
There was a problem hiding this comment.
Nice job catching this stray ) that shouldn't be there.
There was a problem hiding this comment.
Thanks! 😄
Note that I also edited the word "Canceled." → "Cancelled." (double l)
There was a problem hiding this comment.
"Canceled" was correct — please change this back.
Documentation follows Apple Style Guide, which calls for spelling it "canceled" and "canceling". The API naming guidelines for Cocoa (which Swift often follows) follow historical precedent of other API names, and spells it "cancelled" and "cancelling".
There was a problem hiding this comment.
@amartini51 Thanks for following up!
The Apple Style Guide - C definitely says that we should use one l for "canceled".
On lines 121-122 in the very same file, however, there is case cancelled in use.
/// The stream finished as a result of cancellation.
case cancelledActually, "cancelled" is being used much more than "canceled" in overall Swift repo. 🧐
Would it be better to just revert this word for now? How do you think?
There was a problem hiding this comment.
Let's revert this change please, so we're not making the problem worse. Someone (possibly me or @invalidname) can take another pass over the file to correct the other "cancelled" spellings in a different PR.
There was a problem hiding this comment.
Regarding lines 121-121, case cancelled is an example of the Cocoa naming guidelines I mentioned. You can see this style difference in API reference for Task and and related types — symbols with "cancelled" in its name have "canceled" in their docs.
Both style guides use the spelling "cancellation".
There was a problem hiding this comment.
Ohh, now I see. Documentation follows "canceled", while the API naming follows "cancelled".
Sorry for additional revert commit, and thank you so much for being part of this.
There was a problem hiding this comment.
Reading my original post, I could have been clearer that there were two style guides involved here, one for code and one for docs. Sorry about that. Thanks for the fixes in this PR!
| @@ -22,12 +22,12 @@ extension AsyncSequence { | |||
| /// | |||
| /// In this example, an asynchronous sequence called `Counter` produces `Int` | |||
| /// values from `1` to `10`. The `dropFirst(_:)` method causes the modified | |||
| /// sequence to ignore the values `0` through `4`, and instead emit `5` through `10`: | |||
| /// sequence to ignore the values `1` through `3`, and instead emit `4` through `10`: | |||
There was a problem hiding this comment.
Right. This way matches the actual output on line 30.
|
Thanks for reviewing, @invalidname! |
Documentation follows Apple Style Guide spelling: https://help.apple.com/applestyleguide/#/apsgb744e4a3#apdb51b39ece6204
|
@swift-ci Please smoke test. |
[Concurrency] Revise `Async-` related files doc (cherry picked from commit 4b0824c)
// Printscomments style like the other stdlib files.