maintain-jsdocs
/maintain-jsdocs
Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.
Original author description
Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.
How it works
- Scope
- The contract
- Workflow
- Quality bar
- References
SKILL.md preview
---
name: maintain-jsdocs
description: 'Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.'
---
# Maintain JSDocs
## Scope
- JSDoc only. README and docs pages are out of scope unless the request says otherwise.
- Covers **all exported declarations** in every source file of a package, not just what `index.ts` re-exports, plus module augmentation members in plugin packages.
- Includes `@internal` exports: gen-api skips them, but their JSDoc is still maintained.
- Excludes `dist/`, `coverage/`, `*.test.ts`, `*.spec.ts`, `pika.gen.*`, `generated-*.ts`.
- English only.
Package directories in this repository: !`grep -o "dir: '[^']*'" "${CLAUDE_PROJECT_DIR}/scripts/_skill-shared/index.ts" | sed "s/dir: //;s/'//g" | tr '\n' ' '`
Ask which packages to process when the request does not say; use `AskUserQuestion` if it is available.
## The contract
`gen-api-docs` extracts JSDoc from `packages/*/src/index.ts` via the TypeScript compiler API. Every gap renders as "Missing JSDoc summary." on a published page, so the gap list is the definition of done:
| Export kind | Required |
|---|---|
| Function | Summary + `@param` description per parameter |
| Interface | Summary + description per property |
| Type alias | Summary |
| Constant / Variable | Summary |
| Class | Summary + description per public property and method, including constructor `@param`s |
| Module augmentation member | Description per property |
`collectCoverageGaps` in `scripts/maintain-docs/gen-api-docs.ts` is the authority. Read it when a gap report is surprising.
## Workflow
1. **Find the gaps.** `pnpm maintain-docs:gen-api` lists every coverage gap by package and symbol. Work from that list.
2. **Write the JSDoc** directly in the source file, reading the implementation and its call sites first.
3. **Validate**:
```bash
pnpm maintain-jsdocs:lint --packages <name>... # corruption check
pnpm maintain-docs:gen-api # zero-gap check
pnpm --filter @pikacss/<name> typecheck
```
Repeat until gen-api reports `✅ No JSDoc coverage gaps detected.`
For large scopes, process one package per subagent in parallel rather than sweeping serially.
### Full restart (opt in, destructive)
`pnpm maintain-jsdocs:scaffold --packages <name>...` **replaces** existing JSDoc on every exported declaration with `@todo FILL:` templates, then you fill each marker and remove the tag.
Use it only when the existing JSDoc for a package is being rewritten wholesale on purpose. It discards good prose along with bad, so gap-driven editing is the default.
## Quality bar
Beyond zero-gap: every sentence must add something the type signature does not already say. "Returns the resolved engine configuration after plugin normalization" over "Returns a ResolvedEngineConfig".
Repo-specific conventions the generator and readers rely on:
- `@default` on every optional interface property — the effective value or behavior when omitted, literals in inline code.
- `@example` with a fenced `ts` block when usage is ordering-sensitive, composable, or easy to misuse.
- `@remarks` for lifecycle, hook interaction, and cross-package relationships — this is where PikaCSS's non-obvious behavior belongs.
- Each JSDoc tag starts its own real line. Never emit literal `\n` or `\t` inside a comment; `maintain-jsdocs:lint` fails on both.
```ts
declare module '@pikacss/core' {
interface EngineConfig {
/**
* CSS reset style injected as a preflight, before utility styles.
*
* @default 'tailwind-preflight'
*/
reset?: ResetStyle
}
}
```
## References
- [workflow-rules.md](references/workflow-rules.md) — format conventions and the quality checklist.
Files in this package (2)
- SKILL.md 4 KB
- references/workflow-rules.md 7 KB
Versions
The database has no other skills named maintain-jsdocs.
Database snapshot: 13.11.2026 · package version a1244b534f76 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 96jsdocs
Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics. - 100write-component-jsdocs
Guide for writing JSDoc comments on vapor-ui components and their props. Use when adding, reviewing, or fixing JSDoc on component tsx files or css.ts variant files. Covers where to place comments based on component pattern — standalone, compound root, compound sub-part,… - 100jsdoc-comment-generator
Generate jsdoc comment generator operations. Auto-activating skill for Technical Documentation. Triggers on: jsdoc comment generator, jsdoc comment generator Part of the Technical Documentation skill category. Use when working with jsdoc comment generator functionality. Trigger… - 100jsdoc
JSDoc - documentation generator for JavaScript with type annotations. USE WHEN: user mentions "JSDoc", "JavaScript documentation", asks about "documenting JavaScript", "type hints", "jsdoc comments", "API documentation generation" DO NOT USE FOR: TypeScript - use `jsdoc-tsdoc`… - 95jsdoc-guide
JSDoc writing rules for AI-powered documentation generation. Use when writing JSDoc, documenting functions, or adding code comments. - 100documentation
Generate docstrings, JSDoc, API docs, and README updates that reflect current code. Use when: docs, docstring, JSDoc, README, API docs, document this, add documentation.