cldoc tries to make documenting your code as simple as possible. This page describes the format for documenting various parts of your code.
To associate documentation with a particular symbol, element or section of your code, cldoc takes the same approach as other existing documentation tools. You simply write a comment right above the symbol that you wish to document.
The format to document a symbol is simple. Lets start with a class.
A documentation section begins with an ordinary comment (so not
continues over the next lines. Multiple comments following eachother are automatically
concatenated together. Both multiline and single line comments can be used. To write
comments that are not part of the public documentation, use
The actual comment consists of several parts. Documentation for all symbols
always has a
brief section and a
body section. The
brief section consists
of the first line of the comment (and is not optional). The
is optional, and makes up the rest of the comment. There are two other
sections which are used for functions and methods
(we’ll come to that later).
The last thing that is noteworthy is the use of
<RingBell> to create a cross-reference
to another symbol. When the documentation is extracted, all cross-references
are resolved from their current context (same as c++ itself does). So, we can
RingBell from the
Bicycle documentation, but from outside
Bicycle we need to use
Lets extend our standard bicycle class with a racing bike.
Here we see a new feature. When we implement the
RacingBike subclass, we
Bicycle. Here we are going to reimplement
it doesn’t really make sense to write another piece of documentation for
the function (it will still do the same, just differently implemented). Here
we can use the special
@inherit comment which will copy the documentation
from the first base class which has a comment specified for the
method. This of course only works for
Functions and Methods
We have seen most of the basic documentation comment syntax. There is still some specific syntax left for documenting functions and methods.
Here we document the arguments and the return value of a method. The syntax,
again, is simple. You use @name to document an argument, directly after the
brief section. Following the last parameter is the
body. For methods with
a return value, the
@return documents the return value after the
Grouping symbols in categories
Symbols can be grouped in categories to improve logical separation of different
parts of your code. Normally, with C++ this is not so much of a necessity since
code should already be segmented by namespaces and classes. However, for C API,
this is not the case. To move a particular symbol into a category, you can
use add the following
directives around the symbols you want to move:
The category name can be anything, as long as it doesn’t collide with any symbol
names. Categories can be nested just as any other symbol by using the
Documentation for categories can be written using external documentation files, which is explained in the next section.
Writing external documentation
It’s often useful to write documentation in separate, external files instead of having to write everything in a C++ file. For example, namespaces often do not have a logical location to write documentation. Another reason is that writing large pieces of documentation as C++ comments is cumbersome.
cldoc supports writing external documentation as markdown files (files ending
on .md). These files are read from a directory specified with the
option of cldoc (see Generating site for more information).
Each .md file contains one or more special headers which refer to the particular
symbol that it’s documenting:
symbol is the C++ identifier (for example
transport to document the
transport namespace). A file can contain more than one section so you don’t
have to write separate files for each symbol. The special symbol name
can be used to add a description to the main documentation index page.
Merged markdown files can include other files by using the special
instruction, which includes the file specified at
filepath (relative to the
currently being parsed file).
Externally documented symbols which cannot be resolved when generating the documentation, will automatically create a category with the symbol as the name. This is useful because it allows you to easily write additional documentation (like a manual or tutorial) by just writing simple .md files.