The intro is the first one or two sentences of a class, interface, or member description. It is the part of the page that travels: parent pages show it in their summary tables, editors show it in tooltips, and search engines use it to augment the meta description. These rules keep it short, specific, and free of the words that waste its space.
Doc builds differ in what follows the intro. Some render the rest of the description below it, some move it to a Summary or Overview section, and some display the whole description in the parent page’s table, so that 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. What comes after it is covered on the overview and remarks page.
Open a class, interface, or member description with one or two sentences that identify the element by what it does or what it is for. Keep them 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. Where the build displays the whole description in the parent table, keep the description to the intro and put everything else in the remarks. Don’t weaken the intro to fit search-engine techniques.
Examples
- ✓
RetryPolicy: Controls how failed requests are retried: 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
Parent pages display the intro as the element’s summary, next to its name and kind, so it has to stand on its own. Search engines also use these sentences to augment meta descriptions with practical information: the meta description carries the product and element names, and the intro attracts queries about what the element does. Those are side effects of a good intro, not a reason to shape it around keywords.
Open the first sentence of a class, interface, or member description with what the element does or what it is for. Don’t repeat the element name, and don’t name the kind of element (A class that, An interface for, This method). A type that holds data rather than doing something can open with a noun phrase that says what a value of the type is. The one exception to the kind-naming ban is an abstract class, whose intro opens with the set phrase in api-intro-003.
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.
- ✓
ScannerOptions: The options that configure a scanner.
- ✗
ScannerOptions: Names the set of options that configure a scanner.
Rationale
The first sentence is what most readers scan, and a summary table shows it next to the element’s name and kind, so repeating either spends the sentence’s most visible words on what the reader already sees.
When a class is abstract, say so 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 two facts before anything else: that they cannot create an instance of it, and what they extend it for. A set phrase puts both facts in the same place on every page.