[Xcb] XCB naming conventions (progress)

[Ian Osgood]

On Sep 16, 2006, at 2:49 AM, Vincent Torri wrote:

>
> Hey,
>
> so, xproto.h is almost correctly generated, now. There is some  
> problems and remarks that I want to discuss here.
>
> Problems:
>
> 1) XCBBUTTON struct type and XCBButton enum type have the same name  
> with underscores (xcb_button_t). I think that we should rename  
> XCBButton. Any Idea for that ? In X.h, it's described as button  
> names. So maybe the protocol description should be changed in  
> XCBButtonName.

This enumeration is used similarly to XCBMapIndex.  Perhaps we could  
name it XCBButtonIndex.

My convention was to name the enumerations so that the generated  
names matched the X.h names as closely as possible to ease migration.  
(Almost all of the enumerations, including XCBButton, match X.h but  
with the "XCB" prefix.) I had to change some enumeration names to  
avoid conflicts with the error numbers, which don't otherwise have a  
distinguishing suffix (a bug, in my opinion).

(This brings up another quibble. Why do we have a separate named  
structure for every error returned when they are all structurally  
identical? I propose a single XCBCoreError structure instead.)

>
> 2) same problem with XCBHOST and XCBHost. Although I don't have an  
> idea for the enum name. X.h does not describe it well.

This for the "mode" member of the XCBChangeHosts structures and  
requests.

One solution is to leave the enumerations unnamed, to avoid polluting  
the namespace. This has precedent in Apple's Carbon and pre-Carbon  
APIs. Nothing else in XCB refers to them. However, this closes the  
door on future type-safety and protocol documentation work.

Another solution is to reuse the XCBSetMode enumeration already used  
for XCBChangeSaveSet. This works nicely because it matches the "mode"  
member for a bit of self-documentation.  (I think this is my  
preference.)

Another solution is to break with X.h and try instead to match the  
member name where the enumeration is used. In this case, that would  
be XCBHostMode { XCBHostModeInsert, XCBHostModeDelete }.  This may  
make the most sense, since this whole naming change will completely  
break with X.h (which uses StudlyCaps thoughout).

You suggested another solution, use a different suffix for  
enumerations, _e.

>
> 3) I have a technical problem with XSLT : some requests ask for  
> pointer and its length. I automatically add '_t' to the name of the  
> type, but there is a problem in case the type is char and void. The  
> xsl code is :
>
>       <xsl:attribute name="type">
>         <xsl:text>const </xsl:text>
>         <xsl:call-template name="canonical-type-name" />
>         <xsl:text>_t *</xsl:text>
>       </xsl:attribute>
>
> So I would like to test the value returned by the template and add  
> if only if the value of canonical-type-name is different from char  
> and void
>
> Does someone have an idea on how to do that ?
>
> Remarks:
>
> 1) in xproto.xml, there is the structure SetupReq. Shouldn't iit be  
> renamed as SetupRequest ?

Yes. I think Jamey also wanted to expand all "Req" to "Request" and  
all "Rep" to "Reply" as well.

>
> 2) for enum dans define values, I use upper case letter, with words  
> separated with underscores. Is it ok for everybody ?

I'm not  sure what you mean here. Could you give an example?

Another thing: once renaming in xproto is complete, will we want to  
use the same naming conventions on the symbols in xcb.h?

> I think that's enough for now.
>
> thank you
>
> Vincent
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
>