If I enable gtk-doc, then the necessary magic happens, and 'build' does the right thing automagically. If I want the Doxygen docs, I know to use the top-level Doxyfile. Is there anything at all for building the XML docs with xmlto? The version discovered by 'configure' is substituted all over the place, and various associated macros are defined accordingly in the Makefiles, but where is it *used*? Much the same, indeed, applies to 'Doxygen'. At the very least, the options to 'configure' should be brought into line with reality, and the deep secrets of how to actually GET the documentation should be revealed. Maybe the necessary documentation magically appears when one already knows how to get it? Of course, if xmlto is to be used, one would expect some configuration options for choosing the stylesheets, and so on. There's not much sign of that.
This is legacy from when dbus-glib was part of the dbus module.
Created attachment 41840 [details] [review] Maemo's patch to install the doxygen docs, FYI only (I attach this patch for information only: I don't recommend applying it.) We should make our minds up whether dbus-glib is documented with Doxygen or gtk-doc; this is important because it affects the markup we should be writing in the source code. At the moment, if you have (and enable) both, the gtk-doc version is installed automatically. The Maemo packaging has this patch to install the Doxygen-generated docs too, but as you can see at http://maemo.org/api_refs/5.0/5.0-final/dbus-glib_2/ they look pretty horrible, and I think they should be killed off. I think dbus-glib is documented in gtk-doc, and that the Doxygen setup is a relic of libdbus which should be discarded; if there's anything that is public API and is only documented via Doxygen, we should make it appear in gtk-doc rather than keeping Doxygen support. Does anyone disagree?
Here's a branch to clean up the build system, discard Doxygen support and fix various gtk-doc nits. I'm not going to attach the patches here, because there are quite a lot; see gitweb (in the URL field).
I've redone the branch to be independent of other changes, and have few enough patches to attach here.
Created attachment 47374 [details] [review] [PATCH 1/3] Remove Doxygen droppings from source code
Created attachment 47375 [details] [review] [PATCH 2/3] Use single star in doc-comments not intended for gtk-doc
Created attachment 47376 [details] [review] [PATCH 3/3] Remove all support for Doxygen
Review of attachment 47374 [details] [review]: ++
Review of attachment 47375 [details] [review]: ++
Review of attachment 47376 [details] [review]: ++
Fixed in git, 0.94
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.