Every public element of an API gets its own section and its own description, and some kinds of element need specific facts stated. These rules cover the shape of a member section and the wording of its description, then what callers need to know about parameters. Member rules carry the api-member prefix; parameter rules keep api-param. Return values and errors have their own pages.
api-member-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 documentation. Give every public member its own section, and never omit a member because its description is not written yet.
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 documentation complete.
api-member-006 should API docs In a list of members of one kind (a Methods or Properties section), head each member’s section with the identifier alone, as it appears in code: the name, and for a method or function the name followed by its parameter names in parentheses. Give each overload its own section. When a member has its own page, the page title is the identifier followed by its kind (assert() method, RetryPolicy class). The identifier keeps its code casing in either place; sentence case (cap-001) does not apply to an identifier, and the heading takes no code font (head-011).
Examples
open(path, mode)Rationale
A member heading is the member’s name: it is what a reader searches for, what the page contents list shows, and what the anchor is built from. Changing its casing or wrapping it in code font breaks the match between the heading and the code. In a list, the section heading already says the kind, so repeating it on every member is noise; on a page of its own, the title is the only place the kind can be stated.
api-member-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, Returns the for a method that computes or looks up a value and is not a getter, 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.findByEmail(email): Returns the user with the specified email address.Rationale
Consistent verb openers let a reader recognize a method’s kind, such as getter, setter, or callback, at a glance.
api-member-007 should API docs In a member description, use the definite article for values the reader can identify from the member’s own entry, including its parameters and the element the member belongs to. Use the indefinite article only for an object the member creates or for a value that is not specific.
Examples
Rationale
An entry’s signature and parameter documentation identify its values, so the definite article points at them correctly. The indefinite article means “any one of these,” which misdescribes a value the caller already holds, and is right only for something the member creates or leaves unspecified.
api-member-008 should API docs Don’t use a parameter name as a noun in a member description. Name the concept in plain English and leave parameter names to the parameter documentation. Where a description does refer to a parameter as an API element, follow the name with parameter.
Examples
number by multiplier.mode parameter controls whether the file opens for reading or for writing.mode controls whether the file opens for reading or for writing.Rationale
Member descriptions appear without their signatures in search results, summary tables, and editor tooltips, so a description built from parameter names loses the referents it depends on. A bare code-font token in a sentence also reads as a literal value or as a reference to the identifier itself, not as the value the caller supplies. Readers scan member descriptions before, and often instead of, parameter descriptions.
api-member-009 should API docs When a member description refers to two elements of the same type, distinguish them: current for the element the member belongs to or the element in scope, specified for an element or value the caller supplies. Don’t add current or specified when only one element of that type is in play. Don’t use this for the element the member belongs to, and don’t substitute given, provided, supplied, passed-in, or input for specified.
Examples
Servo instance to the current Servo instance.Servo instance. (Another instance is in scope.)Servo instance. (No other instance is in play.)Servo instance.Rationale
Current and specified form a contrast pair that states where an element comes from without relying on a language keyword, so a qualifier used where nothing contrasts is noise that weakens the pair everywhere else. This is a keyword in most object-oriented languages with a meaning close to the one intended here, and the English demonstrative cannot be marked as code, so the reader has no signal for which reading applies. This prohibition is narrower than sentence-001: this Servo instance satisfies the antecedent requirement and is still wrong here, because the collision is with the keyword, not with the antecedent. Given, provided, and supplied don’t say who supplied the value, since an API supplies values to the caller as often as the caller supplies them to the API, and each carries a competing sense (given that, provided that, given name, supply chain). Input names a distinct concept in streams, forms, and machine learning documentation and should not be borrowed as a provenance qualifier.
api-member-010 should API docs When a member description refers to an identifier, name the kind of identifier and what it identifies. Don’t use a bare ID where the reader could take it as identifying either the code element or the real-world entity that element represents. A description that already names what the identifier identifies needs nothing more.
Examples
Servo instance.Servo instance controls.Servo instance.id: The identifier the beacon advertises. (The description names what the ID identifies; nothing more is needed.)Rationale
In component, entity, and device APIs, a bare ID more often names the entity, device, or record than the object holding it, so an unqualified ID leaves the reader to guess which one a member returns. Naming the kind of identifier also tells the reader what scope the value is unique in.
api-member-005 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
contacts.read permission. Without it, the call throws PermissionError.Rationale
A method that needs a permission or platform fails confusingly without it, so stating the dependency and the absent-case behavior saves debugging.
api-param-004 should API docs For boolean parameters and properties, describe what happens when the value is true and when it is false. If either description is long, use a separate sentence for each value. Write the literals in code font, spelled as the language spells them (true, True, TRUE). A sentence can open with a lowercase literal in code font; if your group prefers not to, write around it by opening with If or Returns. When true and false are ordinary words rather than the values (a true copy), no code font.
Examples
recursive: If true, deletes subdirectories too; if false, deletes only files in the top-level directory.recursive: Whether the delete is recursive.retryOnTimeout (property): true to retry a request that times out; false to fail it on the first timeout.strict: If true, the parser rejects any input that does not match the schema and reports the first mismatch. If false, the parser accepts the input, fills missing fields with their defaults, and records each mismatch as a warning.verbose (Python): True to log every request; False to log errors only.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. Code font marks true as the value the caller passes, which is why it also carries the language’s own spelling; the word true in ordinary text stays a word.
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.
api-param-009 should API docs Mark input parameters, output parameters, and parameters that are both with the language’s or the API’s own syntax (out, ref, inout, a pointer, a returned tuple). In the parameter description, describe the value; don’t restate the direction. Later text can note that a parameter is an output parameter when the reader needs it, for example when the caller must pass an initialized variable.
Examples
out count (int): The number of records that matched the filter.count (int): Output parameter. Receives the number of records that matched the filter.Rationale
Direction is part of the signature, and the language already has a notation for it that readers of that language recognize. Repeating it in words displaces the one thing the description is for, what the value means.
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
timeout parameter accepts an integer; pass 30 as the argument.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 description ambiguous about what the caller actually controls.
The five member-level rules on this page were re-issued under the api-member
prefix on 2026-09-09: api-param named a subset of what they cover, because
parameters exist only on methods and functions, which are themselves member
types. Two of them moved again on 2026-09-15, to the page a reader looks at
first. The retired IDs stay reserved and are never reused.
api-param-001 (retired 2026-09-09): “Describe every public member.” Re-issued as api-member-001, unchanged.api-param-002 (retired 2026-09-09): “Lead with the purpose.” Re-issued as api-member-002, unchanged; see that entry.api-param-003 (retired 2026-09-09): “Match the verb to the method type.” Re-issued as api-member-003, unchanged.api-param-006 (retired 2026-09-09): “Code font and links for API names.” Re-issued as api-member-004, unchanged; see that entry.api-param-007 (retired 2026-09-09): “Document dependencies and their absence.” Re-issued as api-member-005, unchanged.api-member-002 (retired 2026-09-15): “Lead with the purpose.” Folded into api-intro-002, which also bans naming the kind of element.api-member-004 (retired 2026-09-15): “Code font and links for API names.” Re-issued as api-ref-004, which adds when to link and when not to.