api-reference

API Reference Generator Guidance

Philosophy

API reference docs are the Reference quadrant of the Diataxis framework — information-oriented, accurate, and complete. They document every public function, class, method, parameter, and return type.

This skill does not generate API docs directly — that's the job of language-specific tools (TypeDoc, Sphinx, godoc, rustdoc). Instead, it provides configuration guidance and comment conventions so those tools produce high-quality output.

Language Detection

Detect the project language to recommend the appropriate tool:

# Check for language-specific manifest files
[ -f "package.json" ] && echo "javascript/typescript"
[ -f "tsconfig.json" ] && echo "typescript (confirmed)"
[ -f "pyproject.toml" ] || [ -f "setup.py" ] && echo "python"
[ -f "go.mod" ] && echo "go"
[ -f "Cargo.toml" ] && echo "rust"

TypeScript / JavaScript (TypeDoc)

Tool: TypeDoc — generates HTML or Markdown documentation from TypeScript source code and JSDoc comments.

Installation

npm install --save-dev typedoc

Configuration

Create typedoc.json in the project root:

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeInternal": true,
  "categorizeByGroup": true,
  "sort": ["source-order"]
}

For Markdown output (recommended for GitHub-hosted docs):

npm install --save-dev typedoc-plugin-markdown

TSDoc Comment Conventions

/**
 * Generates a marketing-friendly README from codebase analysis.
 *
 * Scans the project for features, translates them into benefit-driven
 * language, and outputs a complete README.md following the 4-question
 * framework.
 *
 * @param options - Configuration for README generation
 * @param options.projectPath - Path to the project root
 * @param options.format - Output format: 'github' | 'npm' | 'pypi'
 * @returns The generated README content as a string
 * @throws {ProjectNotFoundError} If projectPath doesn't exist
 *
 * @example
 * ```typescript
 * const readme = await generateReadme({
 *   projectPath: './my-project',
 *   format: 'github'
 * })
 * ```
 *
 * @see {@link FeatureExtractor} for the scanning workflow
 * @since 1.0.0
 */
export async function generateReadme(options: ReadmeOptions): Promise<string> {