api-details-001 must API docs In reference documentation, describe methods using third-person singular present tense (Creates, Gets, Lists) rather than the imperative or infinitive form.
Overview and remarks
After the intro, a description has two more jobs. The overview says when to use the element and how it relates to its neighbors. The remarks add the behavior a caller cannot infer from the signature. This guide uses overview for a role, not a heading: the overview is whatever the description says after the intro, whether your build renders it as the rest of the description, as a Summary or Overview section, or rolls it into the remarks. Remarks are a section of their own in most builds and the tail of the description in the rest. These rules cover what goes in each part, what stays out, and how the text is phrased. Reference text does not need contractions; use one where the sentence sounds stiff without it. What to document for each member lives on the members and parameters page.
Third-person verbs for methods
Section titled “Third-person verbs for methods”Examples
- ✓
createUser: Creates a user in the current project. - ✗
createUser: Create a user in the current project.
Rationale
A method description states what the method does, so third-person present (Creates) reads as behavior rather than a command to the reader.
Present tense in descriptions
Section titled “Present tense in descriptions”api-details-002 should API docs Write descriptions in present tense.
Examples
- ✓ Returns the list of open sessions.
- ✗ Will return the list of open sessions.
Rationale
Reference describes how the API behaves now, so present tense states that behavior directly.
Scope the overview to use and relationships
Section titled “Scope the overview to use and relationships”api-details-003 should API docs In the overview, or the section your build uses for it, say when to use the element and how it relates to its neighbors: the elements it works with, the alternatives, and the members a caller reaches for first. Don’t repeat member detail or syntax that the member sections and the syntax block already show.
Examples
- ✓ Use a
RetryPolicyobject with any client that accepts a policy; for a one-off request, pass a timeout instead. ARateLimiterobject throttles requests before they are sent, so the two are often used together. - ✗ The
RetryPolicyclass has amaxAttemptsproperty of typeint, adelayproperty of typeDuration, and a constructor that takes both.
Rationale
The overview is where a reader decides whether this element is the one they need. Use and relationships answer that; member detail is one click away and drifts out of date when it is repeated.
Link to guides for concepts
Section titled “Link to guides for concepts”api-details-004 should API docs When the overview or remarks depend on a concept that a developer guide explains, link to the guide and restate only what the reader needs to understand the element. Don’t teach the concept on the reference page.
Examples
- ✓ A refresh token extends the session without a new sign-in. For the full lifecycle, see the authentication guide.
- ✗ A refresh token is a credential that the authorization server issues alongside the access token so that the client can obtain a new access token when the current one expires, without involving the user again, which matters because access tokens are deliberately short-lived to limit the damage if one leaks.
Rationale
A reference page is read by someone who already chose the element and wants its facts. Concept teaching belongs where a reader learns, and a second copy on the reference page drifts from the first.
Keep each member’s facts in its own entry
Section titled “Keep each member’s facts in its own entry”api-details-005 should API docs Document a parameter, return value, or exception in its own entry, not in the remarks and not in another member’s description. Where another entry needs the fact, link to the entry that holds it. An overload’s description stands on its own: it may repeat a sibling overload’s description and add the detail that distinguishes it.
Examples
- ✗ In the remarks of
open(path, mode): Themodeparameter acceptsread,write, orappend, and defaults toread. - ✓ In the
modeparameter’s entry: The access mode:read,write, orappend. Default:read. - ✓
open(path): Opens the file for reading. - ✓
open(path, mode): Opens the file with the specified access mode. (A sibling overload’s description, plus the detail that distinguishes it.)
Rationale
A reader looking for what a parameter accepts looks at the parameter. A fact filed under the remarks or under a sibling member is missed, and when it is written in both places it drifts. Overloads are the one place a reader expects near-identical descriptions, because each one is read alone in a summary table.
Don’t restate the signature
Section titled “Don’t restate the signature”api-details-006 should API docs Don’t describe what the syntax block already shows: the number of parameters, their types, or the return type. State such a fact only when the description needs it, for example to explain what a type means in this context.
Examples
- ✓ Formats the record as one line for the audit log.
- ✗ Takes four parameters and returns a string that formats the record as one line for the audit log.
Rationale
The syntax block is the authoritative statement of the signature, and it is generated. Restating it in words adds nothing a caller can use and goes wrong when the signature changes.
Remarks: what the signature doesn’t show
Section titled “Remarks: what the signature doesn’t show”api-details-007 should API docs Use the remarks for behavior a caller cannot infer from the signature and the intro: side effects, limits, idempotency (whether repeated calls are safe), ordering guarantees, thread safety, and performance characteristics. Include only what a caller needs to use the element correctly.
Examples
- ✓ Calling
close()on a closed stream has no effect. The stream is not safe to share between threads. - ✗ This method is implemented with a ring buffer and was rewritten in version 3 to improve throughput.
Rationale
A caller reads the remarks to avoid surprises: a call that is not safe to repeat, a limit that is not in the signature, an ordering they cannot assume. Implementation history and internals are not surprises a caller can act on.