LuaDoc
Documentation Generator Tool for the Lua language

Introduction

LuaDoc is a documentation generation tool for lua source files. It does not impose a documentation format, but suggests one (XHTML) and implements it. The produced documentation can be of any type.

LuaDoc can be used out-of-the-box, provided that the source code is documented in the proposed format.

Installation

LuaDoc tool is composed by two parts, a library, and a launcher script.

The library follows the package model for Lua 5.1, therefore it should be "installed". Refer to Compat-5.1 configuration section about how to install it properly.

The launcher script, namely luadoc.lua for Unix and luadoc.bat for Windows, should be installed in your system PATH, so that it can be executed.

LuaDoc also depends on two external packages: LuaFileSystem and LuaLogging, and you'll need to install them accordingly.

On Unix boxes, the file luadoc.lua could be used as a script; it's the same as:

lua5.1 luadoc.lua [options|files]

This is the main script: it will load LuaDoc library and process the specified files. Try luadoc.lua --help, it will show you all available options.

How to comment

LuaDoc looks for the sequence of three minus signs (---). This sequence of characters indicates the beginning of a documented comment. The documentation ends with the first line of code found.

The following code defines a function and its documentation.

--- Define special sequences of characters.
-- For each pair (find, subs), the function will create a field named with
-- find which has the value of subs.
-- It also creates an index for the table, according to the order of insertion.
-- @param subs The replacement pattern.
-- @param find The pattern to find.
function def_escapes (find, subs)
   local special = { t = "\t", n = "\n", ['"'] = '"', ['\\'] = '\\', }
   find = gsub (find, "\\(.)", function (x) return %special[x] or x end)
   subs = gsub (subs, "\\(.)", function (x) return %special[x] or x end)
   escape_sequences.n = escape_sequences.n+1
   escape_sequences[escape_sequences.n] = find
   escape_sequences[find] = subs
end

The first sentence (until the first period) will be the resume. The last two, which begins with -- @param, will compound the parameters section. The other lines will complete the description of the function. The corresponding documentation should be something like:

def_escapes (find, subs)
Define special sequences of characters. For each pair (find, subs), the function will create a field named with find which has the value of subs. It also creates an index for the table, according to the order of insertion.

Parameters

  • find: The pattern to find.
  • subs: The replacement pattern.

A good example is the LuaDoc system itself. You can build the documentation by executing the following line from the LuaDoc directory:

luadoc.lua *.lua

It will produce one HTML file for each Lua file and an index file. You can browse them here.

Tags

LuaDoc can parse some tags at each function or table documentation. Tags are indicated in the source code with a `@' character followed by the name of the tag:

@param
Describe function parameters. It also requires the name of the parameter.
@see
Refers to other functions or tables.
@return
Describe the returning value or values of the function.
@usage
Describe the usage of the function or variable.
@description
The description of the function or table. This is usually infered automatically.
@name
The name of the function or table definition. This is usually infered from the code analysis, and the programmer does not need to define it. If LuaDoc can infer the name of the function automatically it's even not recomended to define the name explicitally, to avoid redundancy.
@class
If LuaDoc cannot infer the type of documentation (function, table or module definition), the programmer can specify it explicitally.
@field
Describe a table field definition.
@release
Free format string to describe the module or file release.

Command line options

The luadoc command line script has some options:

-d <path>
Defines the output directory path. Default is the current dir.
-h, --help
Show help instructions
--noindexpage
Do not generate the index page.
--nofiles
Do not generate documentation focused on files.
--nomodules
Do not generate documentation focused on modules.
--doclet <doclet_module>
Doclet module used to generate output
--taglet <taglet_module>
Taglet module used to parse input code
-q, --quiet
Suppress info output
-v, --version
Print version information

Valid XHTML 1.0!

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