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

[Carsten Fuchs <CarstenFuchs@...>]

Hi Eric,

Am 20:59, schrieb Eric Wing:
> Thanks for sharing. This is something I am very interested in for my
> own projects. Did you have to modify Doxygen or does all your stuff
> work with stock?

No modifications, it's stock Doxygen.
We considered doing that, but as one of the details that we wanted to achieve was keeping the 
familiarization, usage and upgrading of Doxygen straightforward also for others, we just used to 
Doxyfile configuration to get as close as possible to the desired result. (As mentioned in my 
previous post, :: vs. : vs. . is one issue where modifying Doxygen might be worthwhile though.)

> Do you have code/examples on how you generate your
> Cpp-like files?

Yes:

The type info system for managing the class hierarchies is at
http://trac.cafu.de/browser/cafu/trunk/Libs/TypeSys.hpp
http://trac.cafu.de/browser/cafu/trunk/Libs/TypeSys.cpp

An example for how the type system is applied/used together with regular classes is at:
http://trac.cafu.de/browser/cafu/trunk/Libs/GuiSys/Window.hpp (see lines 243 to 246)
http://trac.cafu.de/browser/cafu/trunk/Libs/GuiSys/Window.cpp (see lines 74 to 97)

Code that uses all that to create the "fake" C++ code that I mentioned is at
http://trac.cafu.de/browser/cafu/trunk/Libs/TypeSys.cpp#L292
http://trac.cafu.de/browser/cafu/trunk/Games/DeathMatch/Code/ScriptState.cpp#L62

where the latter is a specialization of first and exists only because in this specific place we 
have additional information handy that we use for augmenting the generated documentation.

The obvious downside of this approach is that the same solution is unfortunately not easy to 
apply generally for everyone else, because it is based very much about the "TypeSys" that in 
turn others possibly cannot or don't want to use. However, I guess that a conceptually similar 
approach is possible with other Lua bindings / type systems, too.

> [...] I've been thinking along the lines of
> modifying Doxygen to understand new tags that I would use to declare a
> script API exposed from C/C++/etc.

Yes, I've been thinking about that, too, that is, adding some form of Doxygen documentation 
directly in the C++ code, e.g. documenting (Lua) method WindowT:AddChild() directly at it's C++ 
implementation at http://trac.cafu.de/browser/cafu/trunk/Libs/GuiSys/Window.cpp#L904

This has long been my favorite and investigated approach, but we eventually dropped it because 
it mixes the regular C++ API documentation with the Lua API documentation.

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