Cerberus X Documentation

Makedocs

The Makedocs tool converts Cerberus X documentation to html.

All documentation may use markdown formatting.

General documentation

General documentation files should have a '.cerberusdoc' extension, and should be placed in the docs/cerberusdoc directory.

Markdown links in general documentation

Documentation pages may be linked to using the relative filepath as a link target. For example, if you have added a Tools/MakeImages.cerberusdoc file, any file in the Tools directory can link to it using [[MakeImages]].

Files outside the Tools directory can also link to MakeTools using using [[Tools/MakeImages]]. The link text will have the directory stripped so will appear simply as 'MakeImages'.

A plain [[MakeImages]] is also likely to work even outside the Tools directory, as the link resolver will eventually find MakeTools in the main Index, but it may clash with other definitions of MakeImages so a fully qualified link is preferred.

Module documentation

There are two ways to document a module - either by placing documentation 'in source' within the actual module source code by way of 'cerberusdoc comments', or in a separate cerberusdoc file.

Documenting modules in Cerberus X source code

To document a module declaration, you should precede the declaration with a cerberusdoc comment. A cerberusdoc comment is a block comment starting with the line #Rem cerberusdoc

For example.

#Rem cerberusdoc
Documentation for MyFunction goes here.
#End
Function MyFunction:Void()
...etc...

In addition, the first cerberusdoc comment in the file must be of the form...

#Rem cerberusdoc Module my.module
Documentation for my.module goes here...
#End

...where my.module is the full module path of your module.

Documenting modules using an external cerberusdoc file

You may also document a module using an external cerberusdoc file. This file should either be in the same directory as the module Cerberus X source file, or in a cerberusdoc subdirectory, and must have the same name as the module source file but with a '.cerberusdoc' extension instead of '.cxs'.

For example, given the module source file:

modules/flixel/flixel.cxs

The corresponding cerberusdoc file may be located either here...

modules/flixel/flixel.cerberusdoc

...or here...

modules/flixel/cerberusdoc/flixel.cerberusdoc

Declarations in a cerberusdoc file are normal Cerberus X declarations, but must be preceded by a '# '. Declarations must appear BEFORE the actual documentation.

In addition, a cerberusdoc file must start with a '# Module my.module' declaration.

For example:

# Module my.module

# Import brl.stream
# Import brl.markdown

Documentation for my.module goes here.

# Function MyFunction:Void()

Documentation for MyFunction goes here.

Markdown links in module documentation

Links to declarations may be created simply by specifying the declaration identifier. The link resolver will attempt to find the correct declaration given the scope of the source documentation.

Links to declarations may also be absolute, in which case a full declaration path should be provided. For example, [[mojo.graphics]] will link to the mojo.graphics module. Absolute links to non-scope declarations should use #identifier to specify the 'leaf' declaration, for example [[mojo.graphics#DrawImage]] will link to the DrawImage function in the mojo.graphics module.

Links may also be created to general documentation, using the same rules as given in the above section 'Markdown links in general documentation'.

Adding examples to module documentation

You may add examples using an 'Example:' section, eg:

#Rem cerberusdoc

Frobozz the whirligig

Example:
<pre>
Function Main()
Print Frobozz( "Yes!" )
End
</pre >
#End
Function Frobozz:Void( str:String )
'...etc...

In addition, you can add example programs in Cerberus X source code form to an 'examples' directory located in the same directory as the .cxs or .cerberusdoc file the docs are located in.

Such example programs should have the same name as the declaration they are providing an example for, with an '_example' suffix. For example, example code for the above function would be named 'Frobozz_example.cxs'.

Adding links to module documentation

Documentation may also in include a links section, eg:

Links: [[X]], [[Y]], [[Z]]

Links will be emitted in a 'links' or 'see also' section.