Okay. Reviewed-by <nilschrbra...@googlemail.com>
On Wed, Oct 21, 2015 at 3:34 PM, Auke Booij <a...@tulcod.com> wrote: > On 21 October 2015 at 13:13, Nils Chr. Brause <nilschrbra...@gmail.com> wrote: >> Hi, >> >> On Tue, Oct 20, 2015 at 9:38 AM, Bryce Harrington <br...@osg.samsung.com> >> 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 wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
