Skip to content

Fix the dangling javadoc references jmsfx#136 left behind - #147

Merged
ctgnz merged 1 commit into
masterfrom
fix/144-javadoc-references
Sep 30, 2026
Merged

ctgnz merged 1 commit into
masterfrom
fix/144-javadoc-references

Conversation

@ctgnz

@ctgnz ctgnz commented Sep 30, 2026

Copy link
Copy Markdown
Owner

Blocks #144. The 2.0.0 tag's second run failed here.

What broke

Six {@link} references to getGraphicLocation, which #136 renamed to getGraphicKey. javadoc with doclint=all treats an unresolvable reference as an error, and the release profile is the only thing that runs javadoc — so verify never saw them, on any build, for the whole epic.

file
MainElement.java:13 #getGraphicLocation(StandardIdentity)
AmplifierListItem.java:27 #getGraphicLocation(StandardIdentity)
HqtfDummy.java:28, :37 #getGraphicLocation(StandardIdentity, SymbolSet)
Status.java:55, :65 #getGraphicLocation(StandardIdentity, SymbolSet)

Only the arg-taking method was renamed. The no-argument getGraphicLocation() still exists on AmplifierListItem, Dimension and SymbolSet, where it is the authoring directory rather than a cache key — so a blanket rename would have been wrong, and I checked each of the ~100 remaining uses is real code rather than a doc link.

MainElement's paragraph was stale in three ways rather than one, so it is rewritten instead of patched: it described #124 as pending and said the categories #123 covers "still do" fall back to the classpath. Both are done, and since #130 no generated library returns null there for anything it can draw — which is exactly what the contract now asserts.

On the verification

I reported earlier that "the release profile builds clean". That run was -Dmaven.javadoc.skip=true -Dgpg.skip=true — it skipped both of the things -Prelease adds, so it proved nothing, and this is what it would have caught.

Done properly this time: a full -Pstandard,release clean package with javadoc enabled. No unresolved references, BUILD SUCCESS, and all four javadoc and sources jars produced. Then -Pstandard verify for Spotless, which reflowed one paragraph where the shorter method name moved the wrap point — and the release build re-run after that.

The pattern worth fixing separately

This is the third thing to fail only at tag time: the missing secrets, the stale artifact lists, and now javadoc. The doclint config's own comment records the same class of bug — "it is what caught a {@link} to a type the file never imported, the release profile having never been run before".

-Prelease drifts because nothing exercises it between releases. A CI step running javadoc:javadoc against the release profile's doclint would turn a broken {@link} into a failed PR check instead of a burned tag. Not in this PR — it costs CI time and that is a call worth making on its own — but I would suggest it as a follow-up before 2.1.

🤖 Generated with Claude Code

The 2.0.0 tag's second run failed here: six {@link} references to
getGraphicLocation, which #136 renamed to getGraphicKey. javadoc with
doclint=all treats an unresolvable reference as an error, and the release
profile is the only thing that runs javadoc - so `verify` never saw them.

Only the arg-taking method was renamed. The no-argument getGraphicLocation()
still exists on AmplifierListItem, Dimension and SymbolSet, where it is the
authoring directory rather than a key, so a blanket rename would have been
wrong.

MainElement's paragraph was stale in three ways rather than one, and is
rewritten instead of patched: it described #124 as pending, and said the
categories #123 covers "still do" fall back to the classpath. Both are done,
and since #130 no generated library returns null there for anything it can
draw - which is what the injected-markup contract now asserts.

Verified by running what CI runs: a full -Pstandard,release package with
javadoc enabled reports no unresolved references and builds all four javadoc
and sources jars. My earlier "the release profile builds clean" was run with
-Dmaven.javadoc.skip=true -Dgpg.skip=true, which skipped both of the things
-Prelease actually adds, and so proved nothing.

Spotless reflowed one paragraph, the shorter method name having moved the
wrap point.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ctgnz
ctgnz merged commit 83183bf into master Sep 30, 2026
1 check passed
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