4.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="ISO8859-1"?>
 <fpdoc-descriptions>
 <package name="fpc">
 <module name="Classes">
 </module>
 </fpdoc-description>
 </package>

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:

meOne	The first enumeration value
meTwo	The second enumeration value
meThree	The third enumeration value

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

[next] [front] [up]