Skip to content

feat: cheap KDoc lint in check; move dokka link-resolution off the critical path#15

Merged
rasros merged 2 commits into
mainfrom
feat/kdoc-lint
Jun 14, 2026
Merged

feat: cheap KDoc lint in check; move dokka link-resolution off the critical path#15
rasros merged 2 commits into
mainfrom
feat/kdoc-lint

Conversation

@rasros

@rasros rasros commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

What changed

  • New checkKdoc verification task (lexical scan, like checkNativeSafeTestNames), wired into check. It flags:
    • unknown KDoc block tags — lowercase @tags not in the valid set (@param @return @throws …). PascalCase annotations (@Serializable, @Test) are ignored.
    • qualified [links] to a non-existent package — e.g. a typo'd [com.eignex.klause.nope.Thing]. Scoped to the project's own package root (longest common prefix), so sibling deps (com.eignex.skema) and stdlib ([kotlin.*]) are left alone. Handles top-level-function links; skips fenced code and markdown URLs.
  • check no longer depends on lintDocs; it depends on the detekt tasks + checkNativeSafeTestNames + checkKdoc. Dokka's full link resolution moves to the dedicated lintDocs job (consumers already run it in parallel).

Why

lintDocs runs a full dokka generation (the slowest thing in CI) purely to validate KDoc. Detekt already enforces 'public symbols documented'; checkKdoc now covers tag validity + package-existence cheaply in check, so common KDoc mistakes are still caught on a local build. That removes the reason check had to drag dokka onto the critical path — dokka stays as the thorough resolution backstop in its own job.

Testing

./gradlew compileKotlin passes. The scan was validated against klause's full source: 0 false positives, and it correctly catches injected errors (bad @returns tag; […nope.Thing] and […propagatio.someFun] bad packages).

@rasros rasros merged commit b534bee into main Jun 14, 2026
2 checks passed
@rasros rasros deleted the feat/kdoc-lint branch June 14, 2026 10:10
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