Re: [ANN] LuaDoc 3.0 Released

[David Manura <dm.lua@...>]

Tomas Guisasola Gorham <tomas <at> tecgraf.puc-rio.br> writes:
> LuaDoc is a documentation generator tool for Lua source code.
> ... 
> Feedback is welcome!

I've been looking a lot at possible doc solutions for Lua: POD, POD6 (Perl),
Natural Docs, reStructuredText (Python), rdoc (Ruby), ROBODoc, plain HTML, etc.

There seem to be two recurring approaches.

One is the "class browser" output, which Javadoc, Luadoc, and Doxygen follow. 
It focuses on indexing the classes, methods, and signatures, with additional
documentation inside that structure (sort of a reversed form of literate
programming).

The second approach is where the documentation is written more in prose and also
describes higher level concepts that aren't necessarily visible or identical to
the code (i.e. beyond the classes and functions).  A good example of that is
Roberto's Lpeg documentation:

  http://www.inf.puc-rio.br/~roberto/lpeg.html

I lean toward the latter having more added value, but the two approaches are not
mutually exclusive.  For example, function signatures must be explicitly
specified in both cases, and being able to cross reference (e.g. @see) between
functions in different modules in a consistent way remains useful.  However, in
a dynamic language like Lua, the form of a signature often does not fit into a
rigid structure (like @param and @return in Javadoc), though it can often be
expressed clearly in some declarative form chosen by the author for a particular
module, such as like this (simplified for demonstration):

==============

Function: integrate

  f = integrate(t)

Numerically integrates a function.

<t> is a table having these fields:

  * <func> - function to integrate.  Type is function or callable object of the
form <function(x)> returning <y> over the reals.

  * <min> - minimum bounds.  Type integer, "+INF"/"-INF", or <nil>.  Defaults to
"-INF".

  * <max> - maximum bounds.  Type integer, "+INF"/"-INF", or <nil>.  Defaults to
"+INF".

Returns another function <f> (a wrapped coroutine) of the form

  result, is_complete = f()

where

  * <result> is the current result of the integration, of type number.

  * <is_complete> is a Boolean indicating whether the integration is complete. 
<f> should be called repeatedly until <is_complete> is <true>.

==============