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.