Documenting Lua Code

lua-users home

Here's some notes on documenting Lua code:

Comments: Integration Module Documentation for Distributions

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

Something like that was in the Windows Help (chm) documentation on the, apparently abandoned, Lua All In One (AIO) Distribution: (screenshot) or (CHM download). It's not the best, but it's better than nothing, and it's a start.

RecentChanges · preferences
edit · history
Last edited October 24, 2020 6:29 pm GMT (diff)