Re: Lua at ONLamp - POD for documenting Lua modules

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

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.