fix: make javadoc:javadoc succeed on the forked OpenSearch tree - #44
Merged
Merged
Conversation
The fork brought upstream's three custom block tags and a set of javadoc
references whose targets the pruning removed, so `mvn javadoc:javadoc` failed
with "unknown tag: opensearch.api" and "reference not found".
- Declare `@opensearch.api`, `@opensearch.internal` and `@opensearch.experimental`
in a `pluginManagement` entry for maven-javadoc-plugin, so both the plain goal
and the release profile's `attach-javadocs` see them. 1,820 occurrences across
the forked tree; they render as ordinary block tags.
- Rewrite the 201 references that no longer resolve: `{@link X}` to `{@code X}`
where the member or class was pruned, and drop `@see` lines whose only target
is gone. Comment-only; no production code changes.
- Three sites needed more than that: an orphaned javadoc block left on
`ClusterBlocks#toString()` by a removed method, `Provider#get()`'s `@throws`
clauses for two exception types that are not in the fork (kept as prose), and a
link split across two lines in `NativeMemoryUsageCalculator`.
`mvn javadoc:javadoc` and `mvn -Prelease javadoc:jar` both succeed; 636 tests pass.
marevol
added a commit
that referenced
this pull request
Sep 14, 2026
…#45) #44 removed the javadoc errors but left 12,486 warnings, all of them from doclint's `missing` group: 6,744 "no comment", 2,332 "no @return", and @param/@throws gaps throughout the imported OpenSearch tree. That is upstream's documentation coverage, not a defect introduced here, and it buries anything worth reading in the build output. Set `doclint` to `all,-missing`, so the groups that catch real breakage - syntax, HTML, accessibility and references - still fail the build, while completeness is left alone. It also pins behaviour that otherwise depends on the JDK in use. `mvn javadoc:javadoc` and `mvn -Prelease javadoc:jar` now report 0 errors and 0 warnings, and still generate all 4,902 pages.
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.
mvn javadoc:javadochas been failing since the fork landed:Two causes, both introduced by importing the OpenSearch tree.
Custom block tags
OpenSearch marks every class with
@opensearch.api,@opensearch.internalor@opensearch.experimentaland declares them in its own javadoc configuration. Thefork brought 1,820 of them and no declaration, so javadoc rejected each one.
They are declared now in a
pluginManagemententry for maven-javadoc-plugin, whichthe release profile's
attach-javadocsexecution inherits — previously thatexecution carried its own copy of the version and encoding settings, and the plain
javadoc:javadocgoal saw no configuration at all. The tags render as ordinaryblock headings (1,684 in the generated HTML).
Stripping the tags from the sources was the alternative; declaring them is twelve
lines of pom against edits in 600+ files, and the stability level they record is
real information.
References the pruning removed
201
{@link}/@seetargets no longer exist —Requests#indexRequest(String),BulkRequest#add(DocWriteRequest),WeightedRoutingService,RoutingNodes#failShardand so on. javadoc reports each as
reference not found, and stops at 100, so thefirst run only showed part of it.
Each was rewritten at the exact position javadoc reported:
{@link X}to{@code X}where the member or class was pruned. The prose stillnames what it named; it just no longer claims to link to it.
@see Xlines dropped, since@seecannot hold a non-reference.Three sites needed a judgement call rather than a substitution:
ClusterBlocks— a javadoc block for a removed method was left attached totoString(), documenting anindicesparameter that method does not have. Deleted.Provider#get()—@throws OutOfScopeException/@throws ProvisionExceptionfortwo exception types the fork does not contain. Kept as prose in the description so
the contract survives.
NativeMemoryUsageCalculator— a{@link}split across two lines, which thepositional rewrite could not handle.
All of it is inside comments;
git diffon the source tree touches no code.Verification
mvn javadoc:javadocmvn -Prelease javadoc:jarmvn test12,486 javadoc warnings remain, almost all "no @PARAM for
<T>" in the importedtree. They do not fail the build and are upstream's, not introduced here.