This page describes the rules for the intro of an API element description, which is the description’s first one or two sentences. The intro also appears outside its page in the summary tables of parent pages, in code editor tooltips, and in search results, where some search engines use the intro along with the page’s meta description.
Documentation builds differ in what follows the intro. Some builds render the rest of the description below the intro, and some move the rest of the description to a Summary or Overview section. Others display the whole description in the parent page’s table, and in those builds anything beyond the intro belongs in the remarks. The intro is the same in every case: the first one or two sentences of the description. The overview and remarks page covers the rest of the description.
api-intro-001 should API docs Keep the intro of an API element description to one or two sentences. Make the intro short enough to reuse as the element’s entry in a parent page’s summary table, and specific enough that the entry identifies the element without the rest of the page. When a build displays the whole description in the parent table, use the intro sentences as the description and put everything else in the remarks section.
Examples
RetryPolicy: Controls how failed requests are retried, including the delay between attempts and the maximum number of attempts.RetryPolicy: Network requests can fail for many reasons, including timeouts and rate limits. In most applications you want to retry them, but not forever. This class holds the settings that control that behavior, and you pass it to a client when you create one.Rationale
In a summary table, an API element’s intro appears as the element’s summary, next to the element’s name and element type, so the intro has to make sense to readers without the rest of the page. A reader who scans a summary table compares many intros at once, and a long intro slows that comparison for every element in the table.
api-intro-004 should API docs In the intro, describe what the API element does or what it is, with enough context to tell what the element applies to, such as the object it acts on or belongs to and the part of the product it works in. Don’t use only the words of the element’s name as the description. A type that holds data rather than doing something, such as an options class or a struct, can start with a noun phrase that states what a value of the type is. A member that holds a value, such as a property or field, follows api-member-011.
Examples
Vector3: A 3D vector used to position objects in a virtual world.Player: A player in the virtual world.Player: The player.updatePosition(): Updates the player’s position in the virtual world.updatePosition(): Updates the position.ScannerOptions: The options that configure a scanner.ScannerOptions: Names the set of options that configure a scanner.Rationale
The intro is where a reader decides whether an API element is the one they need. A description made from the words of the element’s name adds nothing to the name, and it leaves the reader to guess what the element applies to. For example, Updates the position could describe a method on a player, a camera, or a window. The object the element acts on or belongs to, and the part of the product it works in, answer that question in the same sentence.
api-intro-002 should API docs In the first sentence of an API element description, don’t repeat the element’s name and don’t state its element type (A class that, An interface for, This method). Later sentences can name the element when the reader needs the name, for example to distinguish the element from another one. An abstract class is the exception. Its intro starts with the set phrase in api-intro-003, which states the element type.
Examples
RetryPolicy: Controls how failed requests are retried.RetryPolicy: The RetryPolicy class. It can be used to configure retries.RetryPolicy: A class that controls how failed requests are retried.retry(): This method retries the request.RetryPolicy: Controls how failed requests are retried. Pass a RetryPolicy object to a client when you create the client. (The name appears in a later sentence, where it tells the reader what to pass.)Rationale
An API reference page shows the element’s name and element type in its title and syntax block, and a summary table shows both next to the element’s intro. When the first sentence repeats the name or the type, the reader has to read words they have already seen before they reach the element’s purpose. In a summary table that lists many intros, the repeated words can slow down a reader who is scanning for the right element.
api-intro-003 should API docs When a class is abstract, state that in the intro with the set phrase Abstract class for [what its subclasses are] followed by Extend it to [what a subclass provides]. Keep the two sentences in that order.
Examples
Parser: Abstract class for parsers that turn a token stream into a syntax tree. Extend it to support a new input format.Parser: Turns a token stream into a syntax tree.Parser: This abstract class cannot be instantiated. Subclasses implement the parsing.Rationale
A reader who reaches an abstract class from a search result or a summary table needs to know that they can’t create an instance of the class and what they can extend it for. A set phrase puts that information in the same place on every page.
api-intro-005 should API docs Don’t add keywords, product names, or phrases to the intro to improve its ranking in search results, and don’t weaken the intro to fit them. Write the intro for the reader of the reference page.
Examples
RetryPolicy: Controls how failed requests are retried.RetryPolicy: Acme SDK RetryPolicy, the retry policy class for Acme API request retries in Acme Cloud.Rationale
Some search engines read the intro in addition to the page’s meta description. When a search engine reads the intro and the meta description, it typically takes the product and element names from the meta description and the element’s purpose from the intro. An intro that states what the element does already matches searches about that purpose, so keywords added to the intro don’t improve the match. They do make the summary-table entry longer and less specific.
api-002 should api-member-003 should api-details-001 must api-details-002 should api-member-011 should