gtk-doc problems

My first reaction was that gtk-doc really sucks. For example, it requires you to write docstrings like this:

/** * my_function_name: * * Do stuff. **/ void my_function_name (GtkWidget *widget) { }

You have to repeat my_function_name in the comment even though it should be extremely simple for the documentation generator to find out the name of the function the docstring is documenting.

There is apparently no way to group multiple source code definitions to one docstring. You can't write something like this and expect it to work:

/** * Defines the minimum and maximum allowed lengths of the name. **/ #define NAME_MIN_LENGTH 10 #define NAME_MAX_LENGTH 20

And despite writing docstrings using the weird format that gtk-doc imposes, you will still have to write separate API documentation using SGML. Yay! For each c-file gtk-doc documents, it generates a file called /tmpl/someclass.sgml which contains place holders for each symbol. Here is an except of one such file:

<!-- ##### SECTION Title ##### --> GtkImageNav <!-- ##### SECTION Short_Description ##### --> Popup window showing a thumbnailed overview of a #GtkImageView <!-- ##### SECTION Long_Description ##### --> <para> GtkImageNav is a popup window that shows a downscaled preview of the pixbuf that #GtkImageView is showing. The user can drag around an rectangle which indicates the current view of the image. </para> ...

Because gtk-doc likes to write to this file, you will have a hard time keeping it version controlled and you will have to periodically merge it with the real source code. gtk-doc therefore negates the main advantage of using a documentation generator tool which is to keep the documentation close to the source code.

I am sorry for all the complaining. gtk-doc is a decent tool and using it is better than writing all documentation is Latex, for example. But gtk-doc is not the only API documentation tool available. There is doxygen, JavaDoc, Epydoc and a whole host of other documentation generators. gtk-doc just manages to be worse then all of them.