Home

About

BBDocugen is a project to enable proper code documentation in BlitzMax source code. Most elements of the program are styled after Doxygen and Javadoc (including the name, currently, but it may change), specifically in the way documentation comments are formatted (to some extent).

Using BBDocugen

Currently, BBDocugen is in a state where it does not produce documentation. The goal is to set up the parsing and extraction of information from source code to the point where information that is relevant to producing documentation can be formatted easily. Secondly, I am attempting to set up BBDocugen to produce more than HTML from the get-go, or to at least have a flexible means of formatting that documentation.

A command-line interface is in the works at the moment, but has not yet been merged into the master branch. Currently, you can programmatically create, load, and manipulate source pages using BBSourcePage from docugen.rb (or any other file that includes sourcepage.rb).

What this means is that there is currently more work being put into how source code information is being read and accessed, with less focus on what the output may look like right now. That being said, I’ll provide some information on how documentation is formatted in BBDocugen.

Formatting Comments

Blocks

Using BBDocugen, you format your documentation by beginning your comment with Rem:doc. As with all BlitzMax code, this is not case sensitive. Any text in the comment up until a tag is considered the ‘body’ of the documentation. This is usually the description of your function, type, field, etc. Closing your comment is the same as a regular block comment, end it with End Rem.

For example:

Rem:doc
	Returns the factorial of {n}
	@param:n	The number to calculate the factorial of.  Must be ≥ 1.
	@returns	-1 if {n} < 0, otherwise {n}!
EndRem
Function fac:Int(n:Int)
	If n < 0 Then
		Return -1
	EndIf
	
	Local x:Int = 1
	
	While n >= 1
		x :* n
		n :- 1
	Wend
	
	Return x
End Function

The first line describes the function. The second line describes the argument n. @param:n specifies that the tag is a parameter tag for the key, or argument, ‘n’. Keys are optional for all tags, but in the case of parameters are needed in order to properly specify which argument you are describing, otherwise the tag will go unused. The last line describes the return value of the function.

Tags

All tags have a name and a body. The tag name must be the first part of the line when introduced. A tag’s body can span multiple lines, including blank lines, and may be formatted however you want provided a line does not begin with an ‘@’ symbol. If a line must begin with an ‘@’ symbol, this symbol must be escaped using a backslash.

The syntax for tags is as follows:

@tag Tag body

Specifies a tag name and body, no key.

@tag:key Tag body

Specifies a tag name, key, and body.

@tag:"multi-word key" Tag body

Specifies a tag name, key, and body. When the tag name is wrapped in double quotes, you may place any character you like insideof the key. The key may not span multiple lines.

The regular expression for matching tags, BBRegex::DOC_TAG_REGEX, can be found in regexps.rb. (along with all other regular expressions that are commonly used).

Text Formatting

There is currently no set of rules as to how formatting will be applied to the text itself. I’m leaning towards using Markdown via Maruku for HTML and LaTeX formatting.