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

[Auke Booij]

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).
+      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.
+    </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:
       <itemizedlist>
 	<listitem>
 	  <para>
-- 
2.6.1