Tutorial on using DOCMODS (bbdoc)
BlitzMax Forums/BlitzMax Tutorials/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 "<" and all ">" with ">". 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 ;) |
   |