[Xcb] XCB documentation effort

[Alan Coopersmith]

On 11/21/11 14:33, Michael Stapelberg wrote:
> Hi everybody,
>
> we just concluded in #i3 that XCB is poorly documented (no news here). I/We
> want to fix this. I’ll list a few random thoughts:
>
> 1) The wiki could needs some love. Not sure if our primary focus should be
>     on the wiki, though?
> 2) We need manpages for functions, just like Xlib has them. We can start by
>     just using the X11 protocol description for every request (automatically
>     generating that) and then enhance it with human-written
>     descriptions/additions/examples.
> 3) The function documentation should probably end up in doxygen as well, though
>     I’m not an experienced doxygen user.
>
> Here are my questions to you:
>
> 1) Is anyone *currently* *actively* working on documentation? If so, what’s
>     your status/goals/timeline?
> 2) Does anyone object to my thoughts above and if so, why?
> 3) Did I miss anything that seems important?
> 4) Do you have any hints/tips?

Matt Dew has been working on the X documentation in general, especially 
finishing up our long planned transition of all the docs from a random
collection of formats to be standardized in DocBook/XML, but I don't
think he's looked much at XCB yet.

I know there's some people who'd like to generate the X protocol specs that
he has been helping with directly from the XCB - that seems very doable for
the encoding sections, but the full text would be more challenging and not
as useful as actually having all the XCB calls documented in a more direct
way than "Go see the protocol specs."

-- 
	-Alan Coopersmith-        alan.coopersmith at oracle.com
	 Oracle Solaris Platform Engineering: X Window System