Docmaker 3
Introduction
Docmaker is a utility movie which can be used to generate script documentation in HTML format.
All the headings and method names have named anchors (and some internal links are created - which is more useful for long scripts).
How Does it work
Docmaker scans through the specified script cast members looking for two things: (a) Comments that begin with a "@" character; and (b) method names that begin with any character other than an underscore (it assumes that methods that begin with underscores are meant to be 'private' and excluded from the documentation.
(a) Announcements
Comments which begin with a "@" character are treated as 'script announcements'. Announcements look like this:
-- @Version: 1.0
-- @Author Luke Wigley
-- @Description
-- This script does some stuff that takes a bit of explaining.
-- It takes a couple of lines to explain what it does.
The first two announcements (@Version and @Author) are 'single line announcements'. All the text after the first word are treated as the 'value' of that announcement. Note that the docMaker parser is pretty flexible with white space and the use of a colon after the first word.
The third announcement doesn't have any text after it. In this case, docMaker assumes that any comment lines immediately after the announcment form the 'value' of that announcement.
(b) Methods
In the case of methods, docMaker assumes that any comments immediately after the method name form the description of that method. It also assumes that any comments after the method name that begin with a "*" character form 'parameter and return' descriptions. For example, if a method is written like this:
on MakeDoc (me, whichScriptMember)
-- This method will make HTML documentation of a script
-- * whichScriptMember should be a valid member reference
-- * Returns 0 or error number
The first comment line will be treated as forming the method description. The remaining lines will be formatted into a table which lists the method parameters and the return value.
(c) Formatting Options
The output HTML uses various DIVs and SPANs to mark up the various elements (headings, descriptions, etc). For example, the entire documentation is enclosed in a DIV called "LingoDoc". The Headings are enclosed in SPANs called "FieldName" and have named anchors. The method descriptions are enclosed in a DIV called "LingoMethodEntry".
Some special formatting is done. For example,
- Any comments starting with 2 or more spaces are assumed to be lingo snippets (and are enclosed in a special span)
- Any comments that begin with a # character and formatted into a HTML list.
- When describing parameters, you can enclose the parameter type in {curly braces} to have it formatted using a 'LingoParamType' span.
Using the Utility Movie
Screenshot of Docmaker
The movie requires the PregEx Xtra, OS Controls Xtra and Buddy API Xtras to do its stuff). Download a Zipped version. Put it in your Xtras folder and access it from the Xtras menu.