[Xcb] doc (was: Experiences with XCB)

[Ian Osgood]

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

>
>
> On Tue, 19 Sep 2006, Jamey Sharp wrote:
>
>>> In gneral, you are right, there is a lack of doc about xcb. Once the
>>> naming convention will be out, I think that I'll make a patch so  
>>> that
>>> doc is generated by doxygen if it is found.
>>
>> We should be able to run doxygen at freedesktop.org on a regular  
>> basis,
>> and keep the generated pages at http://xcb.freedesktop.org. We're  
>> ready
>> for that now, I think: I'm again hoping a volunteer will step up  
>> to take
>> care of it. :-)
>
> I've already proposed a patch to build xcb api documentation with  
> doxygen, in a mail, somewhere, sometime... ;)
>
> 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.
>
> 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.
>
> Vincent

Are you envisioning documentation which is copied into comments in  
the xproto.h file?

Ian