<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>LuaDoc: Documentation Generator Tool for the Lua language</title>
<link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"><a href="http://www.keplerproject.org">
<img alt="LuaDoc logo" src="lua.png"/>
</a></div>
<div id="product_name"><big><b>LuaDoc</b></big></div>
<div id="product_description">Documentation Generator Tool for the Lua language</div>
</div> <!-- id="product" -->
<div id="main">
<div id="navigation">
<h1>LuaDoc</h1>
<ul>
<li><a href="index.html">Home</a>
<ul>
<li><a href="index.html#overview">Overview</a></li>
<li><a href="index.html#status">Status</a></li>
<li><a href="index.html#download">Download</a></li>
<li><a href="index.html#dependencies">Dependencies</a></li>
<li><a href="index.html#history">History</a></li>
<li><a href="index.html#credits">Credits</a></li>
<li><a href="index.html#contact">Contact us</a></li>
</ul>
</li>
<li><strong>Manual</strong>
<ul>
<li><a href="manual.html#introduction">Introduction</a></li>
<li><a href="manual.html#installation">Installation</a></li>
<li><a href="manual.html#howto">How to</a></li>
<li><a href="manual.html#tags">Tags</a></li>
<li><a href="manual.html#options">Options</a></li>
</ul>
</li>
<li><a href="architecture.html">Customizing</a>
<ul>
<li><a href="architecture.html#architecture">Architecture</a></li>
<li><a href="architecture.html#taglet">Taglet</a></li>
<li><a href="architecture.html#documentation">Documentation</a></li>
<li><a href="architecture.html#doclet">Doclet</a></li>
</ul>
</li>
<li><a href="examples.html">Examples</a></li>
<li><a href="http://luaforge.net/projects/luadoc/">Project</a>
<ul>
<li><a href="http://luaforge.net/tracker/?group_id=18">Bug Tracker</a></li>
<li><a href="http://luaforge.net/scm/?group_id=18">CVS</a></li>
</ul>
</li>
<li><a href="license.html">License</a></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="introduction">Introduction</a></h2>
<p>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.
</p>
<p>
LuaDoc can be used out-of-the-box, provided that the source code is documented in
the proposed format.
</p>
<h2><a name="installation">Installation</a></h2>
<p>LuaDoc tool is composed by two parts, a library, and a launcher script.</p>
<p>
The library follows the
<a href="http://www.keplerproject.org/compat/">package model</a>
for Lua 5.1 and therefore should be "installed" in your
<code>package.path</code>.
</p>
<p>
The launcher script, namely <code>luadoc.lua</code> for Unix and <code>luadoc.bat</code>
for Windows, should be installed in your system <code>PATH</code>, so that it can be executed.
</p>
<p>
LuaDoc also depends on two external packages:
<a href="http://www.keplerproject.org/luafilesystem">LuaFileSystem</a> and
<a href="http://www.keplerproject.org/lualogging">LuaLogging</a>, and you'll
need to install them accordingly.
</p>
<p>
On Unix boxes, the file luadoc.lua could be used as a script; it's the same as:
</p>
<pre class="example">
lua5.1 luadoc.lua [options|files]
</pre>
<p>
This is the main script: it will load LuaDoc library and process the specified
files. Try <code>luadoc.lua --help</code>, it will show you all available options.
</p>
<h2><a name="howto">How to comment</a></h2>
<p>
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.
</p>
<p>
The following code defines a function and its documentation.
</p>
<pre class="example">
--- 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
</pre>
<p>
The first sentence (until the first period) will be the resume.
The last two, which begins with <code>-- @param</code>, will compound the
parameters section.
The other lines will complete the description of the function.
The corresponding documentation should be something like:
</p>
<dl class="example function">
<dt><a name="def_escapes"></a><strong>def_escapes</strong> (find, subs)</dt>
<dd>
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.
<h3>Parameters</h3>
<ul>
<li>find: The pattern to find.</li>
<li>subs: The replacement pattern.</li>
</ul>
</dd>
</dl>
<p>
A good example is the LuaDoc system itself.
You can build the documentation by executing the following line from the
LuaDoc directory:
</p>
<pre class="example">
luadoc.lua *.lua
</pre>
<p>
It will produce one HTML file for each Lua file and an index file.
You can browse them <a href="api/index.html">here</a>.
</p>
<h2><a name="tags">Tags</a></h2>
<p>
LuaDoc can parse some tags at each function or table documentation.
Tags are indicated in the source code with a `<code>@</code>' character
followed by the name of the tag:
</p>
<dl>
<dt>@author <text></dt>
<dd>An author of the module or file.</dd>
<dt>@copyright <text></dt>
<dd>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).</dd>
<dt>@field</dt>
<dd>Describe a table field definition.</dd>
<dt>@param <word> <text></dt>
<dd>Describe function parameters.
It requires the name of the parameter and its description.</dd>
<dt>@release <text></dt>
<dd>Free format string to describe the module or file release.</dd>
<dt>@return <text></dt>
<dd>Describe a returning value of the function.
Since Lua can return multiple values, this tag should appear more
than once.</dd>
<dt>@see <text></dt>
<dd>Refers to other descriptions of functions or tables.</dd>
<dt>@usage <text></dt>
<dd>Describe the usage of the function or variable.</dd>
</dl>
<h3><a name="infered-tags">Infered Tags</a></h3>
<p>
The following tags would be normally infered by LuaDoc,
but they can be used to override the infered value.
</p>
<dl>
<dt>@class <word></dt>
<dd>If LuaDoc cannot infer the type of documentation (function, table or
module definition), the programmer can specify it explicitally.</dd>
<dt>@description</dt>
<dd>The description of the function or table.
This is usually infered automatically.</dd>
<dt>@name <word></dt>
<dd>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.</dd>
</dl>
<h2><a name="options">Command line options</a></h2>
<p>
The luadoc command line script has some options:
</p>
<dl>
<dt>-d <path></dt>
<dd>Defines the output directory path. Default is the current dir.</dd>
<dt>-h, --help</dt>
<dd>Show help instructions</dd>
<dt>--noindexpage</dt>
<dd>Do not generate the index page.</dd>
<dt>--nofiles</dt>
<dd>Do not generate documentation focused on files.</dd>
<dt>--nomodules</dt>
<dd>Do not generate documentation focused on modules.</dd>
<dt>--doclet <doclet_module></dt>
<dd>Doclet module used to generate output</dd>
<dt>--taglet <taglet_module></dt>
<dd>Taglet module used to parse input code</dd>
<dt>-q, --quiet</dt>
<dd>Suppress info output</dd>
<dt>-v, --version</dt>
<dd>Print version information</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
<p><small>$Id: manual.html,v 1.10 2007/10/12 13:33:45 tomas Exp $</small></p>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
