[Xcb] documentation patches

[Uli Schlachter]

On 19.12.2011 20:49, Michael Stapelberg wrote:
> Hi,
> 
> attached you can find the final (for now) patches to introcude <doc> tags in
> xproto.xml, make xcbgen handle those tags and make c_client.py spit out
> manpages (and enhance the Doxygen docs) based on these tags.
> 
> I compressed them since they are far too large to be displayed inline in your
> mail client anyways.
> 
> Best regards,
> Michael

Since I don't know any python, let's look at that first. ;-)

0001-c_client.py-generate-manapges.patch:
-----------------------------------------

> @@ -1878,11 +1890,58 @@ def _c_request_helper(self, name, cookie_type, void, regular, aux=False):
>      _c_setlevel(1)
>      _h('')
>      _h('/**')
> -    _h(' * Delivers a request to the X server')
> +    if self.doc:
> +        if self.doc.brief:
> +            _h(' * @brief ' + self.doc.brief)
> +        else:
> +            _h(' * No brief doc yet')
> +
> +    _h(' *')
>      _h(' * @param c The connection')

Should the "No brief doc yet"-case generate a warning on stderr? Or should this
write a log to some file, similar to what doxygen does? Or could one add an
error on purpose in that case, so that this shows up in doxygen's log?


Do you plan to fix the remaining "XXX"s in there? If not, what stops them from
staying in there forever after this was merged? (I don't really mind, but I do
think that "staying in there forever" isn't optimal)

[I skipped over most of the python code....]

WTF is up with src/list_of_manpages.inc? Could that get some line breaks? Also,
does this really have to be maintained by hand? Ssince this depends on the
version of xproto used, how should this work at all? This essentially means that
every addition to xproto will cause a commit to libxcb to be needed.

src/static-man/xcb-examples.3:

FLUSHING:
This should *explain* flushing before giving optimizing suggestions. :-/

COMPILATION:
I'd drop that whole paragraph. Does this really fit into a manpage?

CODING STYLE:
Just drop this.

All in all, this man page doesn't feel all that manual-y to me.

xcb-requests.3:

"datastructure" should be "data structure"

CHECKED VS. UNCHECKED:

This explains that unchecked errors go to the event loop, but it doesn't really
say that checked errors are returned by xcb_request_check(). This should be
mentioned more boldly IMHO.

[The example after this code uses "event_type == 0 => is an error", perhaps this
should be mentioned more prominently, too?)

That's all that I have to say for now. Anyway, thanks for writing this at all, I
hope I'm not too cruel. :-)

I haven't looked at the xcb/proto patch (yet?), sorry.

Cheers,
Uli

-- 
Q: Because it reverses the logical flow of conversation.
A: Why is putting a reply at the top of the message frowned upon?