Skip to content

Enable Scalafmt in Scaladocs#4842

Open
satorg wants to merge 2 commits intotypelevel:mainfrom
satorg:scalafmt-docstrings
Open

Enable Scalafmt in Scaladocs#4842
satorg wants to merge 2 commits intotypelevel:mainfrom
satorg:scalafmt-docstrings

Conversation

@satorg
Copy link
Contributor

@satorg satorg commented Mar 9, 2026

The only significant change is in .scalafmt.conf:

- docstrings.style = keep
+ docstrings.style = Asterisk

After that, sbt prePR was applied.

Some manual fixes in Scaladoc were also necessary – not because Scalafmt "broke" something, but because a few existing Scaladocs were incorrectly formatted and were therefore treated as plain text. For example:

Details

A table defined in plain text like that:

Benchmark                                       Mode  Cnt         Score        Error  Units
ParTraverseBench.eitherParBitraversePointfree  thrpt   50  20201469.796 ± 143402.778  ops/s
ParTraverseBench.eitherParBitraversePointfull  thrpt   50  24742265.071 ± 133253.733  ops/s
ParTraverseBench.eitherParTraversePointfree    thrpt   50   1150877.660 ±  10162.432  ops/s
ParTraverseBench.eitherParTraversePointfull    thrpt   50   1221809.128 ±   9997.474  ops/s

had to be manually converted into Markdown:

| Benchmark                                     | Mode  | Cnt | Score        | Error        | Units |
|:----------------------------------------------|:------|:----|:-------------|:-------------|:------|
| ParTraverseBench.eitherParBitraversePointfree | thrpt | 50  | 20201469.796 | ± 143402.778 | ops/s |
| ParTraverseBench.eitherParBitraversePointfull | thrpt | 50  | 24742265.071 | ± 133253.733 | ops/s |
| ParTraverseBench.eitherParTraversePointfree   | thrpt | 50  | 1150877.660  | ±  10162.432 | ops/s |
| ParTraverseBench.eitherParTraversePointfull   | thrpt | 50  | 1221809.128  | ±   9997.474 | ops/s |

which is correctly interpreted by both Scaladoc and Scalafmt. Otherwise, it turns into a mess.

Why this change?

Two reasons:

  1. Autoformatting helps maintain a consistent style across the repository, and Scaladoc is part and parcel of that.
  2. It is especially valuable in the AI era, as it reduces unnecessary noise in PRs that AI agents tend to generate.

Why this particular style?

docstrings.style = Asterisk aligns best with the majority of existing Scaladocs in the repository.

@satorg satorg force-pushed the scalafmt-docstrings branch from 54c1555 to 7691397 Compare March 9, 2026 04:30
Sign up for free to 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