[Xcb] doxygen and documentation

Vincent Torri vtorri at univ-evry.fr
Wed Oct 18 22:16:58 PDT 2006


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.



More information about the Xcb mailing list