[Xcb] doxygen and documentation

[Jamey Sharp]

On Wed, Oct 18, 2006 at 09:40:08PM -0400, Jeremy Kolb wrote:
> So I know nothing of xslt or doxygen but I hacked up this diff to
> generate doxygen comments for the proto headers.  Most of it is stub
> work and shows us where we need to go from here but the resulting html
> pages are pretty cool.

Great! This is exactly what I wanted for a first step in this direction.
Thanks!

This finally prompted me to run doxygen and put up the output at
	http://xcb.freedesktop.org/manual/
which should replace our XcbApi pages. If somebody gets around to fixing
the wiki before I do I sure won't complain. :-) Checking that everything
on the wiki is also in the Doxygen comments is a necessary first step...

> My xslt sucks and the patch needs to be cleaned up a lot, it's just a
> proof of concept hack.

I thought about applying it anyway, but I'd like Josh to review first. I
bet he can make it a lot easier to describe these generated comments.

However, I generated the above page using the patched c-client.

> 1.  We need some type of <brief> or <description> field that we can tie
> in to items/fields/requests/constants/etc., to give a basic description
> of an item.

An old goal that I still hope for here is to be able to take the full
text from the original protocol specifications and incorporate it into
the XML descriptions. That text then can be copied into the Doxygen
comments, as well as being used to regenerate pure protocol
documentation. If that has to be split into a "brief" and "full"
description, I guess that's OK, but I'm inclined to turn on Doxygen's
JAVADOC_AUTOBRIEF mode and get rid of all the explicit "@brief" tags.

> 2.  Maybe a <throws> or similar tag... something like <throws
> name="BadMatch" when="index is out of range" />  so we can document
> which requests throw what errors (and events?).

I think that'd be great. Even better if we can devise a description that
allows some simple test cases or server-side checks to be
auto-generated.

> 3.  I think it would be worth while to make enums field types and then
> when generating c code replace the field type with uint32_t or whatever.
> That would be really good for documentation and higher level bindings.

Yes, please. :-) I think it's not even an ABI change, though that's
worth checking. Propose a patch?

--Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20061019/71e6c769/attachment.pgp