[PATCH v2 1/4] doc: document the enum and bitfield attributes

[Bryce Harrington]

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.

       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.

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