[Xcb] XCB documentation effort

[Matt Dew]

On 11/21/2011 06:51 PM, Alan Coopersmith wrote:
> 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."
>

I have not looked at XCB specifically.  I actually think XCB is one of 
the better documented areas of X so it wasn't high on my list. It has 
more doxygen work done than any other area, except possibly the doxygen 
work done on the input system done by Peter Hutterer.


To specifically answer your questions:
1) Yes, I'm actively working on documentation. (though  I'm not fast at 
it, I only get a few hours a week to work on it.)
    Goals are:
     A) to convert all the intree documentation into docbook. - pretty 
much done
     B) cleanup and style those docs into a set so it looks really nice. 
- end of year
     C) Update the documentation so it's accurate - no idea how long 
this will take;  hopefully by XDS 2012
     D) re-organize the wiki - start on that Beginning of next year, 
hopefully done by XDS 2012


2) +1 - if you can generate the manpages from doxygen, that's the best 
IMHO. I'm still a newbie at doxygen though so I don't know the options here.

3) I think you need to have a discussion to determine what exactly 
people think needs to be done and break it down into individual steps; 
not necessarily a specific order, but at least what needs to be done. A 
face-to-face meeting to start would be the best, with lots of whiteboard 
space and take pictures of all the whiteboard drawings and record the 
audio of the entire meeting(s).
   Re-organizing a wiki is a _HUGE_ amount of work and it gets tedious 
and boring really quickly.  Don't underestimate it.

4)   Keep as much documentation in the source code files as possible; 
doxygen for what you can.  It's the most maintainable long term.  Having 
to maintain documentation separately from the code is extra work and 
it's very easy for them to diverge over time; you can pretty much be 
guaranteed that they will diverge.   Think carefully about what you want 
on the wiki.  Personally I don't think that wikis are not the best place 
for a lot of documentation; unless you do it like gentoo where those 
pages are generated from static xml files (which could be generated from 
something else.

Example: If the config file doesn't change, don't put the documentation 
for it in wiki form.  Put it in the code, if possible, and generate the 
man-pages and web-documentation from that.  Then if someone references 
it in a wiki page, just add a link to the generated documentation.

If possible, there needs to be a small group or team in charge of the 
wiki, for consistency.  Others can edit but allowing everyone to create 
their own structure will result in no overarching theme; which makes it 
harder to find things. "Too many chefs spoil the broth."

Ugly but consistent beats pretty but inconsistent.


Sorry for the essay there. These are just my humble opinions. I hope 
they're helpful.

Let me know if I can help.
Matt


P.S. Alan, the last of the docbook docs, Intrinsics in libXt, is 
actually done. At this point I'm just using it for styling 
experimentation to see what looks good. Then I'll use that to mark up 
the other docs.  If you're curious: 
http://cgit.freedesktop.org/~marcoz/libXt