An API reference style guide: one shape for every entry

What it is

A reference entry describes one function, endpoint, type or option. A style guide for reference material is a short internal document that fixes, for every entry, the sections and their order, the form of the opening sentence, and the wording of recurring facts. Microsoft's reference guidance (cited) lists the sections of a reference article in a fixed order: title and description, declaration or syntax, parameters, return value, remarks, example, requirements and see-also, with exceptions or error codes where the element can raise them; each parameter carries its data type and, where appropriate, whether it is required or optional, and the description must not merely repeat the element name. Google's guidance for API reference comments (cited) notes that only the first sentence of a description appears in summary sections and indexes, so the most important information goes there, and that a deprecation must say what to use instead. OpenAPI (cited) separates a summary, a short statement of what an operation does, from a longer description.

Why it matters

Reference material is read by lookup, not in order. A reader who has learned where the return value is in one entry expects it in the same place in the next; an agent extracting parameters relies on the same regularity. Generated references (from docstrings, OpenAPI, doc comments) reproduce whatever discipline the source has, so the style guide is applied at the source.

How to apply

• First sentence: a complete statement of what the thing does, in the third person, starting with a verb ("Returns the ...", "Creates a ..."), that makes sense alone in an index.
• Parameters: name, type, required or optional, default, allowed range or format, and what happens at the boundary. A parameter without a stated default has an undocumented behaviour.
• Return value: type, meaning, and the empty, null or not-found cases.
• Errors: one line per condition, in the form "condition: error raised or status returned"; link to the shared error format.
• Remarks: ordering guarantees, idempotency, side effects, rate limits, thread safety. Nothing that belongs to a tutorial.
• Example: one minimal, runnable call with its output; keep it executed in CI where possible.
• Deprecation: the replacement, the version since, and the removal plan, in the first sentence.
• Terminology: use the glossary's preferred term for every concept and the same units and date formats throughout.

Pitfalls

Summaries that repeat the name ("getUser: gets the user"). Describing the implementation instead of the contract. Constraints stated only in prose that a validator enforces differently. Examples that no longer run. Different section orders per author, which is the problem the guide exists to remove.