A reference page, or "API term page", describes a single method or property on a class, interface, or object.
The title is the name of the class, interface, or object the method or property is a member of, then a period, then the name of the API term itself.
The page begins with a summary explaining the interface, object, class, or CSS property being described. This should be a paragraph or two at most, and is used as the SEO summary (which can be overridden using the "seoSummary" CSS class.
A box describing the method or property's syntax. This will have a standard appearance site-wide, but the details of its content will depend on the technology being documented.
For a property or attribute, its possible values are described here using a
<dl> list or
<table> as appropriate. A definition list is preferred, but a table may be used, for example, to include a small image showing the effect of using each value.
For a method, a list of parameters is displayed instead, as a definition list.
This section is only included for methods, and specifies the meaning of the return value of the method.
If the method uses special objects which are not used elsewhere, they are documented here instead of in a separate page. For example, if a method uses an object with various fields to set custom parameters, it's documented here. Each of these objects has its own subheading, a brief description of what it's for, and a
<dl> listing each field and its purpose.
Next come the examples; these are live samples with text explaining them. If there is only one sample, there are no subheadings. If there are multiple samples, each should be in its own subsection.
The specification table comes next.
The last section on the page is the browser compatibility table with any associated notes.
Table of contents
The first box in the sidebar is the page's TOC. By default,
<h3> headings should be listed; this will cover the main sections as well as the names of any examples and dictionaries documented.
This box (whose name needs to be determined; perhaps it should be the name of the object or class containing the method or property being documented) contains links to all the other methods and properties on the same object or interface, so the user can quickly get to them.
This box, which replaces the "See also" section in-content, provides links to related topics. This would, for example, link the user from the page on
border-width and so forth, or from
TouchEvent, among others.
Do we want the languages for the page listed in the sidebar?