docs(javadoc): make 733 published descriptions say something, and gate it - #201
Merged
Conversation
…e, and make the licence gate honest Three decisions taken by the maintainer, applied. DetectorType. The enum a user types into @AsyncTest(excludes=...) had 127 bare constants in the published javadoc. Each now carries the first sentence of the detector it selects, taken from that detector's own class javadoc rather than invented. The mapping is derived: AsyncTestConfig.build() gives constant to flag, DetectorRegistry's constructor gives flag to class, and all 127 resolve with none left over. The file is @AILocked and the lock was waived for this on purpose: its own reason is that a constant needs synchronized edits in five places, and a comment adds no constant. The annotation now says the lock is on the constant set, not the file. Two stale claims in the same guardrail are fixed while there: it described "both branches of build()", which has been one expression per detector for some time, and @AIKeepInSync still named the old META-INF/services path for the built-in factories. Both feed the generated CLAUDE.md, so a stale guardrail misdirects every future contributor. Tags. 295 @param and 122 @return appended to existing blocks. Appended, not rebuilt: an earlier attempt rebuilt blocks and replaced real prose with a stub, turning ConcurrencyRunner.execute's javadoc into "Execute.". 287 single-line comments were expanded in a separate first pass so no insertion had to reason about indices another insertion had already moved. Licence gate. Behaviour unchanged, which is the decision: it is intended for a PolyForm Noncommercial library and LicenseGuard is security-critical. What changes is honesty. The README said "outcome depends on the configured backend", which does not prepare anyone for a SecurityException before a test body runs; it now shows the error and explains that CI is silently mocked while a laptop is not. TROUBLESHOOTING.md gains the fix for Maven, Gradle and the IDE, and the reason the gate is loud: a run that was not licensed must never look like a run that found no bugs. Deliberately unchanged: the 51 default-constructor warnings, whose fix would add 51 public constructors to satisfy a style rule. Verified on three gates rather than compilation, which stayed silent through every earlier mistake: javadoc:jar 0 errors, PMD 0 violations, mvn verify green across all four modules. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AENSLJhmSuFzLhXDv4QKUA
…e it Closing every doclint warning did not make the javadoc useful. Doclint answers one question, is the tag present, so a mechanical pass that adds a tag per parameter turns a red build green without a reader learning anything. What that pass had left, all of it on public members and published to consumers: 432 @param tags, 166 @return tags and 135 one-line summaries that restated the identifier and nothing else. `@param lockName the lock name`. `@return the size` on `size()`. The worst read `/** The totcou races. */` over a public field recording time-of-check-to-time-of-use races, the generated prose having respelled a misspelled acronym into a non-word. All 733 now carry a fact the signature does not: the unit on sleepDuration, the null rule on SiteCapture.capture(), that detectors track their subjects by identity rather than equality, that distanceInBytes under a cache line is what makes two fields share one. Two defects surfaced that doclint cannot see, because it checks nothing below protected by default. SpinContentionBarrier's constructor javadoc had been placed between two cache-line padding fields, so it documented pad7 while the public constructor had none. And 183 stray blank lines sat between a javadoc block and its member. totcouRaces keeps its misspelled name: it is public API and renaming it breaks binary compatibility against the 1.6.0 baseline. The javadoc now states what it records and that the name is kept deliberately. JavadocDescribesRatherThanRestatesTest pins this, asking whether a description is anything more than its identifier respelled once a leading article is ignored. Verified in both directions: it failed on the real tree before the fix, naming two sites the sweep's acronym handling had missed, and reintroducing one placeholder afterwards turned it red again with the exact file and line. It also asserts it scanned more than 100 files, so it cannot pass by scanning nothing. Verified with `mvn verify` on all four modules: BUILD SUCCESS, including PMD, SpotBugs, Checkstyle, japicmp against 1.6.0, and javadoc:jar with doclint=all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AENSLJhmSuFzLhXDv4QKUA
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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.
Closing every doclint warning did not make the javadoc useful. Doclint answers one question, is the tag present, so a mechanical pass that adds a tag per parameter turns a red build green without a reader learning anything.
Counting what that pass had actually left, all of it on public members and published to consumers:
@paramtags@returntagsEvery one restated the identifier and nothing else.
@param lockName the lock name.@return the sizeonsize(). The worst read/** The totcou races. */over a public field recording time-of-check-to-time-of-use races, the generated prose having respelled a misspelled acronym into a non-word.All 733 now carry a fact the signature does not: the unit on
sleepDuration, the null rule onSiteCapture.capture(), that detectors track their subjects by identity rather than equality, thatdistanceInBytesunder a cache line is what makes two fields share one.Two defects doclint could not see
It checks nothing below
protectedby default.SpinContentionBarrier's constructor javadoc had been placed between two cache-line padding fields, so it documentedpad7. The public constructor had no javadoc at all and the build was silent. Reattached, and it now states the contract that matters: arriving threads spin rather than park, which is what keeps the collision tight enough to reproduce a race.totcouRaceskeeps its misspelled name. It is public API and renaming it breaks binary compatibility against the 1.6.0 baseline; the javadoc now states what it records and that the name is deliberate.The gate
JavadocDescribesRatherThanRestatesTestasks the question doclint cannot: whether a description, ignoring a leading article, is anything more than its identifier respelled. It does not measure length or style, because a short description can be complete (@return this builder) and no prose rule survives contact with 127 detectors.Verified in both directions rather than assumed:
ABAProblemDetector.java:197 * @return the analyze ABAand one other that the sweep's acronym handling had missed;Verification
mvn verifyon all four modules: BUILD SUCCESS, including PMD, SpotBugs, Checkstyle, japicmp against the 1.6.0 baseline, andjavadoc:jarwithdoclint=all. Javadoc warnings are 0 apart from the 100 implicit-constructor ones left in place by an earlier decision.🤖 Generated with Claude Code
https://claude.ai/code/session_01AENSLJhmSuFzLhXDv4QKUA