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

[Nils Chr. Brause]

Hi,

On Sat, Oct 24, 2015 at 1:07 PM, Auke Booij <auke at tulcod.com> 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 | 41 +++++++++++++++++++++++++++++++++------
>  1 file changed, 35 insertions(+), 6 deletions(-)
>
> diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
> index 477063b..c51cc72 100644
> --- a/doc/publican/sources/Protocol.xml
> +++ b/doc/publican/sources/Protocol.xml
> @@ -15,6 +15,38 @@
>        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).
> +    </para>
> +    <para>
> +      Additionally, the protocol can specify <type>enum</type>s which associate
> +      names to specific numeric enumeration values.  These are primarily just
> +      description in nature: at the wire format level enums are just integers.

*descriptive

> +      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.
> +    </para>
> +    <para>
> +      <type>enum</type>s can be defined as just a set of integers, or as
> +      bitfields.  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.
> +    </para>
> +    <para>
> +      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.
> +    </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 +94,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:
>        <itemizedlist>
>         <listitem>
>           <para>
> --
> 2.6.1
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel


Apart from the typo:

Reviewed-by: <nilschrbrause at googlemail.com>