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. :) > > 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? > > Bryce > >> > + </para> >> > + <para> >> > The server sends back events to the client, each event is emitted >> > from >> > an object. Events can be error conditions. The event includes the >> > object ID and the event opcode, from which the client can determine >> > @@ -62,14 +88,11 @@ >> > The protocol is sent over a UNIX domain stream socket, where the >> > endpoint >> > usually is named <systemitem class="service">wayland-0</systemitem> >> > (although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis> >> > - in the environment). The protocol is message-based. A >> > - message sent by a client to the server is called request. A message >> > - from the server to a client is called event. Every message is >> > - structured as 32-bit words, values are represented in the host's >> > - byte-order. >> > + in the environment). >> > </para> >> > <para> >> > - The message header has 2 words in it: >> > + Every message is structured as 32-bit words, values are represented >> > in the >> > + host's byte-order. The message header has 2 words in it: >> >> The comma after "32-bit words" probably should be a semi-colon here. >> >> Bryce >> >> > <itemizedlist> >> > <listitem> >> > <para> >> > -- >> > 2.6.1 >> > >> > _______________________________________________ >> > wayland-devel mailing list >> > wayland-devel@lists.freedesktop.org >> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel >> _______________________________________________ >> wayland-devel mailing list >> wayland-devel@lists.freedesktop.org >> http://lists.freedesktop.org/mailman/listinfo/wayland-devel > _______________________________________________ > wayland-devel mailing list > wayland-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/wayland-devel Cheers, Nils _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel