[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Documenting a C++ implemented Lua API with Doxygen - a solution
- From: Carsten Fuchs <CarstenFuchs@...>
- Date: Wed, 16 Mar 2011 10:56:15 +0100
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
The source files used to generate it are at
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
Cafu - the open-source Game and Graphics Engine
for multiplayer, cross-platform, real-time 3D Action
Learn more at http://www.cafu.de
Description: S/MIME Cryptographic Signature