lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

On 7/19/07, David Manura <> wrote:
Adriano Ferreira <a.r.ferreira <at>> writes:
> I just mentioned Lua at a blog entry at O'Reilly ONLamp site:

I saw LuaPOD recently too, which was something I was considering writing
for rendering POD-based Lua module docs in .
 Unfortunately, the suggestion of standardizing Lua module docs in terms of
hadn't since caught on much like it has with Perl.  Still, I believe Lua
are really in need of some suitable documentation standard practice,
possibly in
conjunction with LuaRocks, so that documentation for multiple independent
modules can be combined and cross-referenced, such as for Lua distributions,
i.e. letting *documentation be modular*.  This should be an obvious
 POD offers this.  Javadoc offers this.  UNIX manpages offer this.  HTML and
assortment of current Lua documentation practices do not offer it.

I can't say I like all things about POD syntax.  Maybe the rules could be
obvious, the syntax for lists shorter, and the syntax more extensible.
it works well in practice for 95%-99% of things.  It is also not (like
dependent upon any particular language because the documentation is
from the code structure.  I think that is very important for a dynamic
language, especially one that is metaprogrammed, in which static code
tells you fairly little beyond the obvious.  Still, something compatible
the *runtime* docstring concept would also be advantageous.  I've looked at
Natural Docs as a POD alternative; the syntax is natural and output great
(like Perl5) it's not defined according a strict language specification,
limiting the use and development of third-party tools to process it in new
 Perhaps Lua documentation could be written in Lua.  Lua may be good for
definition, but it is not a markup language.  There's also the desire to
reinventing yet another documentation syntax and building a completely new
toolchain to process it, but if it is needed then the ability to convert to
more common intermediate format (e.g. POD, Javadoc, DocBook, etc.) for
subsequent processing (e.g. PDF/HTML/WinHelp rendering) is useful.

For the implementation of LuaRocks itself, I've been using LuaDoc ( ) :

The format is basically like JavaDoc (which meant an easy learning
curve for me) and the output is nice. The tool itself has some minor
issues; it is not very robust on error situations, and does not really
parse Lua (which means it misses some constructs), but worked as
expected for the vast majority of my code and it wasn't hard tweaking
it (LuaDoc or the code) to make it happy with the rest.

The argument about static interfaces and dynamic languages has merit,
but when discussing public APIs, I believe static interfaces are the
major focal point. Apart from implementation issues, I think LuaDoc as
a format is a strong contender for documenting Lua modules. The free
form of Perl's documentation may be flexible, but makes it hard to
find things. In the Perl embedding API, for example, some important
functions are mentioned only in passing, as parts of the docs are
written 'in prose' instead of function-by-function descriptions (which
would make omissions more obvious).

-- Hisham