LuaDoc: Documentation Generator Tool for the Lua language

LuaDoc

Documentation Generator Tool for the Lua language

Architecture

LuaDoc's processing can be divided in two distinct steps: parsing and generation. The parsing step take as input a set of .lua files and must produce a Documentation object. A generator takes a Documentation object as input and produces a set of output files. It's up to the generator to decide which output format it will generate.

The parsing step is executed by a component called taglet, while the generation is handled by a component called doclet. This architecture is shown below.

Architecture

Taglet

LuaDoc does not impose a documentation format. It does relies on an internal representation of the documentation. This representation is described in the Documentation section. If the developer wants to use a custom documentation format the taglet component can be replaced.

Writing a new taglet is a matter a implementing a single method:

function start (files, doc)

files: a list of file (or directory) names.
doc: a preprocessed documentation object.

LuaDoc comes bundled with a standard taglet implementation. This implementation takes all file names in the list and produce the documentation object using a set of tags described in the section How To. If an item in the list is a directory it iterates recursively throw all files in the directory looking for filenames with .lua or .luadoc extensions.

Documentation

Instead of defining a documentation format LuaDoc defines an internal representation of a documentation object. Taglets and doclets must conform with this format.

The documentation object is described below. Some description elements are explained below:

List

table indexed by number. Example: List<string> { [1] = "x", [2] = "y", [3] = "z", }

HashMap

table whose numerical indices are the key values for objects. Example: HashMap<string, string>

{
 [1] = "x",
 [2] = "y";
 [3] = "z";
 ["x"] = "x coord",
 ["y"] = "y coord",
 ["z"] = "z coord",
 }

DOCUMENTATION

{
 files = HashMap<string, DOCUMENTATION_ELEMENT>, -- indexed by file name
 modules = HashMap<string, DOCUMENTATION_ELEMENT>, -- indexed by module name
}

DOCUMENTATION_ELEMENT

{
 type = ["file" | "module"],
 name = <string>, -- full path of file or name of module
 doc = List<BLOCK>, -- all documentation blocks
 functions = HashMap<string, BLOCK>, -- only functions, indexed by function name
 tables = HashMap<string, BLOCK>, -- only table definitions, indexed by table name
 },
}

BLOCK

{
 class = ["module" | "function" | "table"],
 name = <string>,
 summary = <string>,
 description = <string>,
 comment = List<string>,
 code = List<string>,
 param = HashMap<string, string>,
},

Doclet

The primary job of an doclet is to take a Documentation object and generate some kind of output. LuaDoc is bundled with an implementation that generates HTML files.

Writing a new doclet is a matter a implementing a single method:

function start (doc)

doc: a documentation object.

$Id: architecture.html,v 1.5 2007/08/13 15:32:45 carregal Exp $