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

[Auke Booij]

Apologies for my lack of responses, I have been abroad for a few days.

On 23 April 2015 at 10:38, Pekka Paalanen <ppaalanen at gmail.com> wrote:
>> This is a sort of sanity condition on being a bitfield: it does not
>> require all combinations are valid, but it also distinguishes it from
>> a regular enum.
>
> Is that an important distinction to make? That a bitfield with "too
> many" restrictions must not be a bitfield?

Yes, because what the bitfield flag indicates is that it is useful to
think of the values as flags. It means that the values can somehow be
combined. If there is no way to validly combine them, then it is not
useful to think of them like flags. And if the right way to combine
them is not OR'ing, then what you are talking about is not a bitfield.
I am not saying it is a kind of value that is unwelcome in the wayland
API, merely that it is not in the same category as what is usually
considered a bitfield.

And indeed some things (e.g. wl_shell_surface.resize and
xdg_surface.resize_edge) kinda look like a bitfield, but it is up for
discussion whether they actually are, since it also looks like all of
the options are explicitly listed, so in that sense we do not need to
combine values by OR'ing, and it is hence not a bitfield.

Bill's 23rd of April (pseudo)code is very accurate, and highlights the
issues I am trying to address in my bindings. Bill, thanks for that.

Pekka, you keep suggesting "docenum" only be used for documentation.
However, types in richly typed languages *are* documentation (*). They
indicate how you should use certain values. The fact that values are
packaged as a certain enum type *documents* that you should probably
use them in this or that way, without completely blocking use of the
raw data (unless Jeroen's plan goes through).

(*) In fact, in the case of Haskell, more often than not, you can find
functions in an API purely by searching for its type: the type
information of functions documents enough to know their behaviour. In
some languages, the difference between code and documentation is not
so clear-cut.

The entire reason I am asking for this "enum" attribute is so that the
code I generate is more self-documenting. It does not enable the
bindings to compute things it otherwise wouldn't be able to: packaged
(u)ints are still (u)ints. It's to help the user understand the API,
and unless they know better, suggest how they should interact with
wayland.

Jeroen's request, I think, stands separately from this: Jeroen is
asking for strict guarantees on what values are and are not allowed in
enums. Perhaps this should be moved into a separate thread?


So in summary:

- Currently, there is no systematic way to match (u)ints that are
passed around with enums that are defined by the protocol. This makes
the <enum>s, from a technical point of view, somewhat disconnected
from the (u)int arguments.

- Currently, there is no systematic way to tell if bitwise
computations on enum values are supposed to be possible (as per Bill's
example code).

- Currently, there is no guarantee that only certain (u)int values
will be exchanged under a given version of a protocol.

- It would be much welcomed by bindings and documentation generators
if there would be a *semantic* correspondence between (u)ints and
<enum>s. This correspondence would merely indicate how certain (u)ints
are to be interpreted by matching them with an <enum>. This feature
alone should not generate an API that is in any sense stronger or
weaker than without such information (iow, access to the underlying
(u)ints should still be available), but it may look different (e.g.
(u)ints packaged in a type that refers to the right <enum>).

- In strongly typed languages, hints on generating the right API shape
for bitfield-style arguments would be welcomed (as per Bill's example
code). However, details of when something is a "bitfield" need to be
discussed.

- In strongly typed languages, guarantees on which enum values are
allowed in the protocol would be welcomed. However, worries about
compatibility (both between languages and between versions) need to be
worked out in detail. Also, how do such guarantees combine with the
"bitfield" flag?

- Whereas interface names are global, enums are named locally in
interfaces. However, there might be a need to refer to another
interface's <enum>. However, this is a problem that can be solved
later as it comes up (for now the enum attribute would use local
names). As far as I am aware, there is no such situation in any common
protocol right now.