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:
Element | Description |
---|---|
<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.
- and the
- 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
.