[Xcb] documentation patches

[Michael Stapelberg]

Hi Uli,

Excerpts from Uli Schlachter's message of 2012-01-11 18:56:17 +0000:
>     There are only two cases when XCB flushes by itself. The first Case is when
>     its write buffer becomes full, the second case is when you are asking for
>     the reply of a request which wasn't flushed out yet (like
>     \fIxcb_query_pointer_reply\fP). This last point also includes
>     xcb_request_check(). Please note that waiting for an event does *NOT* flush.
Merged.

> Ok, how about this:
> 
>    .SH CHECKED VS. UNCHECKED
> 
>     The checked and [just the sentence which was already there]
> 
>     A request is UNCHECKED if errors that it causes are handled by the normal
>     main loop. This means that that you will receive an X11 event of type 0 when
>     calling \fIxcb_wait_for_event\fP.
> 
>     If a request is CHECKED, you will have to explicitly check for errors
>     from this single request. Not doing so will result in a memory leak. See
>     below for details on how to check for errors.
> 
> The point is that this now explains the difference independently from the whole
> "has a reply" / "has no reply" part.
This is exactly what confused me when first reading about the difference
between checked and unchecked (and in fact, I did not understand it for a long
time). Your explanation does not mention *at all* that some requests are
checked by default and some are unchecked and why it is like that.

The default variant does make sense in both cases, and very few users
(according to my view of the world and experiences with XCB, please correct me
if I’m wrong) will need to explicitly call the _[un]checked variant. This is
why I am explaining the default behaviour first in every paragraph.

So, I prefer my explanation. Actually, when I wrote it, I let a friend of mine
proofread it who did not understand the difference between checked and
unchecked before, and he said it became clear. Unless you got a good argument
on why to change this part, I’d be inclined to just leave it like it is.

> I'll just assume that nothing got worse. I skipped most of the python parts anyway.
> BTW: Thanks for going down the documentation road. :-)
You’re welcome ;-).

Best regards,
Michael