The APIDOC namespace provides a way of describing an API in XML. APIDOC is an XML based API documentation system which allows the document writer to create document content using a set of logical tags in an XML file. A perl script, parse_apidoc.pl, processes the source XML, and generates a collection of HTML files suitable for web publishing.

The set of tags available in APIDOC is very small compared to HTML, and can be broken down into three groups. These are Organizational, Formatting, and Other. Organizational tags are logical sections of an API document, such as an ENTRY, a DESCRIPTION or an EXAMPLE. Formatting tags provide a set of basic format control tags, such as B and I, as well as intelligent tags like C and S which automatically create links to other ENTRYs or external documents. The group of tags classified as Other don't fit into either of the other two categories, but don't warrant a group of their own.

See the README for instructions on how to run APIDOC. Tags and attributes are case sensitive. In APIDOC, all tag names are in UPPERCASE, and all attribute names are lowercase.

The document you are reading was created with APIDOC, see http://www.mozilla.org/projects/apidoc/apidoc.xml for the source.

APIDOC was originally written to allow engineers in the JavaScript group at Netscape to maintain their own documentation on the JavaScript Embedding API. That document is available from the JavaScript Page on mozilla.org

Container for all other tags. . . . Identifier for the API. The APIDOC version expected by the contained tags. Currently this attribute is ignored. The API tag is the top level container for all other tags. It is analogous to the HTML tag in used in HTML documents. Unlike in HTML, if tags appear outside of the API tag, the file will fail to parse. API is the top level tag, it contains all other tags. An entry point in the API. . . . Identifier for the entry point. The ENTRY tag declares an API entry point you wish to document. It serves as the container for most other Organizational tags. Entries can be referenced in SEEALSO tags. If text appearing in a C tag is also an ENTRY, a link will be created. ENTRY can only be contained by the API tag. Indicates the type of an ENTRY. Type of the entry. The value attribute should be used to describe the ENTRYs type. For example, documentation on a C based API may use 'Macro', 'Data Structure' and 'Function' as types, while this document uses 'Organizational', 'Formatting', and 'Other' as type names.

When a TYPE tag is encountered, a new GROUP is created (if it doesn't already exist), and the ENTRY which contains the TYPE tag is added to that group. In addition, the new GROUP is automatically added to the 'Groups' portion of 'See Also' for that ENTRY. TYPE can only be contained by an ENTRY tag.

A brief summary for the ENTRY. . . . Gives the user a brief overview of the ENTRY's purpose. See the 'Summary' of this entry for an example. Syntax for using the ENTRY. . . . Shows the user an abstract use of the ENTRY. PARAM tags can be contained by the SYNTAX tag to further illustrate parameters. Text inside SYNTAX tags will be rendered in a mono-space font using the HTML PRE tag. Leading spaces in the text contained in a SYNTAX tag are converted to entities. Use the EXAMPLE tag for concrete examples. SYNTAX can only be contained by an ENTRY tag.

Formatting tags cannot be used inside an SYNTAX tag.

Description for a parameter used by the ENTRY . . . The name of the parameter. The data type of the parameter. Used to describe a parameter used by the ENTRY. PARAM tags can only be contained inside SYNTAX tags. Multiple PARAM tags can appear in a SYNTAX tag (typically one for each parameter). PARAM tags will be displayed in the order they appear. PARAM can only be contained by a SYNTAX tag. Description for the return value of the ENTRY . . . Optional. The name of the return value. The data type of the return value. RETVAL works exactly like the PARAM tag, with the exception that the name attribute is optional. If name is omitted, it defaults to the string "Return Value". RETVAL can only be contained by a SYNTAX tag. Long description for the ENTRY . . . Contains a long description of the ENTRY. Literal HTML can be included using a ![CDATA[ . . . ]] tag. The CDATA 'trick' can actually be used inside any APIDOC tag, but is most useful for DESCRIPTIONs. DESCRIPTION can only be contained by an ENTRY tag. An example usage the ENTRY. . . . Short description of what the example shows. Contains a "real world" example of the ENTRY being used. As with the SYNTAX tag text inside EXAMPLE tags will be rendered in a mono-space font, and leading spaces are significant. The desc attribute can be used to provide a short caption for the example. EXAMPLE can only be contained by an ENTRY tag.

Formatting tags cannot be used inside an EXAMPLE tag.

Important notes about the ENTRY. . . . Contains notes about the entry that should stand out from the description for one reason or another. If an entry is deprecated, the NOTES section would be a good place to explain why. NOTE can only be contained by an ENTRY tag. Associate one ENTRY with another. The id of a related ENTRY. Associates one entry with another. Multiple SEEALSO tags can appear in an ENTRY. Using an entry in a C tag creates a SEEALSO tag for it automatically. The EXTERNALREF tag can be used to attach references to external documents to entries. Marks an ENTRY as deprecated. Marking an entry as DEPRECATED tells would-be users that the use of that ENTRY is not advised. Further information can be placed in the DESCRIPTION or NOTE tag. Marking an entry as DEPRECATED automatically makes it a member of the 'Deprecated' GROUP. DEPRECATED can only be contained by an ENTRY tag. An external source with more information about the API. A text description of the reference. The URL for the reference. EXTERNALREFs will be added to the 'See Also' portion of an ENTRY. If an EXTERNALREF appears as a child of the API tag, and the value of the URL contains the characters '{e}', the reference will be attached to every entry, and the ENTRYs id will be substituted in for '{e}'. If '{e}' does not appear in the value attribute, APIDOC assumes that this EXTERNALREF applies to the API as a whole, and only lists it in the table of contents.

If an EXTERNALREF appears as a child of an ENTRY tag, it will only appear in that ENTRYs 'See Also' section.

Multiple EXTERNALREF tags can appear as children of both API and ENTRY tags. TYPE can only be contained by the API and ENTRY tags.

Defines a footer for the generated pages. Text contained by a FOOT tag will be included as the footer for every generated page, including Entries and the Table of Contents. The FOOT tag can only be contained by an API tag.

All Formatting tags are valid within the FOOT tag.

Defines a header for the generated pages. Text contained by a HEAD tag will be included as the header for every generated page, including Entries and the Table of Contents. The HEAD tag can only be contained by the API tag.

All Formatting tags are valid within the ENTRY tag.

Includes an ENTRY in a group. The name of the group. The id of the ENTRY to add to the group. Optional (and ignored) if the GROUP tag appears as a child of an ENTRY tag, in which case the id of the containing ENTRY is used. For each unique GROUP name appearing in the API, a sub-heading will appear in the Table of Contents, listing each member of the GROUP. Multiple GROUP tags can appear as children of the API tag. The GROUP tag can appear as a child of either the API tag, or an ENTRY tag. When a GROUP is parented directly by the API tag, both name and value attributes must be specified. When a GROUP tag is parented by an ENTRY tag, the id of the containing ENTRY is used in place of the value attribute.

Marking an item as DEPRECATED automatically makes it a member of the group named 'Deprecated'. Using the TYPE tag in an ENTRY automatically makes it a member of a group of the same name as the TYPE. GROUP can only be contained by the API and ENTRY tags.

Marks text as code. Any text contained in a C tag will appear in a mono-space font, rendered using the HTML CODE tag. In addition, if the text is an ENTRY id (but not the current ENTRY), a link will be created to the ENTRY in the text, and a SEEALSO tag will be generated.

For example, all of the links in this body of text were generated by wrapping the plain text in a C tag. APIDOC checks to see of the contained text is a valid ENTRY, and if so, assumes that's what you were talking about. If the contained text is not a valid ENTRY, or it is the current entry, the text is rendered in a HTML CODE container, and no links are generated. Formatting tags cannot be used in SYNTAX or EXAMPLE tags (but they can be used in PARAM tags.)

Marks the beginning of a new paragraph. . . . Marks the start of a new paragraph. Unlike in HTML, P tags are not containers. That is, the only valid P tag is the one shown here. Marks text as bold. Any text contained in a B tag will appear bold. This tag functions exactly like the B tag in HTML. Formatting tags cannot be used in SYNTAX or EXAMPLE tags (but they can be used in PARAM tags.) Inserts a line break. This tag functions exactly like the BR tag in HTML. Formatting tags cannot be used in SYNTAX or EXAMPLE tags (but they can be used in PARAM tags.) Marks text as italic. Any text contained in a I tag will appear in italics. This tag functions exactly like the I tag in HTML. Creates an inline link to an EXTERNALREF or GROUP. If the text wrapped in an S tag is a valid GROUP (including a GROUP implied by a TYPE or DEPRECATED tag) a link to the referenced group will be created in addition to the text. If instead, the text matches a valid EXTERNALREF tag, a link to the external reference will be created.

In both cases, an appropriate entry is added to the ENTRYs 'See Also' section. If the text contained by an S tag does not match any GROUP or EXTERNALREF, the parse will fail.

Formatting tags cannot be used in SYNTAX or EXAMPLE tags (but they can be used in PARAM tags.)

CSS file referenced by generated Table of Contents pages. The following styles are referenced by generated Table of Contents pages:
classNameDescription
titleTitle line
toc-title"Alphabetical Listing" and "Grouped Listing" titles
toc-abcAlphabetical listing table.
toc-group-evenEven groups
toc-group-oddOdd groups
toc-rowA row (contains the entry and the deprecated indicator)
toc-entryA normal entry
toc-entry-deprecatedA deprecated entry
toc-ind-deprecatedThe indicator (D) following a deprecated entry
]]> CSS file referenced by generated content pages. The following styles are referenced by generated content pages:
classNameDescription
titleTitle line
api-entryThe table surrounding an entire entry.
entry-headingThe table row in api-entry containing the heading information
api-entry-tableThe heading is yet another table, this class is used for that table
entry-titleThe title (the value of the ENTRYs id tag) of the entry
entry-typeThe type of the entry
entry-subheadA sub-heading in the entry, such as "Summary", or "Example"
entry-summaryThe Summary section for an entry
entry-syntaxThe Syntax section for an entry
entry-descriptionThe Description section for an entry
entry-notesThe Notes section for an entry
entry-exampleThe Example section for an entry
entry-seealsoThe See Also section for an entry
seealsoThe table containing the three See Also sections
seealso-groupsThe Groups section of seealso
seealso-externalsThe Documents section of seealso
seealso-internalsThe Entries section of seealso
param-listA table of parameters
param-list-headThe title row for a parameter list
param-list-evenAn even row of a parameter list (ie, row 0, 2, 4, ...)
param-list-oddAn odd row of a parameter list (ie, row 1, 3, 5, ...)
param-nameThe Name of a parameter in a parameter list
param-typeThe Type of a parameter in a parameter list
param-descThe Description of a parameter in a parameter list
]]>