4.1 Introduction

The description le 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 le. 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 le would look something like this:

The header xml tag is mandatory, and indicates that the le 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.

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 lled with the documentation for each identier that appears in the unit interface header.

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

For example, to document the type

Type
MyEnum = (meOne,meTwo,meThree);

an element tag called myenum should exist:

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

As it can be seen, the names of the identiers 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 ll 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:

The MyEnum type is a simple enumeration type which is not
really useful, except for demonstration purposes.

A second important tag is the short tag. It should contain a short description of the identier, preferably a description that ts 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 dierent other cases: For instance the dierent values of an enumeration type will be laid out in a table, using the short description:

The first enumeration value

The second enumeration value

The third enumeration value

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

meOne	The rst 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 dierent 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 (126).

To add a section or page of documentation that is not directly related to a single identier 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 identiers.

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:

Using the keyboard functions

To use the keyboard functions of the CRT unit, one...

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

[next] [front] [up]