[Xcb] XCB documentation effort

[Michael Stapelberg]

Hi Jamey,

Excerpts from Jamey Sharp's message of 2011-11-21 23:32:57 +0000:
> To the best of my knowledge, nobody is actively working on it.
Alright, I declare myself hereby in charge of this. If anyone wants to help,
feel free to contact me. I usually reply to email well within 24 hours.

> But, Doxygen can generate man pages. So I think it makes the most sense
> to do all your documentation generation using Doxygen. I don't think
> you'll need any of the fancy parts of Doxygen, and there's already some
> usable Doxygen-generation in XCB's code generator that you can build on,
> so I don't think that's hard. If I'm wrong, we can do something else.
OK.

> Second, just to make sure we're talking about the same thing: When you
> say "enhance it with human-written descriptions/additions/examples," I'm
> hoping you mean to add those bits of explanatory text to the xcb-proto
> XML, and let the code generator copy them from there into Doxygen
> comments. If instead you mean to auto-generate a documentation template
> and then hand-edit the template to fill it in, I'm not too fond of that
> for maintaining the documentation in the future--and anyway I'd like
> other language bindings to be able to auto-generate their own
> documentation too.
Your concern sounds reasonable, I’ll look into putting it in the XML and then
modifying the generator so that it generates documentation.

> As for the wiki, I think just making Doxygen-generated HTML available
> somewhere under xcb.freedesktop.org would go a long way, as long as we
> could keep it up to date. Although doing something with the tutorial
I agree. I’m not sure how freedesktop.org works from a developer’s point of
view. Could we have a git hook which takes care of updating it?

> My question for you is, how can we help? :-)
At the moment, the action items are on my side. I will keep you (all) updated
in case I need anything :). Probably reviewing documentation on a regular basis
would be a good idea. We’ll see once some work is actually done.

Best regards,
Michael