Tutorial on using DOCMODS (bbdoc)

I Wrote this document whilst documenting one of my own modules, and I hope you all find it very useful.
V1.0
------------------------------------------------------------
Command line

docMods.exe <module>

To document a module called ABCDelta.mod you would need the command line:

docMods.exe ABCDelta.mod

You can also document all modules in a module folder with the following (Which would document ABCDelta.mod and ABCGamma.mod, both subfolders of ABC.mod).

docMods.exe ABC.mod

A handy batch file, placed in your mods folder like this will be of enormous use.

call ..\bin\docmods ABC.delta
call ..\bin\docmods ABC.gamma
pause

Documentation:
In the following sections, please remember that the order of the bbDoc command is important, and you must make sure that there is NOT a carriage return between endRem and your statement otherwise this will not work.

Documenting your Modules:
In your module, immediately before your module name, add the bbdoc header.

Rem
	bbdoc:	The ABC Delta system for games.
	about:	This system allows the simple creation of games.
EndRem
Module ABC.delta

Anything you add into ModuleInfo command will be listed at the bottom of the documentation.

This is very handy for History and other information...

ModuleInfo "Author: Si Dunford"
ModuleInfo "Copyright: Si Dunford, Dorsai Technologies February 2007"
ModuleInfo "Purpose: Tutorial on DocMods"
ModuleInfo "Version: v1.10"

ModuleInfo "History v1.00: 22 Feb 2007 - Initial version"
ModuleInfo "History v1.10: 28 Feb 2007 - Produced modules"

Documenting your Functions:
For each function you wish to document, add a bbdoc header immediately before the function declaration.

Rem
	bbdoc:	Description of your function
	about:	Details about what the function does
	returns:	What the function returns.
EndRem
function myFunction()

Documenting your object Types:

Rem
	bbdoc:	Description of your type
	about:	Details about what the type does
EndRem
Type myType

Documenting your Type's Methods or functions

Rem
	bbdoc:	Description of your method
	about:	Details about what the method does
	returns:	What the method returns.
EndRem
Method myMethod()

Documenting globals in your types:

Rem
	bbdoc:	Description of your global variable
	about:	Details about what the variable is used for
EndRem
global myGlobal%

Documenting Keywords:
At the end of your module file, you may specify keywords that will be included in the documentation. These might be used for constants, or even instead of method/function descriptions. The choice is yours.

This example shows a keyword "KEYWORD", that is being added to your documentation.

Rem
	bbdoc:	Description of this keyword
	keyword:	KEYWORD
EndRem

Adding examples to your documentation:
In your mod folder create a subfolder called "doc". Within this folder will be created an HTML file by DocMods. If you create example files in this folder they are merged into your documentation.

For example; Lets say we have a function called delta(), and a small example of how it should be used.

'# DELTA
Rem
	bbdoc:	Obtain the delta of X
	about:	This function looks up the delta of the provided variable X
	returns:	INT
EndRem
function delta%( x% )
...
end function

Create a file in docs, called delta.bmx containing the following code:

'# DELTA EXAMPLE
nDelta = delta( x )

Using HTML in examples:
If you need to use HTML in your example files, you will need to replace all "<" signs with "&lt;" and all ">" with "&gt;".

If you wish to create links to other parts of the documentation, these can be added directly using HTML statements in about statement.

PLEASE NOTE:
There appears to be a bug in the docMods.exe, in that if you have two identical keywords then only the first is recongnised and the example appears for both of them..
In the following example, it is not possible to create an example for both TDelta.create() and TGamma.Create(), because both would need to be called create.BMX.

Rem
	bbdoc:	The ABC Delta system for games.
	about:	This system allows the simple creation of games.
EndRem
Module ABC.delta

'########################################
Rem
	bbdoc:	Description of your type
	about:	Details about what the type does
EndRem
type Tdelta

	Rem
		bbdoc:	Create TDelta
		about:	Creates an initialises a new TDelta object
		returns:	TDelta
	EndRem
	function create:Tdelta( img:Timage, y% )
	...
	end function
end type

'########################################
Rem
	bbdoc:	Description of your type
	about:	Details about what the type does
EndRem
type Tgamma

	Rem
		bbdoc:	Create TGamma
		about:	Creates an initialises a new TGamma object
		returns:	TGamma
	EndRem
	function create:Tgamma( x% )
	...
	end function
end type

Nice :-)

I've found, from my experience, that it's better to put returns: before about:, especially for multi-line about: sections.

Also, remember that the example .bmx file in /doc might not appear in the documentation if the case isn't exactly the same.

Good and informative.

Other goodies to add:

Use @ to make a word bold
Use # to make link which jumps to a bookmark
Use <br> for line breaks
Use <p> for paragraph breaks

In this example mem appears bold and the MemAloc and MemExtend are both links which jump to the location of the commands on the same page.

Rem
bbdoc: Free allocated memory
about: The memory specified by @mem must have been previously allocated by #MemAlloc or #MemExtend.
End Rem

Create tables like so:

<table>
<tr><th>Parameter</th><th>Desription</th></tr>
<tr><td>DOH_BANG</td><td>Make everything go bang</td></tr>
<tr><td>DOH_NOTHING</td><td>Do nothing</td></tr>
</table>

Can you use any HTML code you want as part of your doc?

You can put HTML code in the about: section and I guess you probably could in the rest of it if you needed to.

Oh... and another thing ;-)

You can create a file called intro.bbdoc in the /doc folder too.
The contents of this is added to the top of the module documentation, kind of like so:

+MODULE TITLE+

+INTRO.BBDOC+

+MODULE DOCS+

Very handy if you don't want to fill your code with introductory documentation and such-like. (A crazy example of this is my recent RegeEx module documentation).

:-)

bbdoc files
I've been reviewing the BlitzMax 1.26 bbdoc files, and I found the following worth documenting...

These files do not appear to be limited to intro.bbdoc. There are lots of them in the docs/source folder within the main BlitzMax folder. They contain various formatting, for example:

Prefixing a line with a "+" shows the text in a header style.

Prefixing a word with a "%" sign, makes it Italic.
Prefixing a word with a "@" sign makes it Bold.

If you want more than one word in Bold or Italic style above, enclose the words in braces, eg:

This is the @{best example I could think of}.

Enclosing text in double braces forces a code-block, eg:

{{
type TExample
  field x%
end type
}}

Bullet point lists can be created easily using:

[
* Bullet point one
* Bullet point two
]

A link to another document can be easily created by prefixing with a "#" for example:

This is a link to #another module.

Lastly, you can show tables, by seperating the cells with a "|", and including the whole thing in brackets "[...]".

[ @function | @description
* makeTea() | This makes the tea
* cookDinner() | This cooks your dinner
* kitchenSink() | Catch-all function
]

The double braces code block doesnt work for me, but this does:

&SingleWord
&{
MultiWord
Or
Line
}

Otherwise great list =)

Can this be used on non module files, so just plain .bmx files? I tried but on a file with a bbdoc section in it that I'd made but nothing seemed to happen...

AFAIK docmods works only with modules.

bummer looks like I have to turn it into a module then, or maybe I can just put some "module info" text at the top and not actually compile it into a mod and it'll work?

if you place something in the .mod-structure, it has to be a mod.

Why not just make it a mod or use the dual approach I've suggested to make both the includers and the modders happy ;)