<hisham.hm <at> gmail.com> writes:
> For the implementation of LuaRocks itself, I've been using LuaDoc...
> 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).
I think a distinction needs to be made between two or three types of module
documentation. One is the (typically static) API--e.g. the function signatures
and their meaning. The second is a more conceptual description of the module in
context--it's purpose, examples, and the logical concepts the module deals with
(e.g. a module that provides an API for regular expression matching may also
describe conceptually what is a regular expression, as well as its syntax and
common usages). Third, there are the more administrative items such as credits,
license, contacting the author, limitations/known bugs, dependencies, project
URL, compatibility, etc.
A typical POD contains all three types of documentation, typically placed under
various boilerplate headings, and so is comprehensive. For those unfamiliar, a
few reasonably good PODs by Conway and Stein are below:
http://search.cpan.org/~dconway/Class-Std/lib/Class/Std.pm
http://search.cpan.org/~lds/CGI.pm/CGI/Cookie.pm
http://search.cpan.org/~lds/GD/GD.pm
http://search.cpan.org/~lds/Crypt-CBC/CBC.pm
This is not inherent in POD though. I've noticed the somewhat common "Kepler"
HTML style of docs follows basically the same three-pronged approach:
http://www.keplerproject.org/copas/
but the limitations here are in its original representation as HTML. It's
fairly presentational: it's split into multiple pages and has this side-bar on
each page. It's not as if this documentation is intended for process by
external tools (e.g. documentation checkers, formatters, and translators), nor
is there a mechanism for cross referencing between modules that is not dependent
upon HTTP, nor is there any mechanism for encouraging module authors to use a
consistent format. These are things addressed by, for example, POD and a few
others.
The .rockspec files do contain some of the third type of documentation, though
you would also want this displayed in the formatted (e.g. HTML) documentation
browsed by the user.
My concern about LuaDoc (and to some extent ROBODoc) is that it is only
encouraging the first of the three types of documentation, as if to suggest that
one only needs to insert the LuaDoc and the module is documented. If you see on
the web some of Doxygen generated output that barely documents the API and
doesn't describe anything in context, it's obvious that this type of
documentation has limited use in understanding. Maybe LuaDoc could be used for
the other two types of documentation, but I don't see much framework to
encourage it, and even LuaRocks is using a separate manual.html file. There are
also reasons to avoid interweaving such docs with the source too much (even
though keeping them together is often encouraged), such as if it will be
translated into different languages, an excellent example being the Lua
Reference Manual, which is not inline to the Lua source, nor does it following
anything like the LuaDoc style (though it does translate well into POD). In
fact, Lua modules are often implemented in C not Lua.
I see Ruby is using a wiki-like syntax called RDoc --
http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html . Incidentally,
having the Lua wiki and Lua modules use the same syntax would be convenient.
