On 21 October 2015 at 13:13, Nils Chr. Brause <[email protected]> wrote: > Hi, > > On Tue, Oct 20, 2015 at 9:38 AM, Bryce Harrington <[email protected]> > wrote: >> On Tue, Oct 20, 2015 at 12:01:14AM -0700, Bryce Harrington wrote: >>> On Mon, Oct 19, 2015 at 11:21:23PM +0100, Auke Booij wrote: >>> > Introduce the enum and bitfield attributes, which allow you to refer to >>> > the enum >>> > you are expecting in an argument, and specify which enums are to be >>> > thought of >>> > as bitfields. >>> > >>> > + Additionally, the protocol can specify <type>enum</type>s. These >>> > are used >>> > + to list options for <type>int</type> and <type>uint</type> type >>> > arguments. >>> > + Arguments can refer to the specific enumeration that is >>> > semantically >>> > + implied. Only in the case that the argument is of type >>> > <type>uint</type>, >>> > + it can be specified that the primary interface to its numeric >>> > value deals >>> > + with bitwise operations, for example when arbitrarily many choices >>> > of the >>> > + enum can be ORed together. >>> > + </para> >>> > + <para> >>> > + The purpose of the <type>enum</type> and <type>bitfield</type> >>> > attributes >>> > + is to document what arguments refer to which enums, and to >>> > document which >>> > + numeric enum values are primarily accessed using bitwise >>> > operations. >>> > + Additionally, the enum and bitfield attributes may be used by >>> > other code, >>> > + such as bindings to other languages, for example to enhance type >>> > safety of >>> > + code. However, such usage is only supported if the following >>> > property is >>> > + satisfied: code written prior to the specification of these >>> > attributes >>> > + still works after their specification. In other words, specifying >>> > an >>> > + attribute for an argument, that previously did not have an enum or >>> > + bitfield attribute, should not break API. Code that does not >>> > satisfy this >>> > + rule is not guaranteed to obey backwards compatibility. >>> >>> This next chunk gets a bit too jarringly technical too quickly. I think >>> your second paragraph gives a better intro to these attributes, but it >>> doesn't work to simply swap them. Let me take a shot at copyediting >>> this a bit: >>> >>> I think this is clearer, and hopefully hasn't lost any meaning. I'm not >>> sure it's improved the technicality of this prose... perhaps this >>> section would be better promoted to its own section, with maybe just a >>> reference sentence included here? Not sure. >> >> I'm noticing now that I've misunderstood what the bitfield attribute is; >> so the above text is incorrect. Let me try again. >> >> Additionally, the protocol can specify <type>enum</type>s which >> associate specific numeric enumeration values. These are >> primarily just description in nature: at the wire format level >> enums are just integers. But they also serve a secondary purpose >> to enhance type safety or otherwise add context for use in >> language bindings or other such code. This latter usage is only >> supported so long as code written before these attributes were >> introduced still works after; in other words, adding an enum >> should not break API, otherwise it puts backwards compatibility >> at risk. >> >> <type>enum</type>s can be defined as bitfields or just a set of >> integers. This is specified via the <type>bitfield</type> >> boolean attribute in the <type>enum</type> definition. If this >> attribute is true, the enum is intended to be accessed primarily >> using bitwise operations, for example when arbitrarily many >> choices of the enum can be ORed together; if it is false, or the >> attribute is omitted, then the enum arguments are a just a >> sequence of numerical values. > > I am fine with that wording, but it actually is much simpler than that: > In a bitfield every bit has a distinct meaning. In an enumeration, that > is not the case. :)
Like any suggestion us foreign language binders make, while yours is perfectly reasonable in principle, C's abuse of everything makes me want to be a bit careful in this. Additionally, after a long discussion, this is the kind of wording that people seemed to agree on, so personally, I am not planning to make drastic changes in this again. I think Bryce's suggestion will not cause any further disagreements, so I will probably use that in an updated patch. > >> >> The <type>enum</type> attribute can be used on either >> <type>uint</type> or <type>int</type> arguments, however if the >> <type>enum</type> is defined as a <type>bitfield</type>, it can >> only be used on <type>uint</type> args. > > Just out of curiosity: Why does the signess matter for a bitfield? The signedness matters because the signedness shouldn't matter. And if it really doesn't matter, we might as well require it to be unsigned: this is the typical type of a bit field in C, and a signed int suggests something else is going on. I'm intentionally careful here: in my imagined use case, bit fields are unsigned. A signed bit field is something I don't know, and don't make any promises about. If signed bit fields later turn out to be a thing that we want, we can always start allowing that in a later stage. The reverse is not true: we cannot stop allowing signed bit fields. That's why. _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
