Stay organized with collections
Save and categorize content based on your preferences.
When you're documenting an API, provide a complete API reference, typically
generated from source code using document comments that describe all public
classes, methods, constants, and other members.
Use the basic guidelines in this document as appropriate for a given programming
language. This document doesn't specify how to mark up document comments.
For more information, see the following resources:
The specific style guide for each programming language
Documentation basics
The API reference must provide a description for each of the following:
Every class, interface, struct, and any other similar member of the API (such
as union types in C++).
Every constant, field, enum, and typedef.
Every method, with a description for each parameter, the return value, and any
exceptions thrown.
The following are extremely strong suggestions. In some cases, they don't
make sense for a particular API or in a specific language, but in general,
follow these guidelines:
On each unique page (for a class, interface, etc.), include a code sample
(~5-20 lines) at the top.
Put all API names, classes, methods, constants, and parameters in code font,
and link each name to the corresponding reference page. Most document
generators do this automatically for you.
Put string literals in code font, and enclose them in double quotation marks.
For example, XML attribute values might be "wrap_content" or "true".
Make sure that the spelling of a class name in documentation matches the
spelling in code, with capital letters and no spaces (for example,
ActionBar).
Don't make class names plural (Intents, Activities); instead, add
a plural noun (Intent objects, Activity instances).
However, if a class has a name that's a common term, you can refer to it
with the corresponding English word, in lowercase and not in code font
(activities, action bar).
Classes, interfaces, structs
In the first sentence of a class description, briefly state the intended purpose
or function of the class or interface with information that can't be deduced
from the class name and signature. In additional documentation, elaborate on how
to use the API, including how to invoke or instantiate it, what some of the key
features are, and any best practices or pitfalls.
Many documentation tools automatically extract the first sentence of each class
description for use in a list of all classes, so make the first sentence unique
and descriptive, yet short. Additionally:
Don't repeat the class name in the first sentence.
Don't say "this class will/does ..."
Don't use a period before the actual end of the sentence, because some
document generators naively terminate the "short description" at the first
period. For example, some generators terminate the sentence if they see
e.g., so use for example instead.
The following example is the first sentence of the description for Android's
ActionBar class:
A primary toolbar within the activity that may display the activity title,
application-level navigation affordances, and other interactive items.
Members
Make descriptions for members (constants and fields) as brief as possible. Be
sure to link to relevant methods that use the constant or field.
For example, here's the description for the ActionBar class's
DISPLAY_SHOW_HOME
constant:
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
In the first sentence for a method description, briefly state what action the
method performs. In subsequent sentences, explain why and how to use the method,
state any prerequisites that must be met before calling it, give details about
exceptions that may occur, and specify any related APIs.
Document any dependencies (such as
Android permissions)
that are needed to call the method, and how the method behaves if such a
dependency is missing (for example, "the method throws a
SecurityException"
or "the method returns null").
Checks whether this activity is in the process of being destroyed in order to
be recreated with a new configuration. This is often used in onStop to
determine whether the state needs to be cleaned up or if it's passed on to the
next instance of the activity using onRetainNonConfigurationInstance.
Use present tense for all descriptions—for example:
Adds a new bird to the ornithology list.
Returns a bird.
Description
If a method performs an operation and returns some data, start the description
with a verb describing the operation—for example:
Adds a new bird to the ornithology list and returns the ID of the new
entry.
If it's a "getter" method and it returns a boolean, start with "Checks
whether ...."
If it's a "getter" method and it returns something other than a boolean,
start with "Gets the ...."
If it has no return value, start with a verb like one of the following:
Turning on an ability or setting: "Sets the ...."
Updating a property: "Updates the ...."
Deleting something: "Deletes the ...."
Registering a callback or other element for later reference:
"Registers ...."
For a callback: "Called by ...." (Usually for a method that's named
starting with "on", such as onBufferingUpdate.) For example, "Called by
Android when ...." Then, later in the description: "Subclasses implement this
method to ...."
If it's a convenience method that constructs the class object, start with
"Creates a ...."
Parameters
For parameter descriptions, follow these guidelines:
Capitalize the first word, and end the sentence or phrase with a period.
Begin descriptions of non-boolean parameters with "The" or "A" if possible:
The ID of the bird you want to get.
A description of the bird.
For boolean parameters that tell the API to do or not do something, state
what the API does if the parameter is true and if it's false. For example:
enableCertificateValidation: If true, validates the SSL certificate
before proceeding. If false, trusts the certificate without validating it.
For boolean parameters that declare the already-established state of something
(rather than telling the API to do something), use the format "True if ...;
false otherwise." For example:
True if the zoom is set; false otherwise.
In this context, don't put the words "true" and "false" in code font or
quotation marks.
For parameters with default behavior, explain what the behavior is for each
value or range of values, and then say what the default value is. Use the
format Default: to explain the default value.
Return values
Be as brief as possible in the return value's description; put any detailed
information in the class description.
If the return value is anything other than a boolean, start with "The ..."—for
example:
The bird specified by the given ID.
If the return value is a boolean, use the format "True if ...; false
otherwise."—for example:
True if the bird is in the sanctuary; false otherwise.
Exceptions
In languages where the reference generator automatically inserts the word
"Throws", begin your description with "If ...":
If no key is assigned.
Otherwise, begin with "Thrown when ...":
Thrown when no key is assigned.
Deprecations
When something is deprecated, tell the user what to use as a replacement. (If
you track your API with version numbers, mention which version it was first
deprecated in.)
Only the first sentence of a description appears in the summary section and
index, so put the most important information there. Subsequent sentences can
explain why it was deprecated, along with any other information that's useful
for a developer using your API.
If a method is deprecated, tell the reader what to do to make their code work.
Examples
Deprecated. Use #CameraPose instead.
Deprecated. Access this field using the getField method.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-02-13 UTC."],[[["\u003cp\u003eAPI documentation must include descriptions for every class, constant, method, and parameter, with detailed explanations of their purpose, usage, and potential exceptions.\u003c/p\u003e\n"],["\u003cp\u003eDescriptions should be concise and informative, prioritizing clarity and avoiding redundancy, using present tense and specific verbs for actions.\u003c/p\u003e\n"],["\u003cp\u003eParameter descriptions should clearly define their purpose and expected values, including behavior for booleans and defaults, while return values focus on the information provided.\u003c/p\u003e\n"],["\u003cp\u003eClass descriptions should begin with a concise purpose statement and offer guidance on usage, features, and best practices, while member descriptions should link to relevant methods.\u003c/p\u003e\n"],["\u003cp\u003eDeprecation notices must specify replacements and provide guidance for updating existing code to ensure compatibility.\u003c/p\u003e\n"]]],["API documentation should provide descriptions for all public classes, methods, constants, and members. Class descriptions should state the purpose, avoiding repetition of the class name. Method descriptions must detail the action, prerequisites, and exceptions. Parameters should clearly indicate their function, with special formatting for booleans and defaults. Return values are to be concise, using \"The\" or \"True if\" formats. Deprecated elements must indicate their replacement and deprecation version. Follow the guidelines of capitalization, font use and linking.\n"],null,["# API reference code comments\n\n\u003cbr /\u003e\n\nWhen you're documenting an API, provide a complete API reference, typically\ngenerated from source code using document comments that describe all public\nclasses, methods, constants, and other members.\n\nUse the basic guidelines in this document as appropriate for a given programming\nlanguage. This document doesn't specify how to mark up document comments.\n\nFor more information, see the following resources:\n\n- [AIP-192: Documentation](https://google.aip.dev/192) in Google's API standards\n- [Inline API documentation](https://cloud.google.com/apis/design/documentation) in the Google Cloud API design guide\n- The specific style guide for each programming language\n\nDocumentation basics\n--------------------\n\nThe API reference **must** provide a description for each of the following:\n\n- Every class, interface, struct, and any other similar member of the API (such\n as union types in C++).\n\n- Every constant, field, enum, and typedef.\n\n- Every method, with a description for each parameter, the return value, and any\n exceptions thrown.\n\nThe following are **extremely strong suggestions**. In some cases, they don't\nmake sense for a particular API or in a specific language, but in general,\nfollow these guidelines:\n\n- On each unique page (for a class, interface, etc.), include a code sample\n (\\~5-20 lines) at the top.\n\n- Put all API names, classes, methods, constants, and parameters in code font,\n and link each name to the corresponding reference page. Most document\n generators do this automatically for you.\n\n- Put string literals in code font, and enclose them in double quotation marks.\n For example, XML attribute values might be `\"wrap_content\"` or `\"true\"`.\n\n- Make sure that the spelling of a class name in documentation matches the\n spelling in code, with capital letters and no spaces (for example,\n `ActionBar`).\n\n - Don't make class names plural (`Intents`, `Activities`); instead, add\n a plural noun (`Intent` objects, `Activity` instances).\n\n - However, if a class has a name that's a common term, you can refer to it\n with the corresponding English word, in lowercase and *not* in code font\n (activities, action bar).\n\nClasses, interfaces, structs\n----------------------------\n\nIn the first sentence of a class description, briefly state the intended purpose\nor function of the class or interface with information that can't be deduced\nfrom the class name and signature. In additional documentation, elaborate on how\nto use the API, including how to invoke or instantiate it, what some of the key\nfeatures are, and any best practices or pitfalls.\n\nMany documentation tools automatically extract the first sentence of each class\ndescription for use in a list of all classes, so make the first sentence unique\nand descriptive, yet short. Additionally:\n\n- Don't repeat the class name in the first sentence.\n\n- Don't say \"this class will/does ...\"\n\n- Don't use a period before the actual end of the sentence, because some\n document generators naively terminate the \"short description\" at the first\n period. For example, some generators terminate the sentence if they see\n *e.g.* , so use *for example* instead.\n\nThe following example is the first sentence of the description for Android's\n[`ActionBar` class](http://developer.android.com/reference/android/app/ActionBar.html):\n\u003e *A primary toolbar within the activity that may display the activity title,\n\u003e application-level navigation affordances, and other interactive items.*\n\nMembers\n-------\n\nMake descriptions for members (constants and fields) as brief as possible. Be\nsure to link to relevant methods that use the constant or field.\n\nFor example, here's the description for the `ActionBar` class's\n[`DISPLAY_SHOW_HOME`](http://developer.android.com/reference/android/app/ActionBar.html#DISPLAY_SHOW_HOME)\nconstant:\n\u003e *Show 'home' elements in this action bar, leaving more space for other\n\u003e navigation elements. This includes logo and icon.*\n\u003e *See also: `setDisplayOptions(int)`, `setDisplayOptions(int, int)`*\n\nMethods\n-------\n\nIn the first sentence for a method description, briefly state what action the\nmethod performs. In subsequent sentences, explain why and how to use the method,\nstate any prerequisites that must be met before calling it, give details about\nexceptions that may occur, and specify any related APIs.\n\nDocument any dependencies (such as\n[Android permissions](http://developer.android.com/guide/topics/security/permissions.html))\nthat are needed to call the method, and how the method behaves if such a\ndependency is missing (for example, \"the method throws a\n[SecurityException](http://developer.android.com/reference/java/lang/SecurityException.html)\"\nor \"the method returns null\").\n\nFor example, here's the description for Android's\n[`Activity.isChangingConfigurations` method](http://developer.android.com/reference/android/app/Activity.html#isChangingConfigurations()):\n\u003e *Checks whether this activity is in the process of being destroyed in order to\n\u003e be recreated with a new configuration. This is often used in `onStop` to\n\u003e determine whether the state needs to be cleaned up or if it's passed on to the\n\u003e next instance of the activity using `onRetainNonConfigurationInstance`.*\n\nUse present tense for all descriptions---for example:\n\n- *Adds a new bird to the ornithology list.*\n\n- *Returns a bird.*\n\n### Description\n\n- If a method performs an operation and returns some data, start the description\n with a verb describing the operation---for example:\n\n - *Adds a new bird to the ornithology list and returns the ID of the new\n entry.*\n- If it's a \"getter\" method and it returns a boolean, start with \"Checks\n whether ....\"\n\n- If it's a \"getter\" method and it returns something other than a boolean,\n start with \"Gets the ....\"\n\n- If it has no return value, start with a verb like one of the following:\n\n - Turning on an ability or setting: \"Sets the ....\"\n\n - Updating a property: \"Updates the ....\"\n\n - Deleting something: \"Deletes the ....\"\n\n - Registering a callback or other element for later reference:\n \"Registers ....\"\n\n - For a callback: \"Called by ....\" (Usually for a method that's named\n starting with \"on\", such as `onBufferingUpdate`.) For example, \"Called by\n Android when ....\" Then, later in the description: \"Subclasses implement this\n method to ....\"\n\n- If it's a convenience method that constructs the class object, start with\n \"Creates a ....\"\n\n### Parameters\n\nFor parameter descriptions, follow these guidelines:\n\n- Capitalize the first word, and end the sentence or phrase with a period.\n\n- Begin descriptions of non-boolean parameters with \"The\" or \"A\" if possible:\n\n - *The ID of the bird you want to get.*\n\n - *A description of the bird.*\n\n- For boolean parameters that tell the API to do or not do something, state\n what the API does if the parameter is true and if it's false. For example:\n\n - *`enableCertificateValidation`: If true, validates the SSL certificate\n before proceeding. If false, trusts the certificate without validating it.*\n- For boolean parameters that declare the already-established state of something\n (rather than telling the API to do something), use the format \"True if ...;\n false otherwise.\" For example:\n\n - *True if the zoom is set; false otherwise.*\n- In this context, don't put the words \"true\" and \"false\" in code font or\n quotation marks.\n\n- For parameters with default behavior, explain what the behavior is for each\n value or range of values, and then say what the default value is. Use the\n format *Default:* to explain the default value.\n\n### Return values\n\nBe as brief as possible in the return value's description; put any detailed\ninformation in the class description.\n\n- If the return value is anything other than a boolean, start with \"The ...\"---for\n example:\n\n - *The bird specified by the given ID.*\n- If the return value is a boolean, use the format \"True if ...; false\n otherwise.\"---for example:\n\n - *True if the bird is in the sanctuary; false otherwise.*\n\n### Exceptions\n\nIn languages where the reference generator automatically inserts the word\n\"Throws\", begin your description with \"If ...\":\n\n- *If no key is assigned.*\n\nOtherwise, begin with \"Thrown when ...\":\n\n- *Thrown when no key is assigned.*\n\n### Deprecations\n\nWhen something is deprecated, tell the user what to use as a replacement. (If\nyou track your API with version numbers, mention which version it was first\ndeprecated in.)\n\nOnly the first sentence of a description appears in the summary section and\nindex, so put the most important information there. Subsequent sentences can\nexplain why it was deprecated, along with any other information that's useful\nfor a developer using your API.\n\nIf a method is deprecated, tell the reader what to do to make their code work.\n\n#### Examples\n\n\u003e *Deprecated. Use #CameraPose instead.*\n\u003e *Deprecated. Access this field using the `getField` method.*"]]
