My first reaction was that gtk-doc really sucks. For example, it requires you to write docstrings like this:
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:
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:
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.