The <reference> element defines a top-level container
for a reference topic. Reference topics document programming constructs or
facts about a product. Examples of reference topics include language elements,
class descriptions, commands, functions, statements, protocols, types, declarators,
operands, and API information, which provide quick access to facts, but no
explanation of concepts or procedures. Reference topics have the same high-level
structure as any other topic type, with a title, short description, and body.
Within the body, reference topics are typically organized into one or more
sections, property lists, and tables. The reference topic type provides general
rules that apply to all kinds of reference information, using elements like <refsyn> for
syntax or signatures, and <properties> for lists of properties
and values.
The <refbody> element is a container for the
main content of the reference topic. Reference topics limit the body structure
to tables (both simple and standard), property lists, syntax sections, and
generic sections and examples, in any sequence or number.
The <refsyn> element is a special section inside
a reference topic. The section often contains syntax or signature content
(for example, a command-line utility's calling syntax, or an API's signature).
The <refsyn> contains a brief, possibly diagrammatic
description of the subject's interface or high-level structure.
The <properties> element gives a list of properties for
the subject of the current topic, for example whether a class is public or protected.
Each property can include the type, value, and a description. The typical rendering is
usually in a table-like format. To represent multiple values for a type, just create
additional property elements and use only the <propvalue>
element (and <propdesc> when needed) for each successive
value.
The <property> element represents a property
of the current topic's subject. For example, if the current topic is a class,
the property might show that the class is protected rather than public.
It contains three optional elements: type, value, and description.
The <propvalue> element indicates the value or values
for the current property type. You can put values in separate rows if they
need separate descriptions, and just leave the <proptype> element
blank.
The <propdesc> element is used to provide a short description
of the property type and its listed values (or just the value).
The proptype element describes the type of property.
The prophead element supports regular headings for the properties element.