Re: Lua at ONLamp - POD for documenting Lua modules

[hisham.hm@...]

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