Bug 10890 - Confusing documentation configuration in dbus-glib
Summary: Confusing documentation configuration in dbus-glib
Status: RESOLVED FIXED
Alias: None
Product: dbus
Classification: Unclassified
Component: GLib (show other bugs)
Version: unspecified
Hardware: All Linux (All)
: low trivial
Assignee: Simon McVittie
QA Contact: John (J5) Palmieri
URL: http://cgit.freedesktop.org/~smcv/dbu...
Whiteboard: review?
Keywords: patch
Depends on:
Blocks: 37793
  Show dependency treegraph
 
Reported: 2007-05-08 16:42 UTC by Bernard Leak
Modified: 2011-06-01 09:36 UTC (History)
6 users (show)

See Also:
i915 platform:
i915 features:


Attachments
Maemo's patch to install the doxygen docs, FYI only (585 bytes, patch)
2011-01-10 06:47 UTC, Simon McVittie
Details | Splinter Review
[PATCH 1/3] Remove Doxygen droppings from source code (7.88 KB, patch)
2011-05-31 07:33 UTC, Simon McVittie
Details | Splinter Review
[PATCH 2/3] Use single star in doc-comments not intended for gtk-doc (1.97 KB, patch)
2011-05-31 07:33 UTC, Simon McVittie
Details | Splinter Review
[PATCH 3/3] Remove all support for Doxygen (11.88 KB, patch)
2011-05-31 07:33 UTC, Simon McVittie
Details | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
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.