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

[Pekka Paalanen]

On Thu, 23 Apr 2015 14:45:32 +0000
Jeroen Bollen <jbinero at gmail.com> wrote:

> Hello,
> 
> I do think that docenum and enum should be split up. I don't really get the
> purpose of docenum though. Even if an enum can be extended, that extension
> would technically be an extension to the protocol, would it not?

I listed the two (three) ways you can reasonably add new values to an
<enum> in this thread.

The purpose of docenum was purely for documentation. An API generator
must ignore all docenum annotations. This was the backward-compatible
addition.

Any attribute that modifies the generated API in incompatible ways
cannot be added after the interface has been released as stable. If
your function argument was uint, and you change it to an enum in a
strictly typed language, does it not have a good chance of breaking
someone's build?

Think about distributions. A packager goes and upgrades the libwayland
package, which installs a new wayland.xml with strict type annotations
added. Your code generator starts using these annotation and the
generated API changes. A third party application fails to build from
source because of API mismatch. The packager becomes very unhappy.

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

Did I write this? I can't find the source of this quotation...

> I do not quite agree with this. If an application encounters an enum it's
> not familiar with, it should output a warning or an error. The bindings
> should generate the code to be used by the application. If the application
> wants to extend the protocol, they'll have to extend the specification.

I think that totally depends on how the interface is specified. This
applies only to one of the two ways an <enum> can grow.


Thanks,
pq