[PATCH v2 1/4] doc: document the enum and bitfield attributes
Nils Chr. Brause
nilschrbrause at gmail.com
Wed Oct 21 05:13:06 PDT 2015
Hi,
On Tue, Oct 20, 2015 at 9:38 AM, Bryce Harrington <bryce at 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 at lists.freedesktop.org
>> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>> _______________________________________________
>> wayland-devel mailing list
>> wayland-devel at lists.freedesktop.org
>> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Cheers,
Nils
More information about the wayland-devel
mailing list