On 22 April 2015 at 08:34, Pekka Paalanen <ppaala...@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! _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel