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