[Xcb] doxygen doc of the API
josh at freedesktop.org
Tue Feb 28 09:19:54 PST 2006
Vincent Torri wrote:
> i have begun to add in xcb.h some doxygen doc for the API that is
> described in .
> 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
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)
> 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 ?
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
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...
Size: 256 bytes
Desc: OpenPGP digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20060228/64605a45/signature.pgp
More information about the Xcb