Documenting Lua Code
 |
||
|
Documenting Lua Code |
|
On providing providing integrated documentation for many modules,
for inclusion in LuaDistributions, here's my overview of the situation... README's
hidden in tarballs (example [10]) are not especially effective. The
Kepler effort resulted in the prevalence of what might be called this
"doc.css" HTML format (example [4]). Overall it isn't bad. It's a
somewhat loose (unrestrictive) format that often effectively covers
both qualitative and reference API sections, reminiscent of the
character of Perl POD (except that it would be better if more Lua
modules started with a SYNOPSIS section as prevalent in POD). It's
important to note that the Lua Reference manual also kind-of follows
this loose format. Then came the more structured
class-browser/JavaDoc like LuaDoc (example [5]), though I think this
"fill in the blank" style for function parameter documentation
(@param) doesn't always encourage clear documentation. The Lua
Reference Manual doesn't take this approach, and I don't see people
complaining. One advantage of the more structured format though is
that it allows systematic inter-linking between the API of
independently developed modules, even if those documents are moved or
translated into different formats; however, even the more loosely
structured POD offers the basics of that. Years ago, I proposed that
Lua standardize on POD [6], which, although a bit quirky, works in
Perl and will work in Lua, but it didn't catch on. More recently,
there's the Python inspired reStructuredText/Sphinx (example [7]),
which goes a little beyond POD and offers targeting multiple output
formats (DHTML, PDF, HTML Help .chm, etc.). Sphinx is proven and well
supported system (like cmake) though a bit heavy for some tastes and
likewise might not catch on in the Lua community (if anything would).
Markdown is popular, especially for the lightweight README files that
github encourages, and github is becoming very popular in the Lua
community, but markdown is is a little too lightweight for things like
interlinking APIs. --DavidManura
In the end I think people often like to follow examples. Like Kepler
followed the loose doc format of the Reference Manual, and ended up
setting a trend with doc.css which a number of non-Kepler projects
followed (even Roberto's lpeg). IIRC the Xavante installation from the
Kepler all-in-one package used to generate an index.html page linking
to each subproject's index. Short from reformatting/rewriting
documentation, which no one will do, I think adding support for
rendering to HTML a few popular formats (LuaDoc, Markdown) and
generating a main index.html page for all installed projects is about
as far as we can go. Some projects will integrate more nicely than
others, and hopefully that will set an example. --HishamMuhammad
