Skip to content

Conversation

@bvenners
Copy link

@bvennersbvenners commented Dec 14, 2025

The following style changes are made in this commit:

  1. Use indicative mood (Returns, Builds, ... not imperative mood (Return, Build, ...).
  2. Terminate initial sentence with a period.
  3. Place code artifact names (for classes, methods, etc.) in backticks so they will render in code font.

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.

The following style changes are made in this commit: 1. Use indicative mood (Returns, Builds, ... not imperative mood (Return, Build, ...). 2. Terminate initial sentence with a period. 3. Place code artifact names (for classes, methods, etc.) in backticks so they will render in code font. Only doc comments are changed, and only to make the above style changes.
@bvennersbvenners requested a review from a team as a code ownerDecember 14, 2025 19:37
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@bvenners