lua-users home
lua-l archive

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


On 7/19/07, David Manura <dm.lua@math2.org> wrote:
Adriano Ferreira <a.r.ferreira <at> gmail.com> writes:
> I just mentioned Lua at a blog entry at O'Reilly ONLamp site:
>
http://www.oreillynet.com/onlamp/blog/2007/07/all_together_now_lua_pod_lpeg.html

I saw LuaPOD recently too, which was something I was considering writing
myself
for rendering POD-based Lua module docs in
http://lua-users.org/wiki/LuaSearch .
 Unfortunately, the suggestion of standardizing Lua module docs in terms of
POD
hadn't since caught on much like it has with Perl.  Still, I believe Lua
modules
are really in need of some suitable documentation standard practice,
possibly in
conjunction with LuaRocks, so that documentation for multiple independent
Lua
modules can be combined and cross-referenced, such as for Lua distributions,
i.e. letting *documentation be modular*.  This should be an obvious
progression.
 POD offers this.  Javadoc offers this.  UNIX manpages offer this.  HTML and
the
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
more
obvious, the syntax for lists shorter, and the syntax more extensible.
Still,
it works well in practice for 95%-99% of things.  It is also not (like
Doxygen)
dependent upon any particular language because the documentation is
independent
from the code structure.  I think that is very important for a dynamic
scripting
language, especially one that is metaprogrammed, in which static code
structure
tells you fairly little beyond the obvious.  Still, something compatible
with
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
but
(like Perl5) it's not defined according a strict language specification,
thereby
limiting the use and development of third-party tools to process it in new
ways.
 Perhaps Lua documentation could be written in Lua.  Lua may be good for
data
definition, but it is not a markup language.  There's also the desire to
avoid
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
a
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 (
http://luadoc.luaforge.net ) :
http://luarocks.luaforge.net/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