[PATCH wayland] Add "enum" attribute to "arg" elements

[Bill Spitzak]

On 04/21/2015 11:34 PM, Pekka Paalanen wrote:

> I also think this discussion is going off-topic. You wanted to add
> annotations to the XML, so you could find out about enum and bitfield
> arguments, so let's keep to that. There is value in simplicity.

Absolutely agree

> How about this:

Auke's original patch is much more like what is wanted.

> Add three new, mutually exclusive attributes for <arg> tags:
>
> 	docenum="enumname"

This is no different than a normal enumeration.

Whether other values than listed in the enumeration are allowed is part 
of the enumeration definition. And I think Auke does not feel this is 
important right now (and picturing a Python or C++ api it also seems 
unimportant, I agree, the api will allow casting of integers to the enum 
type in all cases. The warning provided by the cast is just as useful 
whether or not the extra value is going to work.

> 	enumeration="enumname"

Certainly use "enum", not "enumeration". No need to increase the keyword 
space.

> 	bitfield="enumname"

This really needs to be part of the enumeration, not the argument list. 
I like the "bitfield"="true" that Auke's patch used.

> Bitfield would be a doc link, but also specify that the values listed
> in <enum> "enumanme" can be orred together to form new legal values.

Yes it is implied that all possible or's of the enum values are allowed 
(this means you can't encode a small enum that has other than a power of 
2 values as a few of the bits, but that is a bad idea anyway).

> However, a remaining problem is that an interface cannot reference an
> <enum> defined for a different interface.

You can reference objects defined by a different interface, right? I 
don't think this is any different. Objects work because you know they 
are represented by an id. For many languages the code generation does 
not depend on the details of the enumeration, it just needs to know it's 
name, so there is no need to parse the other file. And whether int or 
uint is in the api, but that information is already there.

> All these additions are backwards compatible. Scanners should ignore
> tags and attributes they do not recognize.

Yes I'm pretty certain that's why Auke did not replace the "int" and 
"uint" with the enum name and why he added "bitfield"="true" to the enum 
rather than rename enum to bitfield.

> Note, that the meaning of the <enum> tag remains exactly the same: a
> namespaced collection of named constants. Nothing more strict.

Yes except there should be an indication added whether or not it is a 
bitfield. This has zero effect on most code generation. It does not 
require that the values be powers of two (there is likely to be useful 
combinations given as abbreviated names listed, for instance 
"topleft_corner" which combines the bits for "top_edge" and "left_edge").

> All that said, this is just a quick draft I haven't really thought
> through. You could name the attributes differently, change docenum to
> be an attribute for <description> rather than <arg>, etc.

Auke's original patch is almost perfect imho.