As of two days ago the Gtk+ buildbot is finally running the test suite after every build. And today we even have the first regressions that we need to address/understand. The short-, mid- and long term goal is now to get as many tests running as possible and keep them running. There are quite some bugs to be fixed in WebKit/Gtk+, our base libraries, our testing tools so there is plenty of fun left for everyone.
In the webkit IRC channel we sometimes get questions regarding the API of the WebKit/Gtk+ port and if there are examples. On the one hand we are pretty strong. We have the GtkLauncher, some early adopters, when adding API many people made sure that we have API documentation. On the other hand we are weak as there is no introduction, no generated reference manual, no downloadable samples. So I got a bit sidetracked from the regression work and started to integrate gtk-doc and to cut a long story short: You can find an initial version here.
On to the gory details. Integrating gtk-doc requires recursive make due the way the gtk-doc.make rules are written. This file is copied in from gtkdocize. When dealing with documentation you can not have srcdir != builddir. The html result will be put in the source directory and if you try to squeeze in the @VERSION@ you will need srcdir == builddir. Starting from GtkDoc in live.gnome.org and Florian’s GPE guide one finds pretty much everything one needs to find. Some things needed some look at the tool sourcecode (perl, eeek!) but are clear now.
WEBKIT_API type
function_name (function*…);
To make gtkdoc-scan parse the above as a function you will need to pass –ignore-decorators=”WEBKIT_API” to the tool. Magically plenty of symbols turned up in the -unused.txt file and I was able to copy them into the -sections.txt. Now the tool refused to find any documentation. So remember WebKit/Gtk+ is mostly written in C++ and gtkdoc-mkdb simply does not know about the “.cpp” file extension. So pass –source-suffixes=c,cpp to gtkdoc-mkdb and it will find the sourcecode. Ah functions and their documentation, almost perfect. The last undocumented bit is for -sections.txt. E.g. you have the various _get_type(void) methods and there is little benefit of having them pop up in the API. Inside your “<SECTION>” you can put them into a “<SUBSECTION Private>” and they will be ignored.
The next thing is to get it actually merged into WebKit and integrate having uptodate API reference in the release process.
