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

Pekka Paalanen ppaalanen at gmail.com
Fri Apr 24 00:07:19 PDT 2015

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

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.


More information about the wayland-devel mailing list