[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Lua at ONLamp - POD for documenting Lua modules
- From: "Adriano Ferreira" <a.r.ferreira@...>
- Date: Thu, 19 Jul 2007 07:28:44 -0300
On 7/19/07, David Manura <email@example.com> wrote:
Adriano Ferreira <a.r.ferreira <at> gmail.com> 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 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.
Thanks for your reply and throrough discussion, David. You summarised
very important points on the issue of documenting Lua code (that I
would not be able to).
Maybe the current limitations of POD could be overcome by adopting the
newly created POD 6 (http://search.cpan.org/dist/Perl6-Perldoc/) which
is going to supersede POD in Perl 6 -- it approaches the points you
mentioned like shorter syntax for some constructions and
extensibility. I will give it a try and, if promising, will take
something to the appreciation of the list subscribers.
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,
Not really a strict language specification, but perlpodspec
(http://perldoc.perl.org/perlpodspec.html) gets close to it.
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.