Make style-only changes to doc comments for the standard library.

[bvenners]

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 most 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 documentation 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.

[Copilot]

Pull request overview

This pull request makes style-only changes to documentation comments across the Scala standard library to improve consistency. The changes include: (1) converting imperative mood to indicative mood (e.g., "Return" → "Returns"), (2) adding terminal periods to initial sentences, and (3) wrapping code artifact names in backticks for proper rendering.

Key changes:

• Updated method documentation across multiple packages (scala.util, scala.sys, scala.collection, scala.concurrent, etc.)
• Converted ~500+ doc comment verbs from imperative to indicative mood
• Added backticks around type names, method names, and other code artifacts

Reviewed changes

Copilot reviewed 167 out of 167 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
Multiple util files (Regex.scala, Try.scala, etc.)	Updated doc comments to use indicative mood and backticks for code elements
sys package files	Standardized documentation style across system utilities
collection package files	Updated extensive collection API documentation for consistency
concurrent package files	Improved Future/Promise documentation clarity
Multiple annotation files	Changed "Consult" to "See" for cross-references
Various other standard library files	Applied consistent style improvements throughout

The changes are thorough and consistent with the stated goals. All modifications are to documentation only, with no functional code changes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.