Reference pages mention other elements constantly, and a reader has to tell from the sentence which element is meant before they follow a link. These rules cover how a method or function name is written, when a code name takes the noun for its kind, when a name is linked, and how a page links to related elements and further reading. Link text and link formatting in general live on the links page.
When text mentions a method or function, write the name with parentheses (open()). When the name is overloaded, add the parameter names (open(path, mode)), the same form the member heading uses; in a language whose overloads differ only by type, the types can stand in for the names (run(int)). Prefix the name with its class or interface unless the method is a member of the element the page documents or a sibling member on the same type (Component.run(int)). For a method in another package, include the package (Nav.Component.registerPath()).
Examples
- ✓ Call the
open() method, then call the Component.run(int) method on the servo.
- ✗ Call open, then call run on the servo.
- ✓ From another package, call the
Nav.Component.registerPath() function.
- ✓ The
nearest(timeoutMs, ids) overload ignores readings from beacons outside the list.
Rationale
The parentheses mark the name as callable, the parameter list tells overloads apart and matches the heading a link lands on, and the qualifier tells the reader which type the method belongs to before they follow a link.
Follow a code element name with the noun for its kind (class, interface, method, function, property, field, parameter, enum, struct, object, instance, component type) on its first mention in a section, and after that whenever the bare name could be read as the real-world thing the element represents or as another element with the same name. A category word used in its ordinary sense needs no qualifier; add the noun once the sentence refers to a specific code element.
Examples
- ✓ Returns the instance ID of the current
Servo instance.
- ✗ Returns the ID of the servo.
- ✓ A component holds the data for one aspect of an entity. (Generic sense.)
- ✓ Register the
Transform component type before the first system runs.
- ✗ Register
Transform before the first system runs.
- ✓ Call the
open() method, then open() again to reopen the file. (Second mention in the same section, no other element named open.)
Rationale
A class and the thing it models usually share a name, so a bare name leaves the reader unable to tell whether a sentence is about the code or about the hardware, record, or entity behind it. The kind noun also gives screen reader users the word that says what is being named, which code font alone does not convey. This extends code-009, which adds a following noun so a code name is never inflected; this rule adds one so a code name is never confused with what it represents.
Use code font for API names: classes, interfaces, methods, functions, properties, constants, and parameters. Link a name to its reference page on its first mention in a section, and keep the code font in the link text; after the first link in a section, use code font alone. Don’t link the element that the page documents to its own page; write it in code font without a link, and link within the page only when the reader needs a different section.
Examples
- ✓ Creates a
Session object. (First mention in the section.)
- ✓ The
Session object expires after an hour. (Later mention in the same section: code font, no link.)
- ✗ Returns a Session object.
- ✗ On the
Component class page: The Component class holds one aspect of an entity.
Rationale
Code font marks the name as an identifier, and one link per section lets the reader jump to its own reference without turning every mention into a link. A page that links to itself sends the reader nowhere.
Include links to related elements and additional resources in reference articles.
Examples
Rationale
Related links help a reader move from one element to the neighboring ones they will likely need next.