[Xcb] About the API documentation

[Ian Osgood]

On Jan 10, 2008, at 4:06 PM, Vesa Paatero wrote:

> Hello!
>
> The main page at xcb.freedesktop.org says that the API is documented
> (with a link to the on-line documentation). So, I wonder why the API
> documentation doesn't mention all functions mentioned in the tutorial,
> for example there:
>
> |xcb_poly_point, ||||xcb_poly_line, xcb_poly_rectangle,  
> xcb_poly_arc, xcb_fill_poly, ||||xcb_map_window
>
> |
>
> |Is there some particular rason why those drawing functions and  
> xcb_map_window are not mentioned, or is it just that the API  
> documentation is not ready yet?|
> ||
>
>
> Thank you...
>
>
> Best Regards,
>
>    Vesa Paatero

There are a several levels to the XCB API. LibXCB consists of the  
plumbing required for 1) connecting to a server, 2) getting  
information about the connection, 3) generic client side utilities,  
4) functions used internally to implement protocol requests.  This is  
the API we have documented in header files and on the wiki API page.

On top of this are the X protocol bindings used for requests,  
replies, and their data types, structures, and constants. This is  
code generated automatically from XML protocol descriptions. We  
currently do NOT document the protocol, instead we rely on public X  
protocol documentation and consistent naming conventions. The  
functions you mention are at this level.

There are also convenience functions we have written on top of the X  
protocol. They provide convenience functions that used to be provided  
within Xlib. These live in the xcb/util package, and could use more  
documentation.

Ian