Generate reference docs from the code

How to do it

For HTTP APIs, use the contract, as in generate docs and clients from the contract. For libraries, generate from types and doc comments with a tool such as TypeDoc, Sphinx autodoc, godoc or Javadoc. For command-line tools, generate the page from the --help text. Write by hand only the guides that explain why and in what order. A project with no public interface for other code, such as a plain website, skips this rule.

Examples

TypeScript example

/**
 * Returns the pickup time for an order placed at `placedAt`.
 * Orders after 15:00 are ready the next morning at 08:00.
 */
export function pickupTime(placedAt: Date): Date { /* ... */ }

Python example

def pickup_time(placed_at: datetime) -> datetime:
    """Return the pickup time for an order placed at placed_at.

    Orders after 15:00 are ready the next morning at 08:00.
    """

How to check

The build regenerates the reference docs and fails when the result differs from the committed or published copy. The generator runs with warnings as errors, such as typedoc --treatValidationWarningsAsErrors with validation.notDocumented on. For Python, add a docstring linter such as Ruff's D1 rules. A public function without a doc comment then fails.

Sources

• OpenAPI Specification 3.2.1

Related rules

• DOC-1 Sort every page into one of four kinds in Documentation
• API-48 Generate docs and clients from the contract in API design
• DOC-13 Generate the settings reference from one schema in Documentation