Skip to content

Commit be065b9

Browse files
committed
feat(docs): Public API Documenter skill
- Introduced a `Public API Documenter` claude skill to audit missing KDoc in public API members.
1 parent 384064e commit be065b9

2 files changed

Lines changed: 409 additions & 0 deletions

File tree

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
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

Comments
 (0)