# Code Documentation

> Generate docs: README, API reference, architecture, guides.

- Skill: `hezaohezao/code-documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hezaohezao/code-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hezaohezao/code-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: HezaoHezao (https://skillmd.com/u/hezaohezao)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/hezaohezao/code-documentation

---


# Code Documentation

## Overview

Generate professional, comprehensive documentation for software projects,
codebases, libraries, and APIs. Follows best practices from React, Django,
Stripe, Kubernetes to produce accurate, well-structured docs.

## When to Use

- User asks to "document", "create docs", or "write documentation" for code
- User requests a README, API reference, or developer guide
- User shares a codebase and wants documentation generated
- User asks to improve or update existing documentation
- User needs architecture documentation with diagrams
- User requests a changelog or migration guide

## Workflow

### Phase 1: Codebase Analysis

#### Step 1.1: Project Discovery

| Field | How to Determine |
|-------|-----------------|
| **Language(s)** | File extensions, `package.json`, `pyproject.toml`, `go.mod` |
| **Framework** | Dependencies (React, Django, Express, Spring) |
| **Build System** | `Makefile`, `CMakeLists.txt`, `webpack.config.js` |
| **Package Manager** | npm/yarn/pnpm, pip/uv/poetry, cargo |
| **Project Structure** | Map directory tree |
| **Entry Points** | main files, CLI entry points, exported modules |
| **Existing Docs** | README, docs/, wiki, inline docs |

```bash
# Discover project structure
list_dir(".")
# Read key files
read_file("package.json")  # or pyproject.toml, go.mod, etc.
# Find all source files
bash("find . -name '*.py' -not -path '*/venv/*' -not -path '*/.venv/*' | head -30")
```

#### Step 1.2: Code Structure Analysis

```bash
# Find entry points
bash("grep -rl 'if __name__' --include='*.py' . | head -10")

# Find API routes/endpoints
bash("grep -rn '@app.route\|@router\.\|def get\|def post' --include='*.py' . | head -20")

# Find exported modules
bash("grep -rn 'export\|module.exports' --include='*.js' --include='*.ts' . | head -20")

# Find classes (for API reference)
bash("grep -rn '^class ' --include='*.py' . | head -20")
```

### Phase 2: Documentation Generation

#### README.md

```markdown
# Project Name

> One-line description

## Features
- Feature 1
- Feature 2

## Installation
\`\`\`bash
pip install project-name
\`\`\`

## Quick Start
\`\`\`python
from project import Client
client = Client()
result = client.do_thing()
\`\`\`

## API Reference
### `Client.do_thing(param: str) -> Result`
Description of what this does.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| param | str | Yes | The input |

## Configuration
| Key | Default | Description |
|-----|---------|-------------|

## Contributing
See CONTRIBUTING.md

## License
MIT
```

#### API Reference

For each public function/class:
- Signature (parameters, return type)
- Description
- Parameters table
- Return value
- Example usage
- Exceptions raised

#### Architecture Documentation

- System overview diagram (use `architecture-diagram` skill)
- Component descriptions
- Data flow
- Key design decisions (ADR format)

### Phase 3: Review

- [ ] All public APIs documented
- [ ] Examples are runnable
- [ ] Installation instructions tested
- [ ] No broken links
- [ ] Language-appropriate conventions (docstrings, JSDoc, GoDoc)
- [ ] Architecture diagram included for complex projects

## Documentation Conventions by Language

| Language | Inline Format | Reference Format |
|----------|--------------|-----------------|
| Python | docstrings (Google/NumPy style) | Sphinx, MkDocs |
| JavaScript/TypeScript | JSDoc/TSDoc | JSDoc, TypeDoc |
| Go | GoDoc comments | godoc |
| Java | Javadoc | javadoc |
| Rust | rustdoc (`///`) | rustdoc |

## Changelog Generation

```bash
# From git log
bash("git log --oneline --no-decorate v1.0.0..HEAD | head -50")

# Generate changelog from commits
bash("git log v1.0.0..HEAD --pretty=format:'- %s (%h)' --no-merges")
```

## Pitfalls

- **Stale docs**: documentation must match code. If code changed, docs must
  update. Note the commit/version the docs were generated from.
- **No examples**: documentation without runnable examples is useless. Always
  include copy-pasteable examples.
- **Over-documenting internals**: document public API, not implementation
  details. Internal code should have inline comments, not API docs.
- **No table of contents**: for long docs, include a TOC with anchor links.
- **Missing prerequisites**: list all dependencies, environment requirements,
  and minimum versions.