Apologies for my lack of responses, I have been abroad for a few days. On 23 April 2015 at 10:38, Pekka Paalanen <ppaala...@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. _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel