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.

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 { /* ... */ }

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.