[Xcb] doxygen doc of the API

[Josh Triplett]

Vincent Torri wrote:
> i have begun to add in xcb.h some doxygen doc for the API that is
> described in [1].

Awesome.

> 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

Sounds reasonable.

> 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

Hmmm.  I'd tend to say that the docs should be built by default, unless
doxygen is unavailable or you explicitly --disable-doc.

>   c) if not found, check the result of --with-doxygen-path and search
>      doxygen in that path

Typically, if the user gives --with-doxygen-path to configure, they
expect that to be used in preference to automatic discovery.

>   d) AM_CONDITIONAL and rules in doc/api/Makefile.am (generation, install,
>      extra dist, clean)

Sounds good.

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

Definitely.

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

I agree with Bart's suggested separation.

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

In general, I'm not a fan of hungarian-like notation for variable names.
 The particular case of "screenp" might be more clearly written as
"pscreen" or as "screen_ptr" though.

- Josh Triplett
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20060228/64605a45/signature.pgp