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

[Bryce Harrington]

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.
> 
> Signed-off-by: Auke Booij <auke at tulcod.com>
> ---
>  doc/publican/sources/Protocol.xml | 35 +++++++++++++++++++++++++++++------
>  1 file changed, 29 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> index 477063b..c6178b7 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -15,6 +15,32 @@
>        identifies which method in the interface to invoke.
>      </para>
>      <para>
> +      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.
> +      A message has a number of arguments, each of which has a certain type (see
> +      <xref linkend="sect-Protocol-Wire-Format"/> for a list of argument types).

The above is a very good addition to the document, and helps make it
more coherent in this early section by better defining requests
vs. events.

> +      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:

      Additionally, the protocol can specify <type>enum</type>s and
      <type>bitfield</type>s.  Both of these are primarily just
      descriptive in nature: at the wire format level arguments of this
      type are actually just integer data, but they identify arguments
      that have specific numeric enumeration values or that are intended
      to be accessed primarily using bitwise operations.  In addition, a
      secondary purpose of the <type>enum</type> and
      <type>bitfield</type> attributes is 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 or bitfield should not break API,
      otherwise it puts backwards compatibility at risk.

      The <type>enum</type> attribute is applicable both for
      <type>int</type> and <type>uint</type> data.  Arguments can refer
      to the specific enumeration that is semantically implied.

      <type>bitfield</type>s are only allowed for <type>uint</type>s.
      This specifies 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.

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.

> +    </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