Midgard2 and Gtkdoc

One day I realized that for last few months, I managed to fix (few times) some documentation part for Midgard core and PHP bindings. Those fixes almost always included properties of some class. And recently I started to wonder how to write documentation for events in midgard, once. Well, not about the idea, but at least I wanted to avoid writing ( few times in few different places ) what events some class provieds.

Since Midgard 1.8 we used doxygen, which is very good, with cool features for writing docs, but for me ( and writing GObject based code and docs ) is not perfect enough. Mainly you can not document class inheritance, object properties or class signals. And what is more important, you can not do this automagically.

I decided to test gtkdoc ( which is also far from being perfect and seems to be missing doxygen :), and got quite nice documentation part for a start.

• List of MgdSchema object events
• midgard_config properties

Those are created automagically, so I do not have to document them. PHP or Python developer might always want to look for additional information in core documentation, without need to duplicate many informations in many places and without risk that those docs are getting out of date quickly.

Bad thing about gtkdoc and doxygen is the fact that docs should be located in c files ( instead of headers ) and must be reformatted a bit. But once they are written, one is able to use even devhelp to read them.