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 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.

## Text indentation and linebreaks

LuaDoc parses text in such a way that it concatenates text on individual lines and removes trailing and leading whitespace in the process. To prevent LuaDoc from doing this and to retain the original linebreaks and indentation end the tag with a ``#`' character, for example '`@usage#`'. This is especially usefull for multiline code examples in the usage tag, where you want the example code to remain properly indented for readability. Run LuaDoc on the included test file to see the results. Warning; you must make sure that the doclet you are using supports this format.

## 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

$Id: manual.html,v 1.10 2007/10/12 13:33:45 tomas Exp $