# Code Documentation

> Generates and improves code documentation for Python projects. Use this skill whenever the user asks to document code, add docstrings, add type hints, or improve existing comments. Trigger even for partial requests like "document this function", "add comments to my file", "write a README for this project", or "explain what this module does". Also trigger when the user shares code and asks "what does this do?" in a way that implies they want documented output rather than a one-line explanation.

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

---


# Code Documentation Skill

Create clear, concise, and informative, accurate, idiomatic, and useful documentation — not boilerplate. Every piece of documentation you write should help the next developer understand *why*, not just *what*.

---

## Step 1: Detect Context and Scope

Before writing anything, scan the existing code and any existing docs to detect:

1. **Style already in use** — check for: Google style, NumPy/Sphinx style, reStructuredText, or no style
2. **Existing doc coverage** — are some things documented? Mimic that style exactly.
3. **Project type** — library/package, application, CLI tool, API server, etc.
4. **Audience** — internal tool vs public-facing API (affects verbosity)

If no style exists, default to **Google style docstrings**.

**Always announce your detected style** to the user before writing, e.g.:
> "I can see you're using Google-style docstrings — I'll match that throughout."

---

## Step 2: Determine Scope

Ask or infer which documentation type(s) are needed. See the full guidance in:
- `references/inline-docs.md` — docstrings and inline comments
- `references/readme-and-api.md` — README files and API reference docs
- `references/architecture.md` — high-level architecture and design docs

For multi-type requests (e.g. "document this whole project"), tackle in this order:
1. Inline docs first (they inform everything else)
2. API reference
3. README
4. Architecture doc

---

## Step 3: Write Documentation

### Universal rules (apply to all doc types)

- **Document intent, not mechanics.** If the code says `i += 1`, don't write `# increment i`.
- **Keep it current.** If you see a comment that contradicts the code, fix the comment.
- **Don't over-document.** Private helpers and obvious one-liners rarely need docs.
  Focus effort on: public APIs, complex logic, non-obvious side effects, error conditions.
- **Be consistent.** Use the same style, tense, and voice throughout a file.
- **Examples > prose** for complex APIs. A 3-line usage example beats a paragraph of explanation.

### What to always include in function/method docs

| Element | Python (Google) |
|---|---|
| One-line summary | First line of docstring |
| Parameters | `Args:` block |
| Return value | `Returns:` block |
| Exceptions/errors | `Raises:` block |
| Usage example | `Example:` block |

Only include sections that apply — don't add empty `Raises:` if nothing is raised.

---

## Step 4: Output Format

- **Inline docs**: Output the full modified file (or clearly-delimited diff if file is large).
  Never output just the docstring in isolation — always show it in context.
- **README**: Output as Markdown. See `references/readme-and-api.md` for structure.
- **API reference**: Output as Markdown table or structured Markdown. See `references/readme-and-api.md`.
- **Architecture doc**: Output as Markdown with diagrams (Mermaid) where helpful. See `references/architecture.md`.

## Step 5: Offer Follow-ups

After completing documentation, offer at least one relevant next step, e.g.:
- "Want me to generate an API reference from these docstrings?"
- "Should I write a README for this module next?"
- "Want me to add usage examples to the more complex functions?"