lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


You do not need any comment in a header file for Doxygen to parse it:

=====
class Foo {
public:
  Foo();

  void bar(int x);
};
=====

is a perfectly valid header and will generate documentation for the
constructor and bar method.

Not very hard to maintain from my point of view....

Gaspard

On Sat, Dec 18, 2010 at 10:38 PM, David Wolfe <evadeflow@gmail.com> wrote:
>>> I have read that GCC is able to output XML out of C[++] code too.
>>> Out of curiosity, why having chosen Doxygen instead of that? Simpler
>>> to parse?
>
>> I think you are referring to gcc-xml [1]. A similar approach is used
>> in Lqt bindings with the custom-written cpptoxml [2] parser.
>
>> IMO the Doxygen output is better suited for binding - undocumented
>> functions will simply not be bound. However, gccxml and cpptoxml will
>> pick up every method it finds in header files :)
>
> gcc-xml seems like the obvious choice to me. Doxygen comments have to be
> added to headers manually, which is a PITA.  And they're a maintainance
> burden just like regular comments.  How many times have we all seen
> something like this:
>
>    // Bump gain by a factor of 1.5 to compensate for AD65Q freq
>    gain_ *= 1.78;
>
> Any system that relies on comments being up-to-date seems dubious.
> gcc-xml works on the raw C++ headers, so the output XML is automatically
> up-to-date w.r.t. the source, and there's no opportunity to introduce
> errors.
>
> The Python-Ogre project (http://www.pythonogre.com/) uses the python
> bindings for gcc-xml (pygccxml) to programmatically generate C++ binding
> code that, ironically enough, targets Boost-Python. It may seem odd to
> use a code generator to write code for a tool whose chief claim to fame
> is that it doesn't require a separate code generation step, but it's a
> very pragmatic solution in practice that eliminates a lot of
> duplication.  (I've often wished a similar tool existed for luabind.)
>
> You can say things to the py++ code generator like: "Give me a reference
> to all classes in the namespace 'util' whose name matches the pattern
> 'Vec*'. Okay, for all those classes, emit the following binding code."
> So you generate the bindings for Vec2f, Vec2d, Vec3f, Vec3d, Vec4f,
> Vec4d, etc with a single block of python script, instead of writing the
> bindings in C++ by hand and cutting/pasting for all the different
> variants.
>
> Of course, you wouldn't need to target Boost-Python on the back-end.
> Using pygccxml by itself, you can emit whatever binding code you want.
> If a lua port of pygccxml existed, you could even do it all in Lua.
> That, to me, would be the 'holy grail'...
>
>
>