[Xcb] doxygen doc of the API

[Vincent Torri]

hey,

i have begun to add in xcb.h some doxygen doc for the API that is
described in [1]. 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

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 --enable-doc). Such
system would require a test on doxygen, of course. I can propose that:

  a) disable generation of the doc by default
  b) if --enable_doc, 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)

3) I put the doc in xcb.h only (not in the .c). The reason is that those
who prefer reading the headers to look at the prototypes can also read the
doc there. Sounds reasonnable ?

4) Should I make groups, like XCB_OUT, XCB_IN, XCB_UTILITIES, etc.., to
separate the different functions/structures ?

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)

comments and remarks are welcome

Vincent

[1] http://xcb.freedesktop.org/wiki/XcbApi