Skip to content

docs(javadoc): make document.* public API doclint-clean#130

Merged
DemchaAV merged 1 commit into
developfrom
docs/templates-javadoc-doclint
Jun 3, 2026
Merged

docs(javadoc): make document.* public API doclint-clean#130
DemchaAV merged 1 commit into
developfrom
docs/templates-javadoc-doclint

Conversation

@DemchaAV
Copy link
Copy Markdown
Owner

@DemchaAV DemchaAV commented Jun 3, 2026

What

Makes the entire public canonical surface com.demcha.compose.document.*
Javadoc doclint-cleanmvn 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 @return warnings on CvTheme factories."
That count was an artifact of javadoc's default -Xmaxwarns=100 cap
the log literally stopped at 100 warnings. Raising the cap revealed the
true surface:

Warning Count
no @param 471
no @return 191
no comment (public element, zero Javadoc) 205
no main description 35
use of default constructor 16
@deprecated in package-info 9
no @throws 2
Total 929 across 142 files / 28 packages

The 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:

  • 16 explicit no-arg constructors in layout/definitions/* — each
    documents the otherwise-synthesised public default constructor (byte-identical
    behaviour). This is the repo's own idiom for doclint's use of default constructor (cf. PdfTableRowFragmentRenderHandler()).
  • Removed the @deprecated block-tag from 9 package-info.java files —
    doclint forbids that tag in package docs; the @Deprecated(...) annotation
    and the prose body already carry the deprecation notice. @since and the
    annotation are untouched.

No public API, signature, or runtime behaviour change. Every @param on a
convenience 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 under doclint=all (confirmed
    both with the cap temporarily raised and again under the unmodified CI config).
  • mvn test -pl .1060 tests, 0 failures, 0 errors.
  • Diff is 142 files under document.* (+ this CHANGELOG note); 0 code lines
    deleted
    — all diff-deletions are Javadoc comment reflows.

Scope note

The original ask framed this as a small docs(templates) @return/@param
pass. Given the cap discovery (929, spanning the whole document.* surface and
including ~256 elements needing real descriptions), the decision was to go for
full warning-clean rather than a partial pass. CHANGELOG v1.6.9 updated
under Documentation.

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.
@DemchaAV DemchaAV merged commit ca71a8a into develop Jun 3, 2026
11 checks passed
@DemchaAV DemchaAV deleted the docs/templates-javadoc-doclint branch June 3, 2026 10:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant