Documenting a C++ implemented Lua API with Doxygen - a solution

[Carsten Fuchs <CarstenFuchs@...>]

Dear Lua folks,

we've long been looking for a solution for documenting our C++ implemented Lua API (the 
Lua-based scripting API of our game engine Cafu, http://www.cafu.de), preferably using Doxygen, 
and now that we've found it, we would like to share it:

The resulting Doxygen documentation is at
http://api.cafu.de/scripting/

The source files used to generate it are at
http://trac.cafu.de/browser/cafu/trunk/Doxygen/scripting

The obvious key idea was to write "fake" C++ that mirrors the Lua API as input files for Doxygen.

However, we didn't write the "fake" C++ from scratch by hand, but instead the process was much 
facilitated by generating the skeleton of it automatically (then completing the rest by hand).

This was possible because we augmented our C++ class hierarchies that we bind to Lua (using no 
particular framework other than the PiL2 book), with a custom type system, that allows us to 
iterate over the class inheritance tree, and for each class, we iterate over the list of methods 
bound to Lua.
This information is sufficient to generate the above mentioned "fake" C++ input for Doxygen.

The process can be repeated at any later point in time into a new set of files, which can then 
be compared (e.g. using a graphical diff tool) to the previously generated and possibly 
hand-edited files in order to sync new/updated/deleted classes and methods.

The only significant remaining problem is that C++ uses :: as the scope resolution operator and 
. or -> for member access, where Lua uses t[key], t.xy, or t:method(). As a result, the Doxygen 
documentation uses :: when it should use . or a single :
(Doxygen has option OPTIMIZE_OUTPUT_JAVA, which is helpful, but then the output is . everywhere, 
even when it should be :, and so we decided to not use it.)

In summary, a series of small and simple steps has turned out to provide a solution that works 
very well for us and that I've found nowhere else, so I hope it might be useful to others in the 
future.

Best regards,
Carsten



--
   Cafu - the open-source Game and Graphics Engine
for multiplayer, cross-platform, real-time 3D Action
          Learn more at http://www.cafu.de

Attachment: smime.p7s
Description: S/MIME Cryptographic Signature