[Xcb] doc (was: Experiences with XCB)

[Vincent Torri]

On Wed, 20 Sep 2006, Ian Osgood wrote:

> On Sep 20, 2006, at 12:27 AM, Vincent Torri wrote:

>> A question : do we make a single doc (generated by doxygen) for
>> * xcb api or
>> * x protocol or
>> * xcb utils
>> or several for each (or more) of these parts ? Currently, there are doxygen 
>> docs for xcb api and xcb-image api.

> XCB static API is one document. Core X protocol is another document. Each 
> extension is another document. Each util library is another document.

I was thinking about a doc like this one :

http://www.maths.univ-evry.fr/pages_perso/vtorri/files/doc_html.tar.bz2

It's about a doc of a project I'm working on. As you can see, we can 
separate easily the different parts, with only one doc. We can also use 
grouping doc with dosygen.

I like the idea of a big doc where everything can be found, instead of 
several doc to get in different places. It bores me a bit ;-)

>> A remark: When Josh finish to clean my ugly code in c-client.xsl, if he can 
>> add a support for doc in the protocol, compatible with doxygen, then adding 
>> the doc will not that hard. I think that what is needed is:
>> * a "group" field (to group events, drawable related functions, etc...),
>> * a "brief description" field,
>> * a "detailed descrition" field,
>> the remaining part of the doc can be generated automatically, I think.
>
> Are you envisioning documentation which is copied into comments in the 
> xproto.h file?

What I see is : comments in tags in the xml files. And xslt writing 
doxygen doc comments in xproto.h or xproto.c. And finally, doxygen 
creating the doc from those comments.

Any other ideas ?

Vincent