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 warrent 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. An entrypoint in the API. . . . Identifier for the entrypoint. The ENTRY tag declares an API entrypoint 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. 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.

A brief summary for the ENTRY. . . . Gives the user a brief overview of the ENTRY's purpose. See the 'Sumamry' 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 monospace font using the PRE HTML tag. Leading spaces in the text contained in a SYNTAX tag are converted to entities. Use the EXAMPLE tag for concrete examples. Description for a paramater 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. 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". 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. 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 monospace font, and leading spaces are significant. The desc attribute can be used to provide a short caption for the example. 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. 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 automaticall makes it a member of the 'Deprecated' GROUP. 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 substitued 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.

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 subheading 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 a n ENTRY automatically makes the ENTRY a member of a group of the same name as given in the value attribute of the TYPE

Marks text as code. Any text contained in a C tag will appear in a monospace font, rendered using the CODE HTML tag. In addition, if the text is a 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.

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. 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.