[Xcb] doc (was: Experiences with XCB)

[Vincent Torri]

On Tue, 19 Sep 2006, Jamey Sharp wrote:
>
> Heh. I sympathize, kind of. But were you looking for documentation on
> protocol stubs, or on the core API? We've had pretty OK documentation on
> the core API for more than a year, and of course the protocol stubs are
> rather exhaustingly documented by the relevant protocol specifications.
> While we intend to integrate all of that documentation together
> eventually (actually, we're really just waiting for a volunteer to just
> do it), are you saying that wouldn't have helped you? Everything we plan
> to provide was available to you already, after all... :-)
>
>> Usually, when I don't find enough doc on how to translate an Xlib
>> function in the tutorial, I look at the Xlib code. It's usually easy,
>> then to get the XCB code.
>
> Hmm. Your approach is sound, but somewhat frightening. ;-)

maybe, but it helps me a lot for the translation part of the tutorial, for 
example. And I'm used to do that now...

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

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