214 lines
6.7 KiB
HTML
Executable File
214 lines
6.7 KiB
HTML
Executable File
<!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><a href="manual.html">Manual</a>
|
|
<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><strong>Customizing</strong>
|
|
<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="architecture"></a>Architecture</h2>
|
|
|
|
<p>
|
|
LuaDoc's processing can be divided in two distinct steps: parsing and
|
|
generation. The parsing step take as input a set of <code>.lua</code> files
|
|
and must produce a <code>Documentation</code> object. A generator takes a
|
|
<code>Documentation</code> object as input and produces a set of output files.
|
|
It's up to the generator to decide which output format it will generate.
|
|
</p>
|
|
<p>
|
|
The parsing step is executed by a component called
|
|
<strong><code>taglet</code></strong>, while the generation is handled by a
|
|
component called <strong><code>doclet</code></strong>. This architecture is
|
|
shown below.
|
|
</p>
|
|
<p align="center">
|
|
<img src="architecture_h.png" alt="Architecture"/>
|
|
</p>
|
|
|
|
<h2><a name="taglet"></a>Taglet</h2>
|
|
<p>
|
|
LuaDoc does not impose a documentation format. It does relies on an internal
|
|
representation of the documentation. This representation is described in the
|
|
<a href="#documentation">Documentation</a> section. If the developer wants to
|
|
use a custom documentation format the <code>taglet</code> component can be
|
|
replaced.
|
|
</p>
|
|
<p>
|
|
Writing a new taglet is a matter a implementing a single method:
|
|
</p>
|
|
<pre class="example">
|
|
function start (files, doc)
|
|
</pre>
|
|
<dl>
|
|
<dt><strong>files</strong></dt>
|
|
<dd>a list of file (or directory) names.</dd>
|
|
|
|
<dt><strong>doc</strong></dt>
|
|
<dd>a preprocessed documentation object.</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
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 <a href="manual.html#howto">How To</a>. If an
|
|
item in the list is a directory it iterates recursively throw all files in the
|
|
directory looking for filenames with <code>.lua</code> or <code>.luadoc</code>
|
|
extensions.
|
|
</p>
|
|
|
|
<h2><a name="documentation">Documentation</a></h2>
|
|
<p>
|
|
Instead of defining a documentation format LuaDoc defines an internal
|
|
representation of a documentation object. Taglets and doclets must conform with
|
|
this format.
|
|
</p>
|
|
<p>
|
|
The documentation object is described below. Some description elements are explained
|
|
below:
|
|
</p>
|
|
<dl>
|
|
<dt>List</dt>
|
|
<dd>table indexed by number. Example: List<string>
|
|
{
|
|
[1] = "x",
|
|
[2] = "y",
|
|
[3] = "z",
|
|
}
|
|
</dd>
|
|
|
|
<dt>HashMap</dt>
|
|
<dd>table whose numerical indices are the key values for objects. Example: HashMap<string, string>
|
|
<pre class="example">{
|
|
[1] = "x",
|
|
[2] = "y";
|
|
[3] = "z";
|
|
["x"] = "x coord",
|
|
["y"] = "y coord",
|
|
["z"] = "z coord",
|
|
}</pre>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3>DOCUMENTATION</h3>
|
|
<pre class="example">
|
|
{
|
|
files = <i>HashMap<string, DOCUMENTATION_ELEMENT></i>, -- indexed by file name
|
|
modules = <i>HashMap<string, DOCUMENTATION_ELEMENT></i>, -- indexed by module name
|
|
}
|
|
</pre>
|
|
|
|
<h3>DOCUMENTATION_ELEMENT</h3>
|
|
<pre class="example">
|
|
{
|
|
type = ["file" | "module"],
|
|
name = <i><string></i>, -- full path of file or name of module
|
|
doc = <i>List<BLOCK></i>, -- all documentation blocks
|
|
functions = <i>HashMap<string, BLOCK></i>, -- only functions, indexed by function name
|
|
tables = <i>HashMap<string, BLOCK></i>, -- only table definitions, indexed by table name
|
|
},
|
|
}
|
|
</pre>
|
|
|
|
<h3>BLOCK</h3>
|
|
<pre class="example">
|
|
{
|
|
class = ["module" | "function" | "table"],
|
|
name = <i><string></i>,
|
|
summary = <i><string></i>,
|
|
description = <i><string></i>,
|
|
comment = <i>List<string></i>,
|
|
code = <i>List<string></i>,
|
|
param = <i>HashMap<string, string></i>,
|
|
},
|
|
</pre>
|
|
|
|
<h2><a name="doclet"></a>Doclet</h2>
|
|
<p>
|
|
The primary job of an <strong><code>doclet</code></strong> is to take a
|
|
<code>Documentation</code> object and generate some kind of output.
|
|
LuaDoc is bundled with an implementation that generates HTML files.
|
|
</p>
|
|
|
|
<p>
|
|
Writing a new <strong><code>doclet</code></strong> is a matter a
|
|
implementing a single method:
|
|
</p>
|
|
<pre class="example">
|
|
function start (doc)
|
|
</pre>
|
|
<dl>
|
|
<dt><strong>doc</strong></dt>
|
|
<dd>a documentation object.</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: architecture.html,v 1.5 2007/08/13 15:32:45 carregal Exp $</small></p>
|
|
</div> <!-- id="about" -->
|
|
|
|
</div> <!-- id="container" -->
|
|
</body>
|
|
</html>
|