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 and therefore should be "installed" in your
package.path.
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:
- @author <text>
- An author of the module or file.
- @copyright <text>
- The copyright notice of the module or file. LuaDoc adds a © sign between the label (Copyright) and the given text (e.g. 2004-2007 Kepler Project).
- @field
- Describe a table field definition.
- @param <word> <text>
- Describe function parameters. It requires the name of the parameter and its description.
- @release <text>
- Free format string to describe the module or file release.
- @return <text>
- Describe a returning value of the function. Since Lua can return multiple values, this tag should appear more than once.
- @see <text>
- Refers to other descriptions of functions or tables.
- @usage <text>
- Describe the usage of the function or variable.
Infered Tags
The following tags would be normally infered by LuaDoc, but they can be used to override the infered value.
- @class <word>
- If LuaDoc cannot infer the type of documentation (function, table or module definition), the programmer can specify it explicitly.
- @description
- The description of the function or table. This is usually infered automatically.
- @name <word>
- 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 explicitly, to avoid redundancy.
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