[Xcb] doxygen doc of the API

[Barton C Massey]

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 [1].

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.

Good.

>  Should I add an option to configure ? (like, for example,
> the doc is always not built by default, and then i add
> --enable-doc).

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)

Sounds great.

> 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
  4) utils
  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
> example)

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
use. 

Again, thanks much for taking this on!

   Bart