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.
Details and remarks
Covers the running prose of a reference page: the short description and the longer remarks. What to document for parameters, return values, and other members 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.