A reference page, or "API term page", describes a single method or property on a class, interface, or object.
Content layout
Page title
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.
Summary
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.
Syntax
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.
Values/Parameters
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.
Return value
This section is only included for methods, and specifies the meaning of the return value of the method.
Dictionaries/Options
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.
Examples
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.
Specifications
The specification table comes next.
Browser compatibility
The last section on the page is the browser compatibility table with any associated notes.
Sidebar
Table of contents
The first box in the sidebar is the page's TOC. By default, <h2> and <h3> headings should be listed; this will cover the main sections as well as the names of any examples and dictionaries documented.
API links
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.
Related
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 to border-width and so forth, or from Touch to TouchList and TouchEvent, among others.
Languages (?)
Do we want the languages for the page listed in the sidebar?