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

[Auke Booij]

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").

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.

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?

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).

> 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.

> Thanks,
> pq

Thanks to you for listening and taking these ideas seriously!