Tuesday, February 1, 2011

Generating API docs from .gir files

From time to time people ask which are the plans about generating API documentation from the introspected information in the .gir files that g-ir-scanner outputs.

More often, I hear someone swearing about how hard is to setup gtk-doc to correctly generate documentation for your code. And getting g-ir-scanner to generate .gir files as expected is not completely trivial either.

It should be apparent that generating the docs from the .gir would save quite a bit of grief altogether but for one reason or another this hasn't happened yet. Docstrings are in the .gir files already along with the rest of the metadata but gtk-doc is still scanning the C sources.

© Juan José Sánchez Penas
During last GUADEC, the gobject-introspection people could be seen hacking in the lobby instead of attending your talk or rioting against the release team, and one of the outcomes was Zach Goldberg's g-ir-docgen script. His new employer forbids doesn't sponsor him for this work so this has been in the freezer since then.

So we can eventually get out from this situation, I would like to encourage interested non-coding people to add to CC on this bug: https://bugzilla.gnome.org/show_bug.cgi?id=625494

And to those that can actually code, please consider using that ticket to coordinate the effort, it may take less work than you think and it can be a fun hack. Think of all the GNOME hackers that will thank you!