Someone please fix gtk-doc

Python:
There should be one – and preferably only one – obvious way to do it.

Perl:
There’s More Than One Way To Do It

gtk-doc:
There’s More Than One Way To Do It Wrong

Ok, the last one isn’t an actual motto, just how I feel about gtk-doc after having to figure out how to get our additions to gtk+ properly show up in the generated documentation. Extra points if you can guess the language gtk-doc is programmed in.

Here are some of very simple steps to ensure your correctly formulated gtk-doc comments in the code never make their way into the generated HTML documentation:

1. Do not add your_gobject_derivative_get_type() in the ${your-module}.types file
2. Do add your_enum_get_type() in the same file
3. Do not add YourWidget in the ${your-module}-sections.txt file (right below the <TITLE>YourWidget</TITLE> that probably already exists)
4. Do not add every single your_widget_function() in the ${your-module}-sections.txt file
5. Do not include <index> and <index role=”…”> in ${your-module}-docs.sgml (for all combinations of deprecated and Since: tags repeated for role)
6. Do not add <xi:include href=”xml/your-widget.xml”/> in ${your-module}-docs.sgml

While I do like the output gtk-doc generates there’s just so much manual work required to maintain it properly it’s a real pain in the behind. Have I mentioned it takes closer to three hours to build the documentation for our modified gtk+?