|
| 1 | +--- |
| 2 | +name: public-api-documenter |
| 3 | +description: > |
| 4 | + Audit public API for missing KDoc. Use when asked to check documentation |
| 5 | + coverage, find undocumented public members, or before a release to ensure |
| 6 | + all public API has KDoc. Trigger for: "check kdoc", "missing docs", |
| 7 | + "audit documentation", "public api docs". Skip for: test code, internal |
| 8 | + modules, non-Kotlin files. |
| 9 | +allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/find-missing-kdoc.py*) |
| 10 | +--- |
| 11 | + |
| 12 | +# Public API Documenter |
| 13 | + |
| 14 | +Audit the public API surface for missing KDoc documentation. |
| 15 | + |
| 16 | +## How to run |
| 17 | + |
| 18 | +```bash |
| 19 | +python3 ${CLAUDE_SKILL_DIR}/scripts/find-missing-kdoc.py |
| 20 | +python3 ${CLAUDE_SKILL_DIR}/scripts/find-missing-kdoc.py --verbose |
| 21 | +``` |
| 22 | + |
| 23 | +## When to use |
| 24 | + |
| 25 | +- Before a release, to verify all public API members are documented |
| 26 | +- During code review, when new public API is introduced |
| 27 | +- When asked to "check docs", "audit kdoc", or "find missing documentation" |
| 28 | + |
| 29 | +## When to skip |
| 30 | + |
| 31 | +- Test code or internal modules — only public ABI matters |
| 32 | +- Non-Kotlin files or documentation-only changes |
| 33 | +- When the user is asking about code behavior, not documentation coverage |
| 34 | + |
| 35 | +## Exclusions |
| 36 | + |
| 37 | +The script automatically skips members that should not have KDoc: |
| 38 | + |
| 39 | +- **`override` methods/properties** — KDoc belongs on the interface or superclass |
| 40 | +- Auto-generated members: `equals`, `hashCode`, `toString`, `copy`, `componentN`, `serializer`, getters/setters |
| 41 | +- Synthetic and mangled members (inline class name-mangled signatures) |
| 42 | +- `Companion`, `DefaultImpls`, `$$serializer` inner classes |
| 43 | + |
| 44 | +## KDoc guidelines |
| 45 | + |
| 46 | +- Wrap KDoc to keep lines under 100 chars; wrap to multi-line if longer |
| 47 | +- Keep docs concise — focus on "what" and "why", not implementation details |
| 48 | +- Do NOT add KDoc to `override` members; document the contract on the declaring interface/superclass |
| 49 | +- For DSL builder internal `build()` methods (`@PublishedApi`), a one-liner is sufficient |
| 50 | +- For transport `start()`/`close()`/`send()`, document the lifecycle contract on the `Transport` interface |
| 51 | +- Don't add KDoc to data class auto-generated members |
| 52 | + |
| 53 | +## Modules checked |
| 54 | + |
| 55 | +- `kotlin-sdk-core` — Protocol types, JSON-RPC, Transport abstraction |
| 56 | +- `kotlin-sdk-client` — MCP client implementation |
| 57 | +- `kotlin-sdk-server` — MCP server implementation |
| 58 | +- `kotlin-sdk-testing` — In-memory test transports |
0 commit comments