docs: fix all unresolved KDoc links flagged by the docs build - #17
Merged
Conversation
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>
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.
Summary
Fixes all 9 distinct "Couldn't resolve link" warnings from the project's own
./gradlew publishDocsrun (verified against the pasted local run output). Each traces to one of two root causes:[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 ontorun()itself where those really are parameters), a member that only exists on a subclass (DataSpec.init's doc referencingCategorySpec's ownsubcategories), or a flat-out wrong qualifier (ClientDataSpec's[DataSpec.onClient]-onClientis a top-level function, not aDataSpecmember).ConfigSpec.Server,TextureStates,ADataGeneratorPlatform.isDataGen) - fully qualifying them resolves fine. A reference to a symbol in the wrong direction (core-commonmentioning agametest-only class,gametest-commonmentioning 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 infixandtwo declarations below it, but Dokka attached it to the adjacent varargandinstead, which has nootherparameter) and a stale[onRelease]mention inInteractable.pressable's doc - that parameter doesn't exist (release is observed viacollectIsPressedAsState, 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 dokkaGenerateModuleMkdocspreviously logged all 9 warnings; a full rerun after these fixes is clean. Also verified a fullcompileKotlinacross every module.Separate finding (not fixed here)
While looking into this I found the
docsworkflow'sgh-pagesbranch push is failing GitHub's automatic Pages build-and-deploy (a separatepages-build-deploymentworkflow, not this repo's owndocs.yaml) withArtifact 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 tooldocs.yamluses) writes version-alias symlinks intogh-pages, which GitHub'sactions/deploy-pagesrejects. Fixing this means either changing the repo's Pages source to "GitHub Actions" (and adding explicitupload-pages-artifact/deploy-pagessteps todocs.yaml) or reconfiguringmiketo avoid symlinked aliases - a real infrastructure decision, flagging separately rather than changing repo settings in this PR.🤖 Generated with Claude Code