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

[Pekka Paalanen]

On Wed, 22 Apr 2015 11:47:51 +0200
Auke Booij <auke at tulcod.com> wrote:

> On 22 April 2015 at 08:34, Pekka Paalanen <ppaalanen at gmail.com> 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.
> >
> >
> > How about this:
> >
> > Add three new, mutually exclusive attributes for <arg> tags:
> >
> >         docenum="enumname"
> >
> > Docenum would be for documentation linking only, and should not affect
> > code generation. The effect would be in the documentation to add a link
> > to the definition of the "enumname" <enum>. This attribute is
> > applicable for both int and uint type <arg>s.
> >
> >         enumeration="enumname"
> >
> > Enumeration would be a doc link, but also specify that the <enum>
> > "enumname" is a complete enumeration: no other values are legal. You
> > can use this for code generation. You will rely on interface version
> > negotiation to avoid unknown values in case you have an old definition
> > of the interface and your opponent is using a new definition which
> > added values. This attribute is applicable for both int and uint type
> > <arg>s.
> >
> >         bitfield="enumname"
> >
> > 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.
> > Bits that are not settable by using the listed values must be zero. You
> > rely on the interface versioning to avoid getting undefined bits set,
> > just like enumeration relies for adding new values. This attribute is
> > applicable only to uint type <arg>s.
> >
> >
> > So, both enumeration and bitfield could be used for codegen, docenum
> > would not. Docenum or nothing would be used for cases that do not fit
> > as enumeration or bitfield, including cases where unknown values are
> > always allowed but the interface specification defines what to do when
> > encountering one (ignore, use as a literal value, ...).
> >
> > Wayland-scanner would generate the doclink references in header
> > comments, and check that the referenced enum exists and the <arg> type.
> 
> Two comments on this.
> 
> 1. I do not think it is necessary to distinguish between docenum and
> enumeration. At least for me, I am not asking for any new guarantees
> with regards to completeness: sure, new constants may be added on the
> fly. All I want is semantic information: which (u)int refers to which
> enum? And this data would be provided by your docenum (which I would
> just call "enum").

Jeroen seemed to be wanting that. That's why it gets complicated.

It also wasn't clear as your patch didn't have a good explanation on
what the attributes really mean. Explaining them is the most important
part of a patch, especially how it may affect codegen (or in this
case, must not affect codegen).

> Completeness of enums is information that can be encoded in strongly
> typed languages, but I do not think such guarantees are necessary.
> Bindings should be able to deal with new constants not listed in the
> protocol. If we guarantee completeness of enums, I expect we will get
> all kinds of backwards compatibility issues.

Nice to hear.

> 2. I would say the property of being a bitfield belongs to an enum,
> not to an argument: the type that is generated corresponds to an enum,
> not to an argument. And as such, the properties of this type should
> not depend on the argument's attributes. So I would say the "bitfield"
> attribute should go in the <enum>. Otherwise, what is meant if one
> argument uses an <enum> as a bitfield, and another argument uses the
> same <enum> as a regular enum?

Okay.

> I agree that it should express that OR'ing together any number of
> values from the list should *at least* not be considered a protocol
> error. They may still be disregarded for other reasons, but passing
> OR'ed values in a bitfield should not break protocol, and this is the
> guarantee a bitfield flag should express (IMO).

I'm not sure about that. The allowance to "or" things together was more
related to the "strict enumeration" enforcement.

Interfaces should be able to still say, that a certain combination is
illegal and will lead to a protocol error.

None of it will ever break protocol on the wire level, as it is all
just uints.

Given this and that they must not affect codegen, what are the remaining
differences between enums and bitfields? Enum can be an int, but a
bitfield cannot? Is it worth to have the distinction in the language at
all?

In the end, is the only really useful thing left the doc linking?

It seems the main difference between your and Jeroen's requirements is
that Jeroen wants strict guarantees so that codegen can generate the
strictest APIs in his language.

> > However, a remaining problem is that an interface cannot reference an
> > <enum> defined for a different interface. That is a special case I
> > don't know if we should support in this scheme, because it would
> > require the depended-on XML file to be used during parsing, and we do
> > not require that for wayland-scanner. So I'd rather leave that special
> > case for pure documentation and no attribute, at least for now.
> > Developing a way to reference external interfaces is for another time.
> 
> I agree.
> 
> > 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.
> 
> I will see if I can write a wayland-scanner patch for the above ideas,
> so that we all know what we're talking about.

Cool, thanks,
pq