[Xcb] [PATCH] Add more documentation.

[Thomas Fischer]

On Sun, Sep 16, 2018 at 9:33 AM Uli Schlachter <psychon at znc.in> wrote:

> Hi Thomas,
>
> sorry for being awfully slow.
>
> On 26.08.2018 07:14, Thomas Fischer wrote:
> [...]> diff --git a/src/xproto.xml b/src/xproto.xml
> > index 9624700..f78f339 100644
> > --- a/src/xproto.xml
> > +++ b/src/xproto.xml
> > @@ -1828,6 +1828,10 @@ <xcb/xcb.h>
> >      xcb_screen_iterator_t   iter   = xcb_setup_roots_iterator (setup);
> >      xcb_screen_t           *screen = iter.data;
> >
> > +    uint32_t value_mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
> > +    uint32_t value_list[] = { screen->black_pixel,
> > +    XCB_EVENT_MASK_KEY_RELEASE | XCB_EVENT_MASK_EXPOSE
> > +    /* | XCB_EVENT_MASK_* ... */ };
> [...]
>
> What did you base your patch on? The string "xcb_setup_roots_iterator"
> does not appear in the current(?) version of xproto.xml. Thus, your
> patch does not apply here.
>
> Cheers,
> Uli
>

Hello, it's no problem!

The example was based on the tutorial here:
https://xcb.freedesktop.org/tutorial/basicwindowsanddrawing/

The "xcb_setup_roots_iterator" function is generated in
libxcb/src/xproto.{h,c}
Most of the "*_iterator", "*_next" etc. functions are generated, and have
no documentation.
I think the functions "xcb_setup_roots_iterator", "xcb_setup_next",
"xcb_setup_end", etc. are generated by libxcb/src/c_client.py from the
struct "Setup" in xproto.xml:

  <struct name="Setup">
    <field type="CARD8" name="status" /> <!-- always 1 -> Success -->
    <pad bytes="1" />
    <field type="CARD16" name="protocol_major_version" />
    <field type="CARD16" name="protocol_minor_version" />
    <field type="CARD16" name="length" />
    <field type="CARD32" name="release_number" />
    <field type="CARD32" name="resource_id_base" />
    <field type="CARD32" name="resource_id_mask" />
    <field type="CARD32" name="motion_buffer_size" />
    <field type="CARD16" name="vendor_len" />
    <field type="CARD16" name="maximum_request_length" />
    <field type="CARD8" name="roots_len" />
    <field type="CARD8" name="pixmap_formats_len" />
    <field type="CARD8" name="image_byte_order" enum="ImageOrder" />
    <field type="CARD8" name="bitmap_format_bit_order" enum="ImageOrder" />
    <field type="CARD8" name="bitmap_format_scanline_unit" />
    <field type="CARD8" name="bitmap_format_scanline_pad" />
    <field type="KEYCODE" name="min_keycode" />
    <field type="KEYCODE" name="max_keycode" />
    <pad bytes="4" />
    <list type="char" name="vendor">
      <fieldref>vendor_len</fieldref>
    </list>
    <pad align="4" />
    <list type="FORMAT" name="pixmap_formats">
      <fieldref>pixmap_formats_len</fieldref>
    </list>
    <list type="SCREEN" name="roots">
      <fieldref>roots_len</fieldref>
    </list>

Should I change the example, or maybe try to write documentation for these
functions?

Thanks for taking the time to review it,
Thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/xcb/attachments/20180916/5c115c62/attachment-0001.html>