code-documenter
Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- code-documenter
- license
- MIT
- metadata
- { "role": "specialist", "scope": "implementation", "author": "https://github.com/Jeffallan", "domain": "quality", "version": "1.1.0", "triggers": "documentation, docstrings, OpenAPI, Swagger, JSDoc, comments, API docs, tutorials, user guides, doc site", "output-format": "code", "related-skills": "spec-miner, fullstack-guardian, code-reviewer" }
- description
- Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.
02 资源文件 8
- 参考文档references/api-docs-fastapi-django.md4.1 KB
- 参考文档references/api-docs-nestjs-express.md4.8 KB
- 参考文档references/coverage-reports.md3.0 KB
- 参考文档references/documentation-systems.md5.9 KB
- 参考文档references/interactive-api-docs.md10.0 KB
- 参考文档references/python-docstrings.md2.9 KB
- 参考文档references/typescript-jsdoc.md3.0 KB
- 参考文档references/user-guides-tutorials.md10.7 KB
03 SKILL.md 正文
Code Documenter
Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
When to Use This Skill
Applies to any task involving code documentation, API specs, or developer-facing guides. See the reference table below for specific sub-topics.
Core Workflow
- Discover - Ask for format preference and exclusions
- Detect - Identify language and framework
- Analyze - Find undocumented code
- Document - Apply consistent format
- Validate - Test all code examples compile/run:
- Python:
python -m doctest file.pyfor doctest blocks;pytest --doctest-modulesfor module-wide checks - TypeScript/JavaScript:
tsc --noEmitto confirm typed examples compile - OpenAPI: validate spec with
npx @redocly/cli lint openapi.yaml - If validation fails: fix examples and re-validate before proceeding to the Report step
- Python:
- Report - Generate coverage summary
Quick-Reference Examples
Google-style Docstring (Python)
def fetch_user(user_id: int, active_only: bool = True) -> dict:
"""Fetch a single user record by ID.
Args:
user_id: Unique identifier for the user.
active_only: When True, raise an error for inactive users.
Returns:
A dict containing user fields (id, name, email, created_at).
Raises:
ValueError: If user_id is not a positive integer.
UserNotFoundError: If no matching user exists.
"""
NumPy-style Docstring (Python)
def compute_similarity(vec_a: np.ndarray, vec_b: np.ndarray) -> float:
"""Compute cosine similarity between two vectors.
Parameters
----------
vec_a : np.ndarray
First input vector, shape (n,).
vec_b : np.ndarray
Second input vector, shape (n,).
Returns
-------
float
Cosine similarity in the range [-1, 1].
Raises
------
ValueError
If vectors have different lengths.
"""
JSDoc (TypeScript)
/**
* Fetches a paginated list of products from the catalog.
*
* @param {string} categoryId - The category to filter by.
* @param {number} [page=1] - Page number (1-indexed).
* @param {number} [limit=20] - Maximum items per page.
* @returns {Promise<ProductPage>} Resolves to a page of product records.
* @throws {NotFoundError} If the category does not exist.
*
* @example
* const page = await fetchProducts('electronics', 2, 10);
* console.log(page.items);
*/
async function fetchProducts(
categoryId: string,
page = 1,
limit = 20
): Promise<ProductPage> { ... }
Reference Guide
Load detailed guidance based on context:
| Topic | Reference | Load When |
|---|---|---|
| Python Docstrings | references/python-docstrings.md |
Google, NumPy, Sphinx styles |
| TypeScript JSDoc | references/typescript-jsdoc.md |
JSDoc patterns, TypeScript |
| FastAPI/Django API | references/api-docs-fastapi-django.md |
Python API documentation |
| NestJS/Express API | references/api-docs-nestjs-express.md |
Node.js API documentation |
| Coverage Reports | references/coverage-reports.md |
Generating documentation reports |
| Documentation Systems | references/documentation-systems.md |
Doc sites, static generators, search, testing |
| Interactive API Docs | references/interactive-api-docs.md |
OpenAPI 3.1, portals, GraphQL, WebSocket, gRPC, SDKs |
| User Guides & Tutorials | references/user-guides-tutorials.md |
Getting started, tutorials, troubleshooting, FAQs |
Constraints
MUST DO
- Ask for format preference before starting
- Detect framework for correct API doc strategy
- Document all public functions/classes
- Include parameter types and descriptions
- Document exceptions/errors
- Test code examples in documentation
- Generate coverage report
MUST NOT DO
- Assume docstring format without asking
- Apply wrong API doc strategy for framework
- Write inaccurate or untested documentation
- Skip error documentation
- Document obvious getters/setters verbosely
- Create documentation that's hard to maintain
Output Formats
Depending on the task, provide:
- Code Documentation: Documented files + coverage report
- API Docs: OpenAPI specs + portal configuration
- Doc Sites: Site configuration + content structure + build instructions
- Guides/Tutorials: Structured markdown with examples + diagrams
Knowledge Reference
Google/NumPy/Sphinx docstrings, JSDoc, OpenAPI 3.0/3.1, AsyncAPI, gRPC/protobuf, FastAPI, Django, NestJS, Express, GraphQL, Docusaurus, MkDocs, VitePress, Swagger UI, Redoc, Stoplight
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
youtube-downloader
Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
template-skill
Replace with description of the skill and when Claude should use it.
tailored-resume-generator
Analyzes job descriptions and generates tailored resumes that highlight relevant experience, skills, and achievements to maximize interview chances
slack-gif-creator
Toolkit for creating animated GIFs optimized for Slack, with validators for size constraints and composable animation primitives. This skill applies when users request animated GIFs or emoji animations for Slack from descriptions like "make me a GIF for Slack of X doing Y".