docgen

Docgen

Systematic documentation generation with progress tracking and completeness guarantees. Analyzes code file-by-file, ensures nothing is skipped, and produces structured output per component.

Docgen complements flow-docs — it provides the systematic analysis engine for flow-docs' five-phase workflow. It can also be used standalone for ad-hoc documentation tasks when you need structured, complete documentation without a full flow-docs run.

The core guarantee: every file in scope gets documented. Progress is tracked explicitly ([3/12 files documented]) so you always know what's been covered and what remains.

Workflow

1. Scope the Target

Identify what needs documenting: single file, directory, module, or entire package. Be specific — "the auth module" means every file in that directory.

2. Build the File Manifest

Enumerate every file to document with its path. This is the completeness checklist — no file gets dropped silently. Count them: this is your denominator.

3. Analyze Each File

For each file in the manifest:

• Read the file fully — do not guess from file names
• Extract: purpose, public interface, dependencies, key patterns
• Document using the component template in references/component-template.md:
  • Purpose — one sentence
  • Public Interface — every export with signature and description
  • Dependencies — imports and external services
  • Key Patterns — design patterns, invariants, async considerations
  • Usage Example — minimal, copy-pasteable
  • Notes — edge cases and gotchas (only if they exist)
• Scale the template to complexity: a 10-line utility needs Purpose + Interface + Example; a complex service gets the full template
• Mark the file as documented. Report progress: [3/12 files documented]

4. Cross-Reference

After all files are documented:

• Verify imports and dependencies between documented components
• Note common patterns across the module
• Flag circular dependencies or unclear boundaries

5. Synthesize

Produce the final documentation:

• Module overview (what it does, how components relate)
• Per-component documentation (from step 3)
• Dependency map (what depends on what)

Guardrails

• Don't guess from file names — read the actual code. File and function names lie. Read the implementation before writing any documentation claim.
• Don't skip small files — they often contain critical glue (re-exports, config, type definitions).
• Don't document in batches from memory — read each file fresh. Memory drifts.
• Don't declare completeness without checking the manifest — every file must be checked off.
• Don't restate code without explaining WHY — // increments counter by 1 on counter++ adds no value. Explain the reason behind the logic.

Validation Checkpoint

Before declaring documentation complete, verify:

• Every file in the manifest was documented (none skipped)
• Progress was tracked explicitly throughout
• Cross-references between components are accurate
• Documentation was generated from code reading, not memory

Example

Documenting src/auth/:

Manifest: 4 files — middleware.ts, session.ts, guards.ts, index.ts

[1/4] middleware.ts — Authentication middleware. Extracts JWT from Authorization header, validates with session.verify(), attaches user to request context. Exports: authMiddleware().

[2/4] session.ts — Session management. Creates/verifies JWTs using jsonwebtoken. Token lifetime: 24h. Exports: createSession(), verify().

[3/4] guards.ts — Route guards. requireAdmin() checks user.role === 'admin'. requireAuth() checks session exists. Both use authMiddleware output.

[4/4] index.ts — Re-exports: authMiddleware, requireAdmin, requireAuth, createSession.

Cross-reference: guards.ts depends on middleware.ts output. middleware.ts depends on session.ts. index.ts is the public API surface.

Usage Patterns

• "Document the authentication module"
• "Generate API reference docs for this package"
• "I need complete docs for everything in src/services/"
• "What does this module do and how do I use it?" (single-component mode)

References

• Docgen Strategy — Five-step documentation workflow: scope target, build file manifest, analyze each file, cross-reference, synthesize
• Component Template — Per-component documentation structure with scaling guidance for utilities, services, and config files