[Xcb] doxygen and documentation

[Vincent Torri]

Hey,

On Wed, 18 Oct 2006, 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 :)

>
> For those of you who don't know doxygen (and I certainly don't) you need
> to apply the patch, place the xcb.doxygen file in the src directory run
> "doxygen xcb.doxygen".  If someone knows of a better or more correct way
> of doing this speak up.

It's easy to add a doc rule to Makefile.am. Maybe it is better to put 
xcb.doxygen in the doc subdir instead of the top src dir

> My xslt sucks and the patch needs to be cleaned up a lot, it's just a
> proof of concept hack.
>
> For the future:
>
> Depending on how verbose we want to be here are some things to think about:
>
> 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.

both brief and not brief description, I think

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

agreed

Vincent