Documentation that lives in a wiki and lies the moment the code changes is worse than no docs. Doc generators read your source — types, comments, signatures — and produce a reference site that's regenerated on every build. Pair with tutorials and how-tos written by humans, and you get docs that scale: the API reference is always current, and the conceptual material gets the love it actually deserves.
← Back to Testingfoo() take and return." They're poor at "how do I use this system." Pair them with hand-written guides.| Stack | Generator | Notes |
|---|---|---|
| Java | Javadoc | Built into the JDK. The original. Output: HTML reference site. |
| Kotlin | Dokka | Javadoc for Kotlin; outputs HTML, Markdown, or Javadoc-compatible. |
| .NET | DocFX, Sandcastle (legacy) | DocFX builds API + conceptual docs from XML doc comments. |
| JavaScript / TypeScript | TypeDoc, JSDoc, API Extractor | TypeDoc is the modern default for TS. JSDoc still common for plain JS. |
| Python | Sphinx, mkdocs, pdoc | Sphinx is the heavyweight standard; mkdocs (with mkdocstrings) is friendlier; pdoc is minimalist. |
| Ruby | YARD, RDoc | YARD is the standard with rich tag support. |
| Go | go doc, pkg.go.dev | Built-in. Comments above public symbols are the docs. |
| Rust | rustdoc | Standard, runs doctests as part of the test suite. |
| C / C++ | Doxygen | The veteran. Cross-language; ugly default theme; widely deployed. |
| PHP | phpDocumentor | Standard generator from PHPDoc comments. |
| API specs | OpenAPI / Redoc / Swagger UI | Generates browsable API docs from an OpenAPI file. The reference for HTTP APIs. |
| gRPC / Protobuf | protoc-gen-doc, Buf | Generate from .proto files; integrates with API docs sites. |
| Whole-site | Docusaurus, MkDocs Material, VitePress, Nextra | Combine generated reference + handwritten guides into one site. |
Every public function, class, and module gets a doc comment. Internal functions get them when their behavior isn't obvious. Comments on private helpers nobody calls externally just add noise.
// returns the user on a function called getUser() is noise. Document the why, the contract, the edge cases, the units, the side effects — not the obvious.
In typed languages, a strong signature says most of what a parameter description would. Don't restate types in prose; describe what the value means if it isn't obvious.
Rust's doctests, Python's doctest, Go's testable examples — run every code snippet in the docs as part of the test suite. The docs can't drift; if they did, CI breaks.
The most useful framework for organizing docs:
Trying to put all four into one document fails every time. Different docs serve different needs.
Short markdown files in the repo: title, context, decision, consequences. Capture why a choice was made — the constraints, the alternatives considered, the trade-offs accepted. Six months later, someone asks "why isn't this Postgres?" and the answer is committed history, not folklore.
Docusaurus, MkDocs Material, VitePress, Nextra, Mintlify — combine generated API reference, hand-written guides, search, versioning, and dark mode into one deployable site. Most companies that publish docs externally use one of these.
For HTTP APIs: write the OpenAPI spec; generate the docs (Redoc, Swagger UI), the SDKs (OpenAPI Generator, openapi-typescript), and the validation. The schema is the source of truth.