Members and parameters

Every public element of an API gets a description, and some kinds of element need specific facts stated. These rules cover completeness of the reference and what callers need to know about parameters, return values, booleans, defaults, and dependencies.

Describe every public member

api-param-001 must API docs

Provide a description for every public class, interface, struct, constant, field, enum, typedef, method, parameter, return value, and exception in the API reference.

Examples

• ✓ timeout (number) — Maximum time in milliseconds to wait for a response.
• ✗ timeout (number) —

Rationale

An undocumented member forces the reader to guess or read source; a description for each keeps the reference complete.

Lead with the purpose

api-param-002 should API docs

Begin the first sentence of a class or method description with a concise statement of purpose that does not repeat the element name.

Examples

• ✓ RetryPolicy — Controls how failed requests are retried.
• ✗ RetryPolicy — The RetryPolicy class. It can be used to configure retries.

Rationale

The first sentence is what most readers scan, so stating the purpose there, without echoing the name, tells them fast what the element is for.

Match the verb to the method type

api-param-003 should API docs

Use specific verb starters for method descriptions based on method type: ‘Checks whether’ for boolean getters, ‘Gets the’ for non-boolean getters, ‘Sets the’ for setters, ‘Creates a’ for constructor convenience methods, and ‘Called by’ for callbacks.

Examples

• ✓ isEnabled() — Checks whether the feature flag is on.
• ✗ isEnabled() — Gets the feature flag state.

Rationale

Consistent verb openers let a reader recognize a method’s kind, such as getter, setter, or callback, at a glance.

Spell out both boolean values

api-param-004 should API docs

For boolean parameters, describe what the API does when the value is true and when it is false. For boolean return values, use the format ‘True if …; false otherwise.’

Examples

• ✓ recursive — If true, deletes subdirectories too; if false, deletes only files in the top-level directory.
• ✗ recursive — Whether the delete is recursive.
• ✓ Returns: True if the file was deleted; false otherwise.
• ✗ Returns: The result of the delete operation.

Rationale

A boolean’s meaning is not obvious from its name, so stating what each value does keeps the reader from guessing which way is which.

State the default value

api-param-005 should API docs

For parameters with default values, document the default explicitly using a ‘Default:’ label.

Examples

• ✓ limit — Maximum number of results to return. Default: 20.
• ✗ limit — Maximum number of results to return.

Rationale

A caller needs the default to know what happens when they omit the parameter.

Code font and links for API names

api-param-006 should API docs

Use code font for all API names, classes, methods, constants, and parameters, and link each name to its corresponding reference page.

Examples

• ✓ Returns a Session object.
• ✗ Returns a Session object.

Rationale

Code font marks the name as an identifier, and linking it lets the reader jump to its own reference.

Document dependencies and their absence

api-param-007 should API docs

Document any dependencies (such as required permissions or platform requirements) needed to call a method, and describe the method’s behavior when those dependencies are absent.

Examples

• ✓ Requires the contacts.read permission. Without it, the call throws PermissionError.
• ✗ Reads the user’s contacts.

Rationale

A method that needs a permission or platform fails confusingly without it, so stating the dependency and the absent-case behavior saves debugging.

Distinguish arguments from parameters

api-param-008 should API docs

Use ‘parameter’ for the variable named in a method’s definition and ‘argument’ for the actual value passed to it in a call; don’t use the two terms interchangeably.

Examples

• ✓ The timeout parameter accepts an integer; pass 30 as the argument.
• ✗ The timeout argument accepts an integer; pass 30 as the parameter.

Rationale

Parameters and arguments name different things — the declared variable versus the value supplied at the call site — so conflating them makes the reference ambiguous about what the caller actually controls.