google-developer-style-guide-api-code-reference

name	google-developer-style-guide-api-code-reference
description	API reference documentation rules from the Google developer documentation style guide. Covers code comments, class/method documentation, parameter descriptions, and API reference formatting.

API reference code comments

Provide a complete API reference generated from source code document comments for all public classes, methods, constants, and other members. Apply these guidelines as appropriate per programming language.

External references:

• AIP-192: Documentation
• Inline API documentation (Cloud API design guide)
• Language-specific style guides

Documentation basics

Required descriptions (MUST)

Element	Requirement
Every class, interface, struct, union type, etc.	Description required
Every constant, field, enum, typedef	Description required
Every method	Description + each parameter + return value + exceptions

Strong suggestions

• Include a code sample (~5–20 lines) at the top of each unique page (class, interface, etc.).
• Use code font for all API names, classes, methods, constants, parameters. Link each to its reference page.
• Use code font + double quotes for string literals (e.g., "wrap_content", "true").
• Match class name spelling exactly as in code (correct casing, no spaces)— e.g., ActionBar.

Class name pluralization

Do	Don't
Intent objects, Activity instances	Intents, Activities

Exception: If a class name is a common term, you may use the lowercase English word, not in code font (e.g., "activities", "action bar").

Classes, interfaces, structs

First sentence: Briefly state the purpose/function of the class— information not deducible from the name and signature.

Additional documentation: How to use the API, how to invoke/instantiate, key features, best practices, pitfalls.

First-sentence rules

Rule	Example
Don't repeat the class name	—
Don't say "this class will/does ..."	—
Don't use a period before the real end of the sentence (some generators truncate at first period)	Use "for example" instead of "e.g."
Make the first sentence unique, descriptive, and short (it may be extracted for class lists)	—

Example (Android ActionBar):

A primary toolbar within the activity that may display the activity title, application-level navigation affordances, and other interactive items.

Members (constants, fields)

Keep descriptions as brief as possible. Link to relevant methods that use the constant/field.

Example (DISPLAY_SHOW_HOME):

Show 'home' elements in this action bar, leaving more space for other navigation elements. This includes logo and icon.

See also: setDisplayOptions(int), setDisplayOptions(int, int)

Methods

First sentence: Briefly state the action the method performs. Subsequent sentences: Why and how to use it, prerequisites, exceptions, related APIs.

Always document:

• Dependencies (e.g., permissions) needed to call the method
• Behavior when a dependency is missing (e.g., "throws a SecurityException" or "returns null")

Use present tense for all descriptions.

Do	Don't
Adds a new bird to the ornithology list.	Will add a new bird...
Returns a bird.	Will return a bird...

Method description patterns

Method type	Opening pattern	Example
Performs operation + returns data	Start with verb describing the operation	Adds a new bird to the ornithology list and returns the ID of the new entry.
Getter returning boolean	"Checks whether ..."	Checks whether this activity is in the process of being destroyed.
Getter returning non-boolean	"Gets the ..."	Gets the current configuration.
Setter / turns on ability	"Sets the ..."	—
Updates a property	"Updates the ..."	—
Deletes something	"Deletes the ..."	—
Registers callback/element	"Registers ..."	—
Callback (usually onXxx methods)	"Called by ..."	Called by Android when ... Then later: Subclasses implement this method to ...
Convenience constructor	"Creates a ..."	—

Parameters

Rule	Detail
Capitalization & punctuation	Capitalize first word; end with a period
Non-boolean parameters	Begin with "The" or "A" if possible
Boolean (tells API to do something)	State behavior for both true and false
Boolean (declares existing state)	"True if ...; false otherwise."
"true"/"false" wording	Don't use code font or quotation marks in this context
Default values	Explain behavior for each value/range, then state default with format: Default:

Non-boolean examples:

The ID of the bird you want to get.

A description of the bird.

Boolean (action) example:

enableCertificateValidation: If true, validates the SSL certificate before proceeding. If false, trusts the certificate without validating it.

Boolean (state) example:

True if the zoom is set; false otherwise.

Return values

Keep descriptions as brief as possible; put detailed info in the class description.

Return type	Pattern	Example
Non-boolean	"The ..."	The bird specified by the given ID.
Boolean	"True if ...; false otherwise."	True if the bird is in the sanctuary; false otherwise.

Exceptions

Context	Pattern	Example
Generator auto-inserts "Throws"	Start with "If ..."	If no key is assigned.
Generator does NOT auto-insert	Start with "Thrown when ..."	Thrown when no key is assigned.

Deprecations

Required: Tell the user what replacement to use.

• If versioned: mention the version it was first deprecated in.
• First sentence appears in summary/index—put the most important info there.
• Subsequent sentences: explain why deprecated, other useful details.
• If a method is deprecated: tell the reader how to update their code.

Examples:

Deprecated. Use #CameraPose instead.

Deprecated. Access this field using the getField method.