Skip to content

docs: fix all unresolved KDoc links flagged by the docs build - #17

Merged
KP2048 merged 1 commit into
1.21.xfrom
worktree-docs-link-warnings
Aug 13, 2026
Merged

docs: fix all unresolved KDoc links flagged by the docs build#17
KP2048 merged 1 commit into
1.21.xfrom
worktree-docs-link-warnings

Conversation

@KP2048

@KP2048 KP2048 commented Aug 13, 2026

Copy link
Copy Markdown
Member

Summary

Fixes all 9 distinct "Couldn't resolve link" warnings from the project's own ./gradlew publishDocs run (verified against the pasted local run output). Each traces to one of two root causes:

  • Wrong scope/qualifier: a [bracketed] reference to a same-named symbol that isn't actually in scope from where the doc comment sits - e.g. a parameter mentioned from the enclosing class's own doc instead of the function's (configFolder, modToClasses/side - the latter's doc moved onto run() itself where those really are parameters), a member that only exists on a subclass (DataSpec.init's doc referencing CategorySpec's own subcategories), or a flat-out wrong qualifier (ClientDataSpec's [DataSpec.onClient] - onClient is a top-level function, not a DataSpec member).
  • Cross-module references: bare/simple-qualified links to a symbol in a different Dokka module fail even when it's a real, correctly-directed dependency (ConfigSpec.Server, TextureStates, ADataGeneratorPlatform.isDataGen) - fully qualifying them resolves fine. A reference to a symbol in the wrong direction (core-common mentioning a gametest-only class, gametest-common mentioning a per-loader-internal or the separate downstream test app's class) can't resolve at all regardless of qualification - those become plain backtick code spans instead.

Also removed a stray, misattached doc comment on AConditionBuilder (described the infix and two declarations below it, but Dokka attached it to the adjacent vararg and instead, which has no other parameter) and a stale [onRelease] mention in Interactable.pressable's doc - that parameter doesn't exist (release is observed via collectIsPressedAsState, not a callback, as the doc's own next sentence already said).

All changes are doc-comment-only (or a doc-comment relocation in one case) - no logic changes.

Verification

./gradlew dokkaGenerateModuleMkdocs previously logged all 9 warnings; a full rerun after these fixes is clean. Also verified a full compileKotlin across every module.

Separate finding (not fixed here)

While looking into this I found the docs workflow's gh-pages branch push is failing GitHub's automatic Pages build-and-deploy (a separate pages-build-deployment workflow, not this repo's own docs.yaml) with Artifact could not be deployed... content does not contain any hard links, symlinks. The repo's Pages source is currently "Deploy from a branch" (legacy) - mike (the doc-versioning tool docs.yaml uses) writes version-alias symlinks into gh-pages, which GitHub's actions/deploy-pages rejects. Fixing this means either changing the repo's Pages source to "GitHub Actions" (and adding explicit upload-pages-artifact/deploy-pages steps to docs.yaml) or reconfiguring mike to avoid symlinked aliases - a real infrastructure decision, flagging separately rather than changing repo settings in this PR.

🤖 Generated with Claude Code

Every one traces to one of two causes:
- A [bracketed] reference to a same-named symbol that isn't actually in
  scope from where the doc comment sits - a parameter name mentioned from
  the enclosing class's own doc instead of the function's (configFolder,
  modToClasses/side - moved onto run() itself), a member that only exists
  on a subclass (DataSpec.init documenting CategorySpec's own
  subcategories), or a wrong qualifier (ClientDataSpec's [DataSpec.
  onClient] - onClient is a top-level function, not a DataSpec member).
- A genuinely cross-module reference. Bare/simple-qualified links to a
  symbol in a different Dokka module fail even when it's a real, otherwise
  fine dependency (ConfigSpec.Server, TextureStates,
  ADataGeneratorPlatform.isDataGen) - fully qualifying them resolves fine.
  A reference to a symbol that's the *wrong* direction (core-common's
  ComposeScreen.kt mentioning gametest-only AClientGameTestHarness,
  gametest-common's NoOpGameTest mentioning a fabric/neoforge-only
  AGameTestPlatformInternal or the separate downstream test app's
  TestScreenGameTest) can't resolve at all regardless of qualification -
  those become plain backtick code spans instead.

Also removed a stray, misattached doc comment fragment on
AConditionBuilder (described the infix `and` two positions below it, but
Dokka attached it to the adjacent vararg `and` instead, which has no
`other` parameter) and a stale [onRelease] mention in Interactable.pressable's
doc - that parameter doesn't exist (release is observed via
collectIsPressedAsState, not a callback, as the very next sentence
already said).

Verified: `./gradlew dokkaGenerateModuleMkdocs` previously logged all 9
"Couldn't resolve link" warnings (confirmed against the project's own
`publishDocs` output); a full rerun after these fixes is clean. Also
verified a full `compileKotlin` across every module - all doc-comment-only
changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings August 13, 2026 04:04

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@KP2048
KP2048 merged commit 308d457 into 1.21.x Aug 13, 2026
4 of 6 checks passed
@KP2048
KP2048 deleted the worktree-docs-link-warnings branch August 13, 2026 04:08
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.

2 participants