code-documenter

仓库原始内容

按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Code Documenter

Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.

When to Use This Skill

Adding docstrings to functions, classes, and modules
Writing OpenAPI/Swagger specs or JSDoc annotations
Creating API documentation for REST or GraphQL endpoints
Building documentation sites or developer portals
Writing getting-started guides, tutorials, and user guides

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.py for doctest blocks; pytest --doctest-modules for module-wide checks
TypeScript/JavaScript: tsc --noEmit to 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

Report - Generate coverage summary

Quick-Reference Examples

Google-style Docstring (Python)

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)

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)

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

Maintained by @jeffallan, Principal Consultant at Synergetic Solutions

Documentation