[Xcb] Some comments on XCB

[Jamey Sharp]

On Tue, 2005-05-31 at 21:53 -0400, Jeremy A. Kolb wrote:
> On Tue, 31 May 2005, Jamey Sharp wrote:
> > ... So in the special case
> > we handle already, "visual_type" is transformed to "VisualType" (or
> > whatever): '_' is a word separator, and the first letter of each word is
> > forced uppercase.
> > 
> > To fix this, I propose to:
> >       * Add '-' and ' ' to the accepted separators, as these are often
> >         used in protocol specs as well.
> >       * Apply the above-described transformation to all function and
> >         type names, and extend it to force the letters after the first
> >         to lowercase.
> >       * Add a new transformation with the same separators, to be used
> >         for all structure fields and function parameter names. For C
> >         this would presumably be all-lowercase and underscore separated.
> >       * Mark-up the XML with spaces at word boundaries.
> 
> So what do we do about naming conventions?  We really need a standard 
> convention, something readable.  If there is one, it is not on the wiki.  
> I can write one if need be.  But we do need a convention with 
> types/variable names/etc..

What I wrote today, quoted above, defines the case convention I want.
All else is, in fact, documented on the wiki, in the "Protocol Stub API"
section at http://xcb.freedesktop.org/wiki/XcbApi :

        These are not single functions or types, but rather naming
        conventions intended to be used in the core protocol API and the
        public API for all extensions. ...
        
        One of the design goals of this API is that users should be able
        to learn these conventions, then read documentation on the
        binary encoding of the core protocol or any extension, and
        immediately determine the correct function name and argument
        list to generate the desired request.

Darn it, people, I documented this. I want some credit for the piles of
documentation I've written about XCB. *whine*

> As for the XCBAux libs it may be a good idea to sit down and figure out 
> what needs to go in those and how we should break up extension specific 
> auxilliary functions.  I can think of a few for record/randr that would be 
> nice to have.
> 
> Once we get a design I can toss it up on the wiki.  But I think this stuff 
> does need to be standardized and probably sooner rather than later.

I admire your readiness to standardize. I suspect we'll need a lot more
implementation experience with XCB before a good API for XCBAux becomes
apparent. But you're welcome to give it a shot.

--Jamey