Once upon a time, there was gtk-doc. It was weird and strange, and overall, different from other standards like javadoc or doxygen. But we gnomish people, were tied to it, as it was the only one working correctly with GtkObject/GObject. It’s still this way, as I don’t know any good solution with Doxygen or other tool to fill the space of gtk-doc.
Why it was weird? For me, the worst point was the need to maintain a set of files called templates. They were docbook templates that covered some documentation that you couldn’t add to your source code. These files were processed by some scripts that didn’t work very well with version control systems.
With gtk-doc 1.5 we can avoid the templates, at least for most of the use cases they were required. Now you can add to the source code a commentary like this one:
/** * SECTION:myclassname * @short_description: This is my short description for #MyClassName * @see_also: #Other, #AnyOtherOne * * It's a long description about this and that, and other things. You can write * about many things and enter sgml tags like: * <itemizedlist><listitem>an itemized list</listitem><itemizedlist> */
With this structure you remove at last the templates requirement. One additional note. As there was a bug in gtk-doc 1.5, the general makefile scripts provided don’t work with no templates. You have to add a rule to the documentation Makefile.am like this:
tmpl/*.sgml: scan-build.stamp
Another interesting point is using gtk-doc.make. It’s a script provided by the gtk-doc distribution providing general structure for gtk-doc processing. You can use it adding this line to the Makefile.am:
include $(top_srcdir)/gtk-doc.make