Re: doxygen and lua modules

["Wesley Smith" <wesley.hoke@...>]

So far my best solution to this issue has been to define custom XML
tags with doxygen aliases and stuff in documentation of the Lua
interface.  I'm still working on this approach but it looks like it
will allow me to generate the C/C++ and Lua interfaces from doxygen
but still leaves the question of where the doc strings are going to
come from.

wes

On Dec 22, 2007 4:14 PM, David Manura <dm.lua@math2.org> wrote:
> 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.
>
>
>