APIDOC Namespace Reference

Overview

Summary

The APIDOC namespace provides a way of describing an API in XML.

Description

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.

Notes

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

Summary

Container for all other tags.

Syntax

<API id="..." version="...">
    . . .
</API>

Name	Type	Description
`id`	`string`	Identifier for the API.
`version`	`number`	The APIDOC version expected by the contained tags. Currently this attribute is ignored.

Description

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.

Notes

API is the top level tag, it contains all other tags.

Summary

Marks text as bold.

Syntax

<B>foo</B>

Description

Any text contained in a B tag will appear bold. This tag functions exactly like the B tag in HTML.

Notes

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

Summary

Inserts a line break.

Syntax

<BR/>

Description

This tag functions exactly like the BR tag in HTML.

Notes

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

Summary

Marks text as code.

Syntax

<C>foo</C>

Description

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

Notes

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

Summary

Marks an ENTRY as deprecated.

Syntax

<DEPRECATED/>

Description

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.

Notes

DEPRECATED can only be contained by an ENTRY tag.

Summary

Long description for the ENTRY

Syntax

<DESCRIPTION>
     . . .
</DESCRIPTION>

Description

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.

Notes

DESCRIPTION can only be contained by an ENTRY tag.

Summary

An entry point in the API.

Syntax

<ENTRY id="...">
    . . .
</ENTRY>

Name	Type	Description
`id`	`string`	Identifier for the entry point.

Description

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.

Notes

ENTRY can only be contained by the API tag.

Summary

An example usage the ENTRY.

Syntax

<EXAMPLE desc="...">
    . . .
</EXAMPLE>

Name	Type	Description
`desc`	`string`	Short description of what the example shows.

Description

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

This an example of the EXAMPLE tag

<EXAMPLE desc="This an example of the EXAMPLE tag">
   Place sample code to be rendered in a mono-space font here.
</EXAMPLE>

Notes

EXAMPLE can only be contained by an ENTRY tag.

Formatting tags cannot be used inside an EXAMPLE tag.

Summary

An external source with more information about the API.

Syntax

<EXTERNALREF name="..." value="..."/>

Name	Type	Description
`name`	`string`	A text description of the reference.
`value`	`URL`	The URL for the reference.

Description

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.

Notes

TYPE can only be contained by the API and ENTRY tags.

Summary

Defines a footer for the generated pages.

Description

Text contained by a FOOT tag will be included as the footer for every generated page, including Entries and the Table of Contents.

Notes

The FOOT tag can only be contained by an API tag.

All Formatting tags are valid within the FOOT tag.

Summary

Includes an ENTRY in a group.

Syntax

<GROUP name="..." [value="..."]/>

Name	Type	Description
`name`	`string`	The name of the group.
`value`	`ENTRY id`	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.

Description

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.

Notes

GROUP can only be contained by the API and ENTRY tags.

Summary

Defines a header for the generated pages.

Description

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

Notes

The HEAD tag can only be contained by the API tag.

All Formatting tags are valid within the ENTRY tag.

Summary

Marks text as italic.

Syntax

<I>foo</I>

Description

Any text contained in a I tag will appear in italics. This tag functions exactly like the I tag in HTML.

Summary

Important notes about the ENTRY.

Syntax

<NOTE>
    . . .
</NOTE>

Description

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.

Notes

NOTE can only be contained by an ENTRY tag.

Summary

Marks the beginning of a new paragraph.

Syntax

<P/>. . .

Description

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.

Summary

Description for a parameter used by the ENTRY

Syntax

<PARAM name="..." type="...">
    . . .
</PARAM>

Name	Type	Description
`name`	`string`	The name of the parameter.
`type`	`string`	The data type of the parameter.

Description

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.

Example

<PARAM name="name" type="string">
   The name of the parameter.
</PARAM>
<PARAM name="type" type="string">
   The data type of the parameter.
</PARAM>

Notes

PARAM can only be contained by a SYNTAX tag.

Summary

Description for the return value of the ENTRY

Syntax

<RETVAL [name="..."] type="...">
    . . .
</RETVAL>

Name	Type	Description
`name`	`string`	Optional. The name of the return value.
`type`	`string`	The data type of the return value.

Description

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

Notes

RETVAL can only be contained by a SYNTAX tag.

Summary

Creates an inline link to an EXTERNALREF or GROUP.

Syntax

<S>. . .</S>

Description

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.

Notes

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

Summary

Associate one ENTRY with another.

Syntax

<SEEALSO value="..."/>

Name	Type	Description
`value`	`ENTRY id`	The `id` of a related `ENTRY`.

Description

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.

Summary

A brief summary for the ENTRY.

Syntax

<SUMMARY>
     . . .
</SUMMARY>

Description

Gives the user a brief overview of the ENTRY's purpose. See the 'Summary' of this entry for an example.

Summary

Syntax for using the ENTRY.

Syntax

<SYNTAX>
     . . .
</SYNTAX>

Description

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.

Notes

SYNTAX can only be contained by an ENTRY tag.

Formatting tags cannot be used inside an SYNTAX tag.

Summary

Indicates the type of an ENTRY.

Syntax

<TYPE value="..."/>

Name	Type	Description
`value`	`string`	Type of the entry.

Description

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.

Notes

TYPE can only be contained by an ENTRY tag.

Summary

CSS file referenced by generated content pages.

Description

The following styles are referenced by generated content pages:

className	Description
title	Title line
api-entry	The table surrounding an entire entry.
entry-heading	The table row in api-entry containing the heading information
api-entry-table	The heading is yet another table, this class is used for that table
entry-title	The title (the value of the ENTRYs id tag) of the entry
entry-type	The type of the entry
entry-subhead	A sub-heading in the entry, such as "Summary", or "Example"
entry-summary	The Summary section for an entry
entry-syntax	The Syntax section for an entry
entry-description	The Description section for an entry
entry-notes	The Notes section for an entry
entry-example	The Example section for an entry
entry-seealso	The See Also section for an entry
seealso	The table containing the three See Also sections
seealso-groups	The Groups section of seealso
seealso-externals	The Documents section of seealso
seealso-internals	The Entries section of seealso
param-list	A table of parameters
param-list-head	The title row for a parameter list
param-list-even	An even row of a parameter list (ie, row 0, 2, 4, ...)
param-list-odd	An odd row of a parameter list (ie, row 1, 3, 5, ...)
param-name	The Name of a parameter in a parameter list
param-type	The Type of a parameter in a parameter list
param-desc	The Description of a parameter in a parameter list

Summary

CSS file referenced by generated Table of Contents pages.

Description

The following styles are referenced by generated Table of Contents pages:

className	Description
title	Title line
toc-title	"Alphabetical Listing" and "Grouped Listing" titles
toc-abc	Alphabetical listing table.
toc-group-even	Even groups
toc-group-odd	Odd groups
toc-row	A row (contains the entry and the deprecated indicator)
toc-entry	A normal entry
toc-entry-deprecated	A deprecated entry
toc-ind-deprecated	The indicator (D) following a deprecated entry