[Xcb] XCB documentation effort

[Peter Harris]

On 2011-11-24 17:51, Michael Stapelberg wrote:
> 
> I also have a few questions:
> 
> 1) Take the CreateGC request:

>      <valueparam value-mask-type="CARD32"
>                  value-mask-name="value_mask"
>                  value-list-name="value_list" />

>    It obviously supports a bitmask plus some values, which are defined in the
>    enum GC:

>    Now my question is: Where is the connection? How can my generator know what
>    appropriate values for value_mask are?

There isn't any connection at the moment.

Traditionally, there have been so few valueparam requests that we've
just linked them by hand rather than going to the effort of setting up
proper connections. That said, I'd be happier with a connection in the XML.

Short-term, adding a "mask=" to <valueparam> could work. Same principle
as "mask=" on a <field>.

Long-term, I'd like to deprecate <valueparam> in favour of <switch>.
This needs discussion and consensus, and I'd prefer to see at least one
release containing the <switch> in xkb before we apply it to the core
protocol.

Input on this issue is very welcome.

> 2) Instead of using one-letter variable names like 'c' for connection or 'R'
>    for reply, I would like to use 'conn' for connection and 'reply'. Do you
>    have a strong opinion about keeping them one-letter names or can I change
>    them (in the documentation only)?

The names in function parameters are documentation only. Changing the
names affects neither API nor ABI AFAIK, so the change should be okay. I
think I'd be a smidgen happier if the man pages match the .h files, but
I can't bring myself to care all that much.

Peter Harris
-- 
               Open Text Connectivity Solutions Group
Peter Harris                    http://connectivity.opentext.com/
Research and Development        Phone: +1 905 762 6001
pharris at opentext.com            Toll Free: 1 877 359 4866