Re: [ANN] LuaDoc 3.0 Released

["Frans Slothouber" <frans.slothouber@...>]

On 17/08/07, David Manura <dm.lua@math2.org> wrote:
> Tomas Guisasola Gorham writes:
> > LuaDoc is a documentation generator tool for Lua source code.
> > It parses the declarations and documentation comments in a set of Lua source
> > files and produces a set of XHTML pages describing the commented declarations
> > and functions....Feedback is welcome!
>
> Another useful property of a documentation tool is that it be language neutral,
> at least in a fallback case, so that a single tool can be used for a
> multilanguage project (e.g. Lua and C).  POD/POD6, ROBODoc, and Natural Docs, to
> name a few, have this property intentionally.
>
> That may prevent a deep integration between the documentation tool and a
> particular language, but it can be ameliorated with an extensible underlying
> data model (e.g. custom header types in ROBODoc, custom header names in POD,
> custom keywords in Natural Docs, or possibly the @class tag in LuaDoc) and
> configurable parser.  It may require additional programmer typing too, as some
> information is not inferred from the language,

Indeed.  It violates the don't repeat yourself principle.  Data get
duplicated an this
makes it hard to keep it consistent.

ROBODoc partly solves this by allowing the user to included parts of the
source code in the documentation.

For instance:

/****f* Parser/parse
 * PURPOSE
 *    This parses a single string of text and stores
 *    the result in a tree.
 * SYNOPSIS
 */
int parse( char* arg_text, Tree *arg_t )
/*
 *  INPUTS
 *     * arg_text -- a nul terminated string.
 *     * arg_t  - the parse tree
 *****
 */

Results in:

Parser/parse            [function]

PURPOSE
    This parses a single string of text and stores  the result in a tree.
SYNOPSIS
    int parse( char* arg_text, Tree *arg_t )
INPUTS
    -  arg_text -- a nul terminated string.
    -  arg_t  - the parse tree


But still a lot of information gets duplicated (ie: variable names,
function name).
This is in my experience the main source of documentation errors.

But it is hard to find a documentation format that avoids this and is
still readble in source format.

But having a documentation tool that is language neutral is very useful
especially since now-a-days many projects are written in mix of languages.
It also allows you to document things like testcases, makefiles, and other
entities.

> Interestingly, I see the ROBODoc roadmap (
> http://www.xs4all.nl/~rfsber/Robo/roadmap.html ) mentions "Rewrite of ROBODoc in
> Lua".  That would seem to be a much more reasonable fit than doing text
> processing in C.

Most definitely.  Another reason is the lpeg module, that is such an
elagant solution to creating parsers.

But the main reason is size.

When ROBODoc was started in 1994 on the Amiga there were basically
two language choices:  C or Assembler.  So the first version was written in C.
In the following years when it moved from the Amiga to other platforms too

I thought many times of rewriting it in another language, (in particular Perl).

However it is my experience that not many people are willing to install both
a program and the language that is required to run it.  Especially if
it requires
a big install.  Nowadays Perl/Java/Python are big installs.

Lua is so small than you can create a single executable that contains both
the lua interpreter and all the sources for ROBODoc.  So users won't even
know they are using Lua.


And Lua is very elegant in general!

Have fun,
Frans.