[Xcb] doxygen doc of the API
Barton C Massey
bart at cs.pdx.edu
Tue Feb 28 09:06:37 PST 2006
In message <Pine.LNX.4.51.0602281121240.10338 at cartan.iecn.u-nancy.fr> you wrote:
> i have begun to add in xcb.h some doxygen doc for the API that is
> described in .
You are awesome, as always. Thanks hugely.
> Before I go on, i would like to ask some questions and
> make some remarks:
> 1) I want to put the doc in src/doc/api, just beside the tutorial
Should we move all the documentation to its own module? We
have little modules for everything else... :-)
> 2) I would like to include the generation of the documentation with the
> autofoo system.
> Should I add an option to configure ? (like, for example,
> the doc is always not built by default, and then i add
If it's in its own module, this problem goes away.
> b) automatic check of doxygen
> c) if not found, check the result of --with-doxygen-path and search
> doxygen in that path
> d) AM_CONDITIONAL and rules in doc/api/Makefile.am (generation, install,
> extra dist, clean)
> 4) Should I make groups, like XCB_OUT, XCB_IN, XCB_UTILITIES, etc.., to
> separate the different functions/structures ?
IMHO the split should be
1) xcb core api requests
2) core protocol requests
3) extension requests, by extension
5) xcb bottom-half interface
> 5) While documenting some functions, I have remarked that some names of
> parameters are not always the same (display and displayname, screen and
> screenp, etc...). So I would like to make all that names a bit more
> coherent. In particular, instead of screenp (for a pointer on a screen
> number), i find more readable to use p_screen. What do you think ? We can
> extend such naming (i_toto for a parameter toto which is an int, for
I don't feel strongly about this one way or the other.
One thing to note is that Jamey has "the hard part" of the
new error-handling API done, i.e. he's implemented the
support in XCB core. He wouldn't mind some help from
someone, I believe, with "the other hard part" of hacking up
the XSLT to generate the right stubs.
You will probably want to just document that API from the
beginning; it's what we are really going to want everyone to
Again, thanks much for taking this on!
More information about the Xcb