docs(javadoc): make document.* public API doclint-clean#130
Merged
Conversation
Clear every doclint warning on the public canonical surface (com.demcha.compose.document.*) so `mvn javadoc:javadoc` (doclint=all) runs warning-free. Scope was far larger than first visible: javadoc's default -Xmaxwarns=100 cap surfaced only ~100 warnings, but the true count was 929 across 142 files / 28 packages (raised the cap to enumerate the full set, then reverted). Mix: 471 no-@param, 191 no-@return, 205 no-comment, 35 no-main-description, 16 use-of-default-constructor, 9 @deprecated-in- package-info, 2 no-@throws. Additive Javadoc only, with two sanctioned, behaviour-neutral exceptions: - 16 explicit no-arg constructors in layout/definitions/* — documents the otherwise-synthesised public default constructor (identical behaviour); the repo-idiomatic fix for doclint's "use of default constructor". - removal of the @deprecated block-tags doclint forbids in 9 package-info files (the @deprecated annotation + prose body already carry the notice). No public or runtime behaviour change. Verified: javadoc:javadoc is warning-clean under doclint=all (real CI config) and the full suite is green (1060 tests, 0 failures, 0 errors). Follows cycle 1.6.9 Track N (PR #128 widened javadoc validation to testing.*); these document.* gaps predate that work.
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
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
Makes the entire public canonical surface
com.demcha.compose.document.*Javadoc doclint-clean —
mvn javadoc:javadoc -pl .(doclint=all,failOnError=true,show=public) now runs warning-free.Why this is bigger than it looked
The work started from "~100
no @returnwarnings onCvThemefactories."That count was an artifact of javadoc's default
-Xmaxwarns=100cap —the log literally stopped at
100 warnings. Raising the cap revealed thetrue surface:
no @paramno @returnno comment(public element, zero Javadoc)no main descriptionuse of default constructor@deprecatedinpackage-infono @throwsThe build was green before (warnings, not errors), and stays green — this
just closes the real gaps on the public docs surface.
What changed
Additive Javadoc only, with two sanctioned, behaviour-neutral exceptions:
layout/definitions/*— eachdocuments the otherwise-synthesised
publicdefault constructor (byte-identicalbehaviour). This is the repo's own idiom for doclint's
use of default constructor(cf.PdfTableRowFragmentRenderHandler()).@deprecatedblock-tag from 9package-info.javafiles —doclint forbids that tag in package docs; the
@Deprecated(...)annotationand the prose body already carry the deprecation notice.
@sinceand theannotation are untouched.
No public API, signature, or runtime behaviour change. Every
@paramon aconvenience constructor was copied from the documented primary
constructor/record header in the same file, so wording stays consistent.
Verification
mvn javadoc:javadoc -pl .— 0 warnings underdoclint=all(confirmedboth with the cap temporarily raised and again under the unmodified CI config).
mvn test -pl .— 1060 tests, 0 failures, 0 errors.document.*(+ this CHANGELOG note); 0 code linesdeleted — all diff-deletions are Javadoc comment reflows.
Scope note
The original ask framed this as a small
docs(templates)@return/@parampass. Given the cap discovery (929, spanning the whole
document.*surface andincluding ~256 elements needing real descriptions), the decision was to go for
full warning-clean rather than a partial pass. CHANGELOG
v1.6.9updatedunder Documentation.