code-documentation
npx machina-cli add skill plaited/development-skills/code-documentation --openclawCode Documentation Skill
Purpose
This skill provides TSDoc format templates, type documentation guidelines, and maintenance workflows. Use this when:
- Writing or editing TSDoc comments for any function, type, or module
- Reviewing documentation quality
- Creating comprehensive API documentation
- Documenting complex type structures
- Cleaning up non-compliant comments (performance notes, timestamps, inline explanations)
- Synchronizing out-of-sync TSDoc with code changes
- Removing orphaned documentation for deleted code
Key Standard: No @example sections - tests and stories serve as living examples.
Quick Reference
- Creating TSDoc: See workflow.md for the generation workflow
- Maintaining TSDoc: See maintenance.md for cleanup and sync guidelines
This skill contains detailed templates for:
- Public API Functions
- Internal Module Documentation
- Public and Internal Types
- Helper Functions
- Behavioral Programming Functions
- Special Annotations (Security, Performance, Deprecated)
- Type Documentation (Complex Objects, Unions, Functions, Utilities, Branded Types, etc.)
Navigation
- workflow.md - TSDoc generation workflow (4 phases)
- maintenance.md - Comment policy, sync tasks, orphaned doc handling
- public-api-templates.md - Templates for public-facing APIs
- internal-templates.md - Templates for internal code and modules
- type-documentation.md - Comprehensive type documentation templates
Related Skills
- typescript-lsp: Use for type verification and discovery during documentation workflow. Essential for Phase 1 (type analysis) and Phase 2 (usage discovery) of the TSDoc generation process. Run
lsp-hoverto verify signatures,lsp-referencesto find usages, andlsp-symbolsto understand file structure.
Source
git clone https://github.com/plaited/development-skills/blob/main/skills/code-documentation/SKILL.mdView on GitHub Overview
This skill provides standardized TSDoc templates, type documentation guidelines, and maintenance workflows for TypeScript/JavaScript code. It helps ensure consistent, high-quality docs across public APIs, internal modules, and complex types, while keeping comments synchronized with code changes.
How This Skill Works
It offers templates for various documentation scopes (public API, internal modules, types, and helpers), plus maintenance guidance to clean up non-compliant notes and to sync docs with code. The workflow references workflow.md and maintenance.md to describe generation, cleanup, and orphaned doc handling, and it integrates with tooling like TypeScript LSP for verification.
When to Use It
- Writing or editing TSDoc comments for any function, type, or module
- Reviewing documentation quality
- Creating comprehensive API documentation
- Documenting complex type structures
- Cleaning up non-compliant comments (performance notes, timestamps, inline explanations)
Quick Start
- Step 1: Open the appropriate template (public-api-templates.md, internal-templates.md, or type-documentation.md) from references
- Step 2: Populate the doc blocks with accurate parameter, return, and type details per TSDoc rules
- Step 3: Run the generation workflow and maintenance checks to sync docs with code and verify using lsp tooling
Best Practices
- Follow the no @example standard; tests and stories serve as living examples
- Use the provided templates for each doc type (public API, internal, types, etc.)
- Keep TSDoc comments synchronized with code changes
- Remove non-compliant notes (timestamps, inline explanations) as part of maintenance
- Validate documentation with TypeScript LSP checks during review
Example Use Cases
- Documenting a public API function with parameter and return descriptions using the public API template
- Documenting an internal module with module-level notes and usage hints
- Documenting a complex type (unions, branded types) with type documentation templates
- Annotating a function with a security or performance note in Special Annotations
- Cleaning up orphaned documentation after a code deletion or refactor
