Hi all,
On 14.10.2025 22:01, [email protected] wrote:
> The following commit(s) were added to refs/heads/master by this push:
> new 1441ba9f3 Javadoc
> 1441ba9f3 is described below
>
> commit 1441ba9f3cd172ccfbd2d0c2ce336f4a9750a0a2
> Author: Gary D. Gregory <[email protected]>
> AuthorDate: Tue Oct 14 16:01:49 2025 -0400
>
> Javadoc
>
> - Use longer lines
> - Reduce vertical whitespace
Sorry to be picky about formatting-only commits. I agree they can add
value, but they are hard to review and reproduce. With a long list of
unverifiable whitespace changes, it is easy to unintentionally alter
code as well (as in the change that needed fixing in [1]).
Could we align on a deterministic approach for Javadoc (and possibly
code) formatting so that whitespace, including line breaks, is not left
to individual IDE settings? All IDEs show a Javadoc preview, so moving
spaces around is not useful unless the result is stable and enforceable.
Concretely, can we:
1) Define and document a deterministic Javadoc/comment style:
- Line width and wrapping; when to reflow vs preserve.
- Inline code: prefer {@code ...}; block code: <pre>{@code ...}</pre>.
- HTML usage: paragraphs, lists, tables; where opening/closing tags
go (same line vs new line).
- Block tags: order (@param, @return, @throws, @see, …) and
indentation/alignment.
- Punctuation, capitalization, links ({@link}/{@linkplain}).
2) Choose tooling and make it reproducible:
- Pick a formatter (Eclipse JDT profile, Spotless with
palantir/google/eclipse step, etc.) and pin exact versions.
- Commit all configs (formatter XML, Spotless config, Checkstyle
rules, .editorconfig) to the repo.
- Enforce in CI (“check” goals) and provide IDE import instructions.
- Do a one-time mass reformat PR; afterward, accept only
tooling-driven formatting changes.
Related: can we disable Javadoc generation in CI for at least JDK 8 and
11? The Javadoc doclet is less stable than the Java compiler, and I keep
running into Javadoc bugs across versions.
For example, there is currently no way to write the following without
tripping a Javadoc bug in one version or another:
<pre>{@code
@Override
public void getFoo() {
...
}
}</pre>
On JDK up to 11, the doclet fails on the @Override annotation.
Thanks,
Piotr
References:
[1] https://github.com/apache/logging-log4j2/pull/3831
[2] https://google.github.io/styleguide/javaguide.html#s7-javadoc
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
