Bug 10890

Summary:	Confusing documentation configuration in dbus-glib
Product:	dbus	Reporter:	Bernard Leak <bernard>
Component:	GLib	Assignee:	Simon McVittie <smcv>
Status:	RESOLVED FIXED	QA Contact:	John (J5) Palmieri <johnp>
Severity:	trivial
Priority:	low	CC:	cosimo.alfarano, robin.bateboerop, rob.taylor, ross, smcv, will
Version:	unspecified	Keywords:	patch
Hardware:	All
OS:	Linux (All)
URL:	http://cgit.freedesktop.org/~smcv/dbus-glib/log/?h=undoxygenate-10890
Whiteboard:	review?
i915 platform:		i915 features:
Bug Depends on:
Bug Blocks:	37793
Attachments:	Maemo's patch to install the doxygen docs, FYI only [PATCH 1/3] Remove Doxygen droppings from source code [PATCH 2/3] Use single star in doc-comments not intended for gtk-doc [PATCH 3/3] Remove all support for Doxygen

Description Bernard Leak 2007-05-08 16:42:20 UTC

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.

Comment 1 Ross Burton 2007-06-22 07:14:41 UTC

This is legacy from when dbus-glib was part of the dbus module.

Comment 2 Simon McVittie 2011-01-10 06:47:21 UTC

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?

Comment 3 Simon McVittie 2011-03-29 08:56:46 UTC

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).

Comment 4 Simon McVittie 2011-05-31 07:32:50 UTC

I've redone the branch to be independent of other changes, and have few enough patches to attach here.

Comment 5 Simon McVittie 2011-05-31 07:33:13 UTC

Created attachment 47374 [details] [review]
[PATCH 1/3] Remove Doxygen droppings from source code

Comment 6 Simon McVittie 2011-05-31 07:33:32 UTC

Created attachment 47375 [details] [review]
[PATCH 2/3] Use single star in doc-comments not intended for gtk-doc

Comment 7 Simon McVittie 2011-05-31 07:33:44 UTC

Created attachment 47376 [details] [review]
[PATCH 3/3] Remove all support for Doxygen

Comment 8 Will Thompson 2011-06-01 09:19:30 UTC

Review of attachment 47374 [details] [review]:

++

Comment 9 Will Thompson 2011-06-01 09:22:11 UTC

Review of attachment 47375 [details] [review]:

++

Comment 10 Will Thompson 2011-06-01 09:23:19 UTC

Review of attachment 47376 [details] [review]:

++

Comment 11 Simon McVittie 2011-06-01 09:36:24 UTC

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.