Make style-only changes to doc comments for the standard library.#24754
+2,027 −2,027
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The following style changes are made in this commit:
Only doc comments are changed, and only to make the above style changes.
Reasoning: Indicative mood is recommended over imperative mood by the Scaladoc Style Guide:
https://docs.scala-lang.org/style/scaladoc.html
Which says: Document what the method does do not what the method should do. In other words, say “returns the result of applying f to x” rather than “return the result of applying f to x”. Subtle, but important.
It is also what maybe 60% of Scaladoc comments in the standard library does, so this PR makes that consistent. It is also the way doc comments are written in Javadoc for the Java standard library. It is essentially writing the docoumentation as if you are explaining to a user (Returns something...) rather than an implementor (Return something...).
The terminating period is also used some of the time, but not always, in the existing doc comments for the standard library> This makes it consistent. Some phrases are not full sentences, but you can think of the subject as "implicit." "Returns true" means "This method returns true." Also if you have a bullet list where some of the items are complete sentences, and others not, the style guide (Chicago Manual of Style) I go by suggests putting periods after all items. And the Java standard library documentation seems to do this.
A few spots are missed in this PR, which I jotted down as I reviewed every changed file. But it hits most of them, so I'm hoping we can merge this into main and I can do further cleanup in later PRs.