amaechler opened a new pull request, #20592:
URL: https://github.com/apache/druid/pull/20592
### Description
Upgrades `com.puppycrawl.tools:checkstyle` from 12.3.1 to 14.3.0 and fixes
the Javadoc that the new version cannot parse. This picks up the Dependabot
bump from #20580 (closed) and adds the source migration that #20168 found
missing. The change is limited to Javadoc comment lines, and
`codestyle/checkstyle.xml` is unchanged.
#### Why the bump fails on its own
Checkstyle 13 and later ship a stricter Javadoc parser. Our `UnusedImports`
check processes Javadoc by default, so it reports every Javadoc comment that
fails to parse. It also reports imports that are referenced only from such a
comment as unused. With 14.3.0 on master (at 740cf5aacc3) this gives 113
violations in 93 files across 17 modules: 105 parse errors and 8 knock-on
unused-import errors. CI only shows the first failing module
(`druid-processing`) because downstream modules are skipped.
Turning off Javadoc processing in `UnusedImports` instead produces 244
unused-import violations (per the triage on #20168). Fixing the comments keeps
the check as it is.
#### Fixed the malformed Javadoc
The parse errors are real Javadoc typos. Each fix keeps the existing wording:
- `{@link}` syntax: stray `)` or `]` before the closing brace, missing
closing `}`, nested `{@link {@link X}}`, `{@link #field#method()}`, and a
modifier or extra spaces inside a generic reference.
- `@see {@link X}` and `@throws {@link X}` become `@see X` and `@throws X`.
`@see X, the vectorized version` becomes `@see X the vectorized version`, as in
#19064.
- `<pre>{@code ...}</pre>` examples whose braces did not balance get the
missing `}`.
- Broken HTML: `<br></br>`, stray `</p>`, a `<p/` split across two lines,
`</pre</code>`, `<link a=...>` instead of `<a href=...>`, `<i>...</li>`, and
list items without `<ul>`.
- Generics and placeholders in prose, such as `Map<String, Object>`,
`<counter,hash>` and `Object[]`, are wrapped in `{@code}`.
- Annotations at the start of a line inside `<pre>` and `<code>` examples
are escaped as `@`, so they are no longer read as block tags.
No import is removed. All 8 unused-import errors go away once their comments
parse.
#### Testing
- `checkstyle:check` with the cache cleared: 0 violations in all 80 modules,
both on this branch and merged with master at f75fd1fae3a.
- strict-compilation (`clean -DstrictCompile test-compile`): passes.
#### Release note
None. No user-facing change.
<hr>
This PR has:
- [x] been self-reviewed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
