Re: gtk-doc versus doxygen

[Malcolm Tredinnick <malcolm commsecure com au>]

On Sat, Oct 05, 2002 at 09:59:37AM -0500, Jacob Perkins wrote:
> Are there any gnome policies against using doxygen for documenting
> code?  gtk-doc does not seem to have many features, and I can't find

File bug reports about the features you want, or send mail to the
gtk-doc list to spark some discussion. However, as mentioned below, I
think you are wanting something from gtk-doc that it is not designed
for.

> much documentation on the features it does offer.

True, the gtk-doc documentation is a bit lacking, but the gtk-doc list
is pretty helpful (particularly search the archives, since a lot of
questions will have already been answered).

> doxygen, though, has some great features, such as linking to the code,
> showing which functions are referenced by others and what each
> function references.

Hmmm ... looks like you are wanting to provide different documentation
from what gtk-doc is designed for.

The gtk-doc tool is for providing user documentation of the public API.
You are wanting to use the features of doxygen that document the
internal implementation of your package -- i.e. something for developers
working on your package, not for the end users. These are different
purposes.

The public API should not need to refer to the actual implementation or
care about functions that reference this function, etc.

I should also point out that, in general, code marked up for doxygen
parsing is _very_ ugly to read outside of the doxygen markup. It has
random short comments (things like /* out@*/) scattered all over the
ship and you really have to concentrate when reading the code. This is
not a problem with gtk-doc markup -- and that is not a consequence of
the different goals, it's a consequence of the different markup methods.

> So, if I'm hoping to have my project included in gnome cvs, or the gnome
> desktop, do I need to use gtk-doc?

Yes, you should. It would not be very good to suddenly introduce a
dependency on doxygen into the GNOME build hierarchy.

Malcolm