Enable Javadoc doclint (all,-missing) and fail on warnings#734
Open
vharseko wants to merge 2 commits into
Open
Enable Javadoc doclint (all,-missing) and fail on warnings#734vharseko wants to merge 2 commits into
vharseko wants to merge 2 commits into
Conversation
- Replace <doclint>none</doclint> with a single inherited property
<doclint>all,-missing</doclint> + <doclint>${doclint}</doclint>; drop the
per-module duplicates.
- Bump maven-javadoc-plugin 3.11.2 -> 3.12.0 and enable
<failOnWarnings>true</failOnWarnings>.
- Fix every doclint error and warning across all modules on both JDK 11 and
JDK 26: escape bare &, < and > in comments; <tt> -> <code>; <br/> -> <br>;
drop self-closing <p/> and empty <p>; fix heading hierarchy, broken {@link}
references, malformed HTML and ASCII diagrams; add missing @param/@throws
descriptions.
- Fix the config generator: clientMO.xsl / serverMO.xsl emit <code>null</code>
and <code>true</code>; fix two <adm:synopsis>> typos in the HTTP*Authorization
configuration XML; reword an LDAP filter example to avoid a bare &.
- Pin org.openidentityplatform.commons.i18n-framework:maven-plugin to
${commons.version} and bump commons to 3.1.2-SNAPSHOT so message descriptor
classes are generated with the HTML-escaping generator
(OpenIdentityPlatform/commons#271); remove the **/*Messages.java Javadoc
exclusion.
Verified with mvn clean install on JDK 11 and JDK 26: 24/24 modules,
0 doclint errors, 0 warnings.
vharseko
added
docs
build
java
…7-21
- .gitattributes: force *.html to LF so JDK 25/26 doclint on Windows does
not treat the CR of a CRLF as part of a multi-line <a> start tag
(opendj-core overview.html: "unknown tag: a").
- MessageHandler#isLastMessageFromLateQueue: {@link #getNextMessage()} ->
{@code getNextMessage()}; the enclosing class is package-private, so
JDK 17-21 doclint reports "reference not accessible".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Turn Javadoc doclint back on and keep it clean.
<doclint>none</doclint>with a single inherited property<doclint>all,-missing</doclint>+<doclint>${doclint}</doclint>, and dropthe per-module duplicates.
maven-javadoc-plugin3.11.2→3.12.0and enable<failOnWarnings>true</failOnWarnings>.and JDK 26 (JDK 11's doclint is stricter about a bare
>):escape bare
&,<,>;<tt>→<code>;<br/>→<br>; dropself-closing
<p/>and empty<p>; fix heading hierarchy, broken{@link}references, malformed HTML and ASCII diagrams; add missing
@param/@throwsdescriptions.
clientMO.xsl/serverMO.xslnow emit<code>null</code>/<code>true</code>; fix two<adm:synopsis>>typos inthe HTTP*Authorization configuration XML; reword an LDAP filter example to
avoid a bare
&.Message classes / commons dependency
The generated i18n
*Messagesclasses derive their Javadoc from message text(which may contain runtime HTML). Instead of excluding them, this relies on the
HTML-escaping message generator from OpenIdentityPlatform/commons#271, so:
commons.versionis bumped to3.1.2-SNAPSHOT(same as Bump org.openidentityplatform.commons to 3.1.2-SNAPSHOT #733), andorg.openidentityplatform.commons.i18n-framework:maven-pluginis pinned to${commons.version}sogenerate-messagesactually uses the escapinggenerator (its version was previously unspecified and floated to the latest
release).
Depends on OpenIdentityPlatform/commons#271 being available (merged/released
as
3.1.2). Until then the escaping generator must be built locally.Verification
mvn clean installon JDK 11 and JDK 26: 24/24 modules,0 doclint errors, 0 warnings, 18 javadoc jars.