Element names and cross-referencing

Element name conventions

As mentioned in the previous section, the element tag’s attribute is hierarchical. All levels in the hierarchy are denoted by a dot (.) in the name attribute.

As shown in the previous example, for an enumerated type, the various enumeration constants can be documented by specifying their name as enumname.constname. For example, given the type

Type
  MyEnum = (meOne,meTwo,meThree);

The various enumeration values can be documented using the element names MyEnum.meOne, MyEnum.meTwo and MyEnum.meThree:

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

Note that the casing of the name attribute need not be the same as the casing of the declaration.

This hierarchical structure can be used for all non-simple types:

• Enumeration type values.

• Fields in records, objects, classes. For nested record definitions, multiple levels are possible in the name.

• Methods of classes and objects.

• Properties of classes.

• Function and procedure arguments.

• Function results. The name is always the function name followed by Result.

Cross referencing: the link tag

To refer to another point in the documentation (a related function, class or whatever), a tag exists. The link tag takes as a sole attribute a target attribute. The link tag usually encloses a piece of text. In the HTML version of the documentation, this piece of text will function as a hyperlink. In the latex version, a page number reference will be printed.

The attribute contains the name of an element to which the link refers. The name is not case sensitive, but it must be a fully qualified name.

An example of the link type would be:

The <link id="MyEnum">MyEnum</link> type is a simple type.

The link attribute also has a short form:

The <link id="MyEnum"/> type is a simple type.

In the short form, the value of the attribute will be used as the text which will be hyperlinked. This is especially useful in the tag.

To refer to a type in another unit, the unit name must be prepended to the attribute:

<link id="myunit.myenum"/>

will link to the myenum type in a unit named myunit.

To refer to a node in the documentation of another package, the package name should be prepended to the attribute, and it should be prepended with the hash symbol (#):

<link id="#fcl.classes.sofrombeginning"/>

will link to the constant sofrombeginning in the classes unit of the FCL reference documentation. Note that for this to work correctly, the contents file which was created when generating the documentation of the type must be imported correctly (see the import option).