Tag reference

Overview

The tags can roughly be divided in 2 groups:

Documentation structure tags. These are needed for fpdoc to do it’s work. They determine what elements are documented. See table The description file
Text structure and formatting tags. These tags indicate blocks of text, such as paragraphs, tables, lists and remarks, but also specify formatting: apply formatting (make-up) to the text, or to provide links to other parts of the text. These mostly occur in text structure tags. See table The description file

Documentation structure tags
Tag	Description	Page
descr	Element description
element	Identifier documentation
errors	Error section
fpdoc-description	Global tag
module	Unit tag
package	Package global tab
seealso	Cross-reference section
short	Short description
topic	Topic page

Text formatting tags
Tag	Description	Page
b	Format bold
caption	Specify table caption
code	Syntax highlight code
dd	definition data
dl	definition list
dt	Definition term
i	format italics
img	include image
li	list element
link	Cross-reference
ol	numbered list
p	paragraph
pre	Preformatted text
remark	remark paragraph
table	Table
td	Table cell
th	Table header
tr	Table row
u	format underlined
ul	bulleted list
var	format as variable

The nodes for formatting a text resemble closely the basic HTML formatting tags with the following exceptions:

Each opening tag must have a corresponding closing tag.
Tags are case sensitive.
Tables and paragraphs are at the same level, i.e. a table cannot occur inside a paragraph. The same is true for all ’structural’ tags such as lists,

Also, if special formatting tags such as a table or lists are inserted, then the remaining text must be inside a paragraph tag. This means that the following is wrong:

<descr>
Some beginning text
<ol>
<li>A list item</li>
</ol>
some ending text
</descr>

Instead, the correct XML should be

<descr>
<p>Some beginning text</p>
<ol>
<li>A list item</li>
</ol>
<p>some ending text</p>
</descr>

: format bold

This tag will cause the text inside it to be formatted using a bold font.

Example:

Normal text <b>Bold text</b> normal text.

will be formatted as:
Normal text Bold text normal text.

See also: , .

: Linebreak

This tag will cause the text to be continued on the next line, without starting a new paragraph.

Example:

Normal text on first line <br/>Continued on next line.

will be formatted as:
Normal text on first line
Continued on next line.

See also: , .

: Specify table caption

This tag can occur inside a tag and serves to set the table caption.

Example

<table>
<caption>This caption will end up above the table</caption>
<th><td>Column 1</td><td>Column 2</td></th>
</table>

: format as pascal code

The tag serves to insert Pascal code into the text. When possible this code will be highlighted in the output. It can be used to put highlighted Pascal code in the documentation of some identifier. It can occur inside or tags.

Note that any text surrounding the tag should be placed in paragraph tags .

Example:

<code>
With Strings do
  For i:=Count-1 downto 0 do
    Delete(i);
</code>

Seealso: ,

: Descriptions

This is the actual documentation tag. The contents of this tag will be written as the documentation of the element. It can contain any mixture of text and markup tags. The tag can only occur inside a or .

Example:

<element name="MyEnym">
<descr>Myenum is a simple enumeration type</descr>
</element>

See also: , , ,

: definition data.

The tag is used to denote the definition of a term in a definition list. It can occur only inside a definition list tag (), after a definition term () tag. It’s usage is identical to the one in HTML.

Example:

<dl>
<dt>FPC</dt><dd>stands for Free Pascal Compiler.</dd>
</dl>

Will be typeset as

FPC: stands for Free Pascal Compiler.

See also: , , ,

: definition list.

Definition lists are meant to type a set of terms together with their explanation. It’s usage is identical to the one in HTML, with the exception that it cannot occur inside ordinary text: surrounding text should always be enclosed in paragraph tags.

Example:

<dl>
<dt>meOne</dt><dd>First element of the enumeration type.</dd>
<dt>meTwo</dt><dd>Second element of the enumeration type.</dd>
<dt>meThree</dt><dd>Third element of the enumeration type.</dd>
</dl>

Will be typeset as

meOne: First element of the enumeration type.
meTwo: Second element of the enumeration type.
meThree: Third element of the enumeration type.

See also: , , ,

: definition term.

The tag is used in definition lists to enclose the term for which a definition is presented. It’s usage is identical to the usage in HTML.

Example:

<dl>
<dt>FPC</dt><dd>stands for Free Pascal Compiler.</dd>
</dl>

Will be typeset as

FPC: stands for Free Pascal Compiler.

See also: , , ,

: Identifier documentation

The contains the documentation for an identifier in a unit. It should occur inside a module tag. It can contain 4 tags:

short: For a one-line description of the identifier. Is used as a header or is used in overviews of constants, types, variables or classes.
descr: Contains the actual description of the identifier.
errors: For functions an procedures this can be used to describe error conditions. It will be put in a separate section below the description section.
seealso: Used to refer to other nodes. will be typeset in a separate section.

The tag should have at least the attribute, it is used to link the element node to the actual identifier in the Pascal unit. Other attributes may be added in future.

Example:

<element name="MyEnym">
<descr>Myenum is a simple enumeration type</descr>
</element>

The following attributes are supported:

name: this attribute is required and should equal the identifier name.
opaque: this attribute is used for opaque types: if set to 1, the declaration will be replaced with the term “opaque”.
link: this should contain the name of an element. A link to the current element will be referred to this identifier instead. This can be used in overridden methods/properties to refer to the parent documentation instead.
alwaysvisible: if set to 1, documentation for the element will be shown anyway, even if the current visibility is not shown. This can be used to force generation of documentation for private or protected members of a class even when they are not supposed to be shown. (for example, --hide-protected is given, and one wishes to show a protected method.)
skip: if set to 1, the element will not appear in any overviews. A documentation page may be generated in HTML, but it will not be linked to from any overview.

See also: , , ,

: Error section.

The tag is used to document any errors that can occur when calling a function or procedure. it is placed in a different section in the generated documentation. It occurs inside a tag, at the same level as a or tag. It’s contents can be any text or formatting tag.

Example:

<element name="MyDangerousFunction">
<descr>MyDangerousFunction is a dangerous function</descr>
<errors>When MyDangerousFunction fails, all is lost</errors>
</element>

See also: , , ,

: Include an example source file.

The tag is used to include a sample code fragment in the documentation. It must appear below an tag. Multiple example tags may appear in an element tag.

The attribute of the is used to specify the file name containing the example. No extension is required in the filename: if it is missing, .pp is assumed.

Example:

<element name="MyDangerousFunction">
<descr>MyDangerousFunction is a dangerous function</descr>
<errors>When MyDangerousFunction fails, all is lost</errors>
<example file="ex/ex1"/>
</element>

See also: , ,

: Format filename

The tag will cause its contents as a filename. It can occur mixed with any text. It is similar to the tag.

Example:

The file <file>me.exe</file> is searched in the PATH.

will be formatted as:
The file me.exe< is searched in the PATH.

: Global tag

The tag is the topmost tag in a description file. It contains a series of tags, one for each package that is described in the file.

: Format italics

The tag will cause its contents to be typeset in italics. It can occur mixed with any text.

Example:

Normal text <i>italic text</i> normal text.

will be formatted as:
Normal text italic text normal text.

See also: ,

: include image

The tag will include an image in the text. It is considered equivalent to a paragraph tag. The required attribute can be used to search to specify the filename. What kind of file is used depends on the output format. Normally, using png images should work with all output formats.

The attribute is optional and can be used to specify a caption text which will be displayed above or under the figure. Lastly, the attribute can be used to attach a name to the figure (a label to which can be referred).

For example:

<p>
some text
</p>
<img file="myfile" caption="A nice caption"/>
<p>
Some more text.
</p>

: list element

The tag denotes an element in a or list. The usage is the same as for it’s HTML counterpart: It can occur only inside one of the or list tags. It’s contents may be arbitrary text and formatting tags, contrary to HTML tags, the tag always must have a closing tag. Note that it cannot be used in a definition list ().

Example:

<ul>
<li>First item in the list</li>
<li>Second item in the list</li>
</ul>

Will be typeset as

First item in the list.
Second item in the list.

See also: , .

: Cross-reference

The tag is used to insert a reference to an element inside some piece of text or inside the section. It is similar in functionality to the

<A HREF="SomeAnchor">some linked text</A>

construct in HTML.

The mandatory attribute of the tag should have the name of an element tag in it. This name is not case sensitive. will issue a warning if it cannot find a matching name. It will look for matching names in the current file, and in all content files that have been specified with the import command-line option.

The link tag can exist in 2 forms: one with separate closing tag, surrounding a piece of text, one without separate closing tag. If a piece of text is surrounded by the link tag, then the text will be converted to a hyperlink in the HTML documentation. If there is no surrounded text, then the value of the attribute will be used as the text. This means that

<link id="TStream">TStream</link>

and

<link id="TStream"/>

are completely equivalent.

Example:

The <link id="TStringlist">stringlist</link> class is a descendent of the
<link id="TStrings"/> class.

: Unit reference

The tag encloses all tags for a unit. It can contain only tags for all identifiers in the unit and a tag describing the unit itself. The tag should occur inside a tag.

The attribute should have as a value the name of the unit which is described by the module. This name is not case sensitive.

Example:

<module name="classes">
<descr>
The classes unit contains basic class definitions for the FCL.
</descr>
</module>

See also: , ,

: Documentation notes (annotations).

The tag indicates that a particular documentation topic contains annotations. It consists of one or more tags, no other tags are allowed They serve as annotations to the documentation, usually for the benefit of the documentation writer.

As such, notes are by default not included in the final documentation, but they can be added to them with the –emit-notes command-line option.

Notes can appear below the , and tags.

For an explanation of what can appear inside the note tag itself, see .

Example:

<module name="classes">
<descr>
The classes unit contains basic class definitions for the FCL.
</descr>
<notes>
<note>MVC. This unit needs more documenting</note>
<note>FK The new class MyVeryImportantClass needs documenting</note>
<notes>
</module>

: Notes/Annotation entry.

The tag contains the text of one note. It must appear below a tag collection of annotations. The notes will be typeset as a unordered list below the documentation. (usually the descr node).

This means there is a limitation to the markup that a note can contain: It can just contain plain text with some markup, similar to what is allowed in tags. No tables, lists or other structures are supported inside. Example:

<element name="TDuplicates">
<short>How to handle duplicates in a list</short>
<descr>
Some text
</descr>
<notes>
<note>Be more explicit. Maybe refer to <link id="TStringList"/></note>
<notes>
</module>

See also: ,

: Numbered list.

The tag starts a numbered list. It can contain only tags, which denote the various elements in the list. Each item will be preceded by a number. The tag can occur inside a text, but surrounding text should always be enclosed in a paragraph tag, i.e. an tag should occur always at the same level as a tag.

Example:

<p>some text before</p>
<ol>
<li>First item in the list</li>
<li>Second item in the list</li>
</ol>

Will be typeset as:

some text before

First item in the list.
Second item in the list.

See also: , .

: Paragraph

The tag is the paragraph tag. Every description text should be enclosed in a tag. Only when there is only one paragraph (and no lists or tables or remarks) in a description node, then the tag may be skipped.

Note that if a description node contains a , , or any list tag, then the text surrounding these tags must be put inside a paragraph tag. This is different from the behavior in HTML.

The paragraph tag must always have an opening tag and a closing tag, unlike html where only the opening tag may be present.

Example:

<descr>
This is a paragraph which need not be surrounded by paragraph tags.
</descr>

<descr>
<p>
This is the first paragraph.
</p>
<p>
This is the second paragraph.
</p>
</descr>

: Package reference

The tag indicates the package for which the description file contains documentation. A package is a collection of units which are logically grouped together (for a library, program, component suites). The attribute of the tag will be used to select the package node in the description file: Only the node with name as specified by the package command-line option will be used when generating documentation. All other package nodes will be ignored.

The node must always reside in a node. It can contain a node, and various nodes, one node per unit in the package.

See also: , ,

: Insert text as-is

The tag can be used to insert arbitrary text in the documentation. The text will not be formatted in any way, and will be displayed as it is encountered in the description node. It is functionally equivalent to the tag in HTML.

Note that if there is text surrounding the tag, it should be placed inside a paragraph tag.

Example:

<pre>
This is some text.
  This is some more text

    And yet more text...
</pre>

This will be typeset as:

This is some text.
  This is some more text

    And yet more text...

See also: ,

: insert short description

A tag can be used to insert the short description of an element in the current text. The name of the element whose short description must be printed must be given in the attribute. Typical use for this is to repeat the elements of an enumerated type when discussion function results or possible parameter values.

Example:

<dl>
<dt>float_round_nearest_even</dt><dd><printshort id="float_round_nearest_even"/></dd>
<dt>float_round_down</dt><dd><printshort id="float_round_down"/></dd>
<dt>float_round_up</dt><dd><printshort id="float_round_up"/></dd>
<dt>float_round_to_zero</dt><dd><printshort id="float_round_to_zero"/></dd>

: format as remark

A tag can be used to make a paragraph stand out. The is equivalent to the tag, but it’s contents is formatted in a way that makes it stand out from the rest of the text.

Note that any text before or after the tag must be enclosed in paragraph () tags.

Example:

<p>Normal text.</p>
<remark>
This text will stand out.
</remark>
<p>Again normal text.</p>

Will be formatted as

Normal text.

Remark: This text will stand out.

Again normal text.

See also: , ,

: Cross-reference section

The section can occur inside any tag, and will be used to create a list of cross-references. The contents of the tag is a list of tags. No other text is allowed inside this tag. Note that both the long and short form if the link tag may be used.

Example:

<seealso>
<link id="TStrings"/>
<link id="TStringList.Create">Create</link>
</seealso>

See also: ,

: Short description

The short description is used to give a short description of an identifier. If possible, the description should fit on a single line of text. The contents of this tag will be used for the following purposes:

Used as the synopsis on a page that describes an identifier.
Used in overviews of constants, types, variables, record fields, functions and procedures, classes, and for method and property listings of classes.
Replaces the tag in an if no tag is present.
In the description of an enumerated type, the enumeration values are typeset in a table, each row containing the name of the value and the short description.
In the description of a function or procedure that accepts arguments, the arguments are followed by their short description.
In the declaration of a class or record, each method, field or property is followed by the short description.

Example:

<element name="MyEnum.meOne">
<short>First element of MyEnum</short>
</element>

See also: ,

: Table start

The table tag starts a table, as in HTML. A table can contain (table row), (table header row) or tags. Any text surrounding the table must be enclosed in paragraph tags ().

Example:

<table>
<caption>
<var>TALignment</var> values and their meanings.
</caption>
<th><td>Value</td><td>Meaning</td></th>
<tr>
  <td><var>taLeftJustify</var></td>
  <td>Text is displayed aligned to the left.</td>
</tr>
<tr>
  <td><var>taRightJustify</var></td>
  <td>Text is displayed aligned to the right</td>
</tr>
<tr>
  <td><var>taCenter</var></td>
  <td>Text is displayed centred.</td>
</tr>
</table>

Will be formatted approximately as follows:

Value	Meaning
`taLeftJustify`	Text is displayed aligned to the left.
`taRightJustify`	Text is displayed aligned to the right
`taCenter`	Text is displayed centred.

See also: , , ,

: Table cell

The tag is used to denote one cell in a table. It occurs inside a or tag, and can contain any text and formatting tags.

Example:

<table>
<tr><td>Cell (1,1)</td><td>Cell (2,1)</td></tr>
<tr><td>Cell (1,2)</td><td>Cell (2,2)</td></tr>
</table>

Will be formatted approximately as

Cell (1,1)	Cell (2,1)
Cell (1,2)	Cell (2,2)

See also: , ,

: Table header

The th table header tag is used to denote the first row(s) of a table: It (they) will be made up differently from the other rows in the table. Exactly how it is made up depends on the format. In printed documentation (latex) a line will be drawn under the row. In HTML, the font and background may be formatted differently.

The tag can only occur inside a tag, and can contain only tags.

Example:

<table>
<th><td>Cell (1,1)</td><td>Cell (2,1)</td></th>
<tr><td>Cell (1,2)</td><td>Cell (2,2)</td></tr>
</table>

Will be formatted approximately as

Cell (1,1)	Cell (2,1)
Cell (1,2)	Cell (2,2)

See also: ,

: Topic section

The topic tag starts a topic page or section. A topic page or section is not linked to an identifier in some unit: it exists by itself. It must be inside a or tag. It must have a attribute (for cross-referencing). If it appears inside a , it can be nested: a may be inside another tag.

<module name="CRT">
<topic name="UsingKeyboard">
<short>Using the keyboard functions</short>
<descr>
To use the keyboard functions of the CRT unit, one...
</descr>
</topic>

: table row

The tag denotes a row in a table. It works the same as in HTML. It can occur only in a tag, and should contain only table data tags.

Example:

<table>
<tr><td>Cell (1,1)</td><td>Cell (2,1)</td></tr>
<tr><td>Cell (1,2)</td><td>Cell (2,2)</td></tr>
</table>

Will be formatted approximately as

Cell (1,1)	Cell (2,1)
Cell (1,2)	Cell (2,2)

See also: , ,

: Format underlined

Example:

Normal text <u>underlined text</u> normal text.

will be formatted as:
Normal text underlined text normal text.

See also: , .

: bulleted list

The ul tag starts a bulleted list. This works as under HTML, with the exception that any text surrounding the list must be enclosed in paragraph tags (). The list elements should be enclosed in tags.

Example:

<p>some text before</p>
<ul>
<li>First item in the list</li>
<li>Second item in the list</li>
</ul>

Will be typeset as:

some text before

First item in the list.
Second item in the list.

See also: , .

: Hyperlink

The url tag is meant to include an URL to an arbitrary web page. It works much like the tag, except that any URL may be specified. The attribute specifies the URL to link to. In output formats that support links, the text in the tag will be the link’s text. For other formats, the URL will be printed after the text.

If the tag does not enclose any text, then the URL itself will be printed.

Examples:

The normal usage is:

<url href="http://www.freepascal.org/">Here</url> 
is the website of Free Pascal.

It will be typeset as:

Here is the website of Free Pascal.

The short usage is:

Check out the following site: <url href="http://www.freepascal.org/"/>.

Which will be typeset as:

Check out the following site: http://www.freepascal.org/.

: variable

The tag is used to mark a piece of text as a variable (or, more general, as an identifier). It will be typeset differently from the surrounding text. Exactly how this is done depends on the output format.

Example:

The <var>Items</var> property gives indexed access to...

Will be typeset as

The Items property gives indexed access to...

: version info

The can be used to give version information: as of what version an identifier appeared or was deprecated. It should be specified below the tag, and will be output in the documentation. It can contain the same tags as the tag, and is typeset in the same way.

The following is an example:

<element name="myenum">
<descr>
The MyEnum type is a simple enumeration type which is not
really useful, except for demonstration purposes.
</descr>
<version>The myenum type appeared in version 2.1</version>
</element>

See also: , , ,

An experiment, built from development snapshots. Not the official Free Pascal or Lazarus documentation.