Documentation format

Documentation is created in a format developed at Charta Software and is located in .documentation files which correspond to the identically named .pas files.

Documentation files

The documentation for a unit resides in a file that has the same name as the unit but has the extension ".documentation". This documentation file uses an XML based syntax. Here is an example of a .documentation file:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 <Documentation> <Symbol Name="TInputStream"> <Lead>An input stream implements a stream of bytes which can be read from front to end.</Lead> <Description> <P> Streams can have a definite or indefinite size but this fact is not known to the user of the stream. To check whether the stream has reached its end one can check <Symbol Name="AtEnd"/>. If <Code>False</Code> is returned, this does not necessarily mean that there are more bytes to read. If <Code>True</Code> is returned one can be sure that the stream has no more bytes and reading more would result in an exception. The function <Symbol Name="Available"/> returns the amount of bytes that are known to be still available. This function might return zero while in fact there are still more bytes to read. Implementors of <Symbol Name="Available"/> are encouraged to return the largest value that can be known to be available without having to implement buffering schemes. </P> <P> When decoding multi-byte simple values the order of the constituting bytes can either be big endian (higher order bytes first) or little endian (lower order bytes first). A <Symbol Name="TInputStream"/> provides functions to read simple values using either big or little endian encoding. These functions work correctly regardless of the endianness of the underlying platform. </P> </Description> <Symbol Name="Available"> <Lead>Returns the known amount of bytes available to read, can be zero which does not indicate the end of the stream.</Lead> </Symbol> <Symbol Name="AtEnd"> <Lead>Indicates whether the stream has no more bytes to read, when <Code>False</Code> is returned this does not guarantee that there are more bytes to read.</Lead> </Symbol> <Symbol Name="Read"> <Lead>Reads <Code>Count</Code> bytes from the stream and throws an exception when reading beyond the end of the stream.</Lead> </Symbol> <Symbol Name="Skip"> <Lead>Skips <Code>Count</Code> bytes from the stream and throws an exception when reading beyond the end of the stream.</Lead> </Symbol> </Symbol> </Documentation>

Syntax

The main XML elements used in the documentation format are:

ElementDescription
<Documentation>Document element
<Symbol Name="..."> Defines a symbol or refers to the symbol with the provided name. When defining a symbol it can contain a <Lead> element and a <Description> element.
<Lead>Provides a short introductory description of the symbol. This element can contain general structured document syntax.
<Description>Provides the rest of the description of the symbol, information from the <Lead> should not be repeated. This element can contain general structured document syntax.
<Code [Type="inline|block"]>Provides a small snippet of code that can be either inline or a code block. Code is displayed inline by default.

When specifying the name of a symbol the following scoping rules are used to resolve the Pascal symbol from the source code:

  • If the symbol name contains no dots,
    • and the <Symbol> element is a direct child of the <Documentation> element, the symbol is searched in the unit scope.
    • and the <Symbol> element is a direct child of an other <Symbol> element, the symbol is searched in the scope of the enclosing symbol.
  • If the symbol name contains dots, the provided name should be a fully qualified identifier of the symbol.

Please note that the documentation format only supports documenting symbols, that is, code elements that have unique names. Symbols can be identified by a fully qualified path separated by dots. As opposed to Pascal code, the documentation format allows any symbol to be referred using the dot notation, even parameters to a function. For instance, Minimum.Left can refer to parameter Left of function Minimum.