[Xcb] XCB documentation effort

[Jamey Sharp]

On Mon, Nov 21, 2011 at 10:33:40PM +0000, Michael Stapelberg wrote:
> Hi everybody,
> 
> we just concluded in #i3 that XCB is poorly documented (no news here). I/We
> want to fix this.

Hooray!

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

To the best of my knowledge, nobody is actively working on it.

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

I think you have the right general plan: construct the basic
documentation entirely from the XML protocol descriptions.

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.

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.

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
would also help: we should either keep the tutorial in the wiki or in
the source repo, but probably not both... and I think it makes sense to
make it really simple for people to contribute to the tutorial, by
hosting it on the wiki.

My question for you is, how can we help? :-)

Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111121/57177e52/attachment.pgp>