5.1 Introduction

The description file is a XML document, which means that it is a kind of HTML or SGML like format, however it is more structured than HTML, making it easier to parse - and makes it easier to connect or merge it with a Pascal source file. Since the allowed syntax uses a lot of HTML tags, this makes it easy to write code for those that are familiar with writing HTML.

More information about the XML format, SGML and HTML can be found on the website of the W3 (World Wide Web) consortium: http://www.w3.org/

The remaining of this chapter assumes a basic knowledge of tags, their attributes and markup language, so these terms will not be explained here.

The minimal documentation file would look something like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-description>
<package name="fpc">
<module name="Classes">
</module>
</package>
</fpdoc-description>

The header xml tag is mandatory, and indicates that the file contains a documentation XML document.

Inside the document, one or more top-level fpdoc-descriptions tags may appear. Each of these tags can contain one or more package tags, which must have a name attribute. The name attribute will be used by fpdoc to select the documentation nodes.

Inside a package tag, one or more module tags may appear. There should be one module tag per unit that should be documented. The value of the name attribute of the module should be the name of the unit for which the module tag contains the documentation. The value of the name attribute is case insensitive, i.e.

<module name="CRT">

can be used for the documentation of the crt unit.

As it is above, the documentation description does not do much. To write real documentation, the module tag must be filled with the documentation for each identifier that appears in the unit interface header.

For each identifier in the unit interface header, the module should contain a tag that documents the identifier: this is the element tag. The name attribute of the element tag links the documentation to the identifier: the name attribute should have as value the fully qualified name of the identifier in the unit.

For example, to document the type

Type
  MyEnum = (meOne,meTwo,meThree);

an element tag called myenum should exist:

<element name="myenum">
</element>

But also for each of the three enumerated values an element tag should exist:

<element name="myenum.meOne">
</element>
<element name="myenum.meTwo">
</element>
<element name="myenum.meThree">
</element>

As it can be seen, the names of the identifiers follow a hierarchical structure. More about this in the next section.

Now the tags for the types are present, all that should be done is to fill it with the actual description. For this, several tags can be placed inside a element tag. The most important tag is the descr tag. The contents of the descr tag will be used to describe a type, function, constant or variable:

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

A second important tag is the short tag. It should contain a short description of the identifier, preferably a description that fits on one line. The short tag will be used in various overviews, at the top of a page in the HTML documentation (a synopsis) or will be used instead of the descr tag if that one is not available. It can also be used in different other cases: For instance the different values of an enumeration type will be laid out in a table, using the short description:

<element name="myenum.meOne">
<short>The first enumeration value</short>
</element>
<element name="myenum.meTwo">
<short>The second enumeration value</short>
</element>
<element name="myenum.meThree">
<short>The third enumeration value</short>
</element>

This will be converted to a table looking more or less like this:

For functions and procedures, a list of possible error conditions can be documented inside a errors tag. This tag is equivalent to the descr tag, but is placed under a different heading in the generated documentation.

Finally, to cross-reference between related functions, types or classes, a seealso tag is also introduced. This will be used to lay out a series of links to related information. This tag can only have sub-tags which are link tags. For more about the link tag, see link (195).

If a certain identifier has appeared only in a certain version of a library, then this information can be specified in a version tag, see version (242) for more information.

The following example illustrates the use:

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

When documenting methods or properties, it is possible to let the fpdoc engine refer to the parent method when it generates an overview of methods or properties. There are 2 ways of achieving this:

1. Do not include an element tag

2. Specify the link attribute, with the name of the parent method which contains the documentation, as in the following example:

        <element name="TParent.SomeMethod">
        </element
        
        <element name="TChild.SomeMethod" link="TParent.SomeMethod"/>
   

   this can be used to speed up the search for the parent implementation, or to skip several parent classes.

To add a section or page of documentation that is not directly related to a single identifier in a unit, a topic tag can be used. This tag can appear inside a package or module tag, and can contain a short or descr tag. The contents of the short tag will be used for the title of the section or page. In on-line formats, a short list of related topics will appear in the package or module page, with links to the pages that contain the text of the topics. In a linear format, the topic sections will be inserted before the description of all identifiers.

If the topic appears in a package tag, then it can be nested: 2 levels of topics may be used. This is not so for topics inside a module: they can not be nested (the level of nesting in a linear documentation format is limited).

The following is an example of a valid topic 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>

Topic nodes can be useful to add ’how to’ sections to a unit, or to provide general IDE help.