Re: doxygen and lua modules

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

Wesley Smith writes:
> I'm currently exploring the idea of generating documentation for the
> Lua interface of a Lua module with doxygen.

There have been some related discussions on this:
http://lua-users.org/lists/lua-l/2007-08/msg00276.html

> How have people gone about documenting Lua interfaces to
> their modules that are defined in C/C++ in the past?

My modules defined with C/C++ are typically part C/C++ and part Lua.  The entire
external interface to a module is described in POD format at the end of the Lua
file.  Internal documentation uses in-line source comments.  This I've taken
from Perl.

A feature of POD (or similar language neutral format such as HTML as used for
the Lua Reference Manual and Kepler modules) is that it is completely
self-contained: there is no need to analyze the source code to interpret or
render it.  The structural representation of a function definition in source
code is irrelevant.  This is important since, unlike in more static languages
like C++/Java/C# where the form of class and method definitions is fairly
uniform, the structural definition of a Lua function can be varied: not only
represented in Lua or C-compatible language but also constructed at run-time
using various types of Lua metaprogramming with metatables and custom OO
libraries.  For example, in C, a datatype used by a function is often written
more explicitly in source code:

  struct Box { double width; double height; double length; };

whereas in Lua, a function might return a value constructed without a formal
data type (but conceptually it is a datatype):

  local fields = {'width', 'height', 'length'}
  local box = {}
  for i=1,3 do box[fields[i]] = select(i, ...) end

If you must, you could create dummy Lua modules/functions so that the
documentation generator is happy:

  --# [add some external API description here]
  function hello(name) end  -- make documentation generator happy
  hello = _hello  -- replace with version implemented in C

Still, "function hello(name)" carries little usable information besides names of
function and arguments.

> In addition, I'd also like to generate some source files that will add
> in-application help strings to the module table....perhaps there is
> some kind of agreed upon field to put this in and format for the help
> strings.

There's some pages the wiki and this list concerning Python-like "docstrings" (
search: http://lua-users.org/ ).  I'm not aware of an agreed upon format.