[Xcb] [PATCH proto 1/3 V2] xml-xcb spec: describe switch-case

[Christian Linhart]

V2: patch revised according to suggestion from Peter Harris:
* add the restriction that <enumref>
  inside <bitcase> can only refer to an enum's <bit> members, and
  <enumref> inside <case> can only refer to an enum's <value> members.

---
 doc/xml-xcb.txt | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index 97ce5bf..f93db7d 100644
--- a/doc/xml-xcb.txt
+++ b/doc/xml-xcb.txt
@@ -239,26 +239,48 @@ enum; the value is restricted to one of the constants named in the enum.
   defining the set of values included, and a list containing these values.
   value-mask-type gives the type of the bitmask; this must be CARD16 or
   CARD32.  value-mask-name gives the field name of the bitmask, and
   value-list-name gives the field name of the list of values. Please use
   <switch> instead for new protocol definitions.
 
 <switch name="identifier"> switch expression
-    <bitcase> bitcase expression(s), fields </bitcase> </switch>
+    <bitcase> bitcase expression(s), fields </bitcase>
+    <case> case expression(s), fields </case>
+</switch>
 
   This element represents conditional inclusion of fields. It can be viewed
-  as sequence of multiple ifs: if ( switch expression & bitcase expression )
-  is non-zero, bitcase fields are included in structure.  It can be used only
-  as the last field of a structure.
+  as sequence of multiple ifs:
 
-  When a bitcase includes multiple <enumref> clauses, the contents of the
-  bitcase are only present once regardless of the number of bitcase expressions
-  that match.
+  <bitcase>:
+    if ( switch expression & bitcase expression ) is non-zero,
+    bitcase fields are included in structure.
+
+  <case>:
+    if ( switch expression == case expression ) is true,
+    then case fields are included in structure.
+
+  It can be used only as the last field of a structure.
+
+  When a bitcase or case includes multiple <enumref> clauses, the contents
+  of the bitcase or case are only present once regardless of the number of
+  bitcase or case expressions that match.
+
+  <enumref> inside <bitcase> can only refer to an enum's <bit> members.
+  <enumref> inside <case> can only refer to an enum's <value> members.
+
+  A switch may contain multiple <bitcase> or <case> elements.
+  Usually it will only contain <bitcase> elements
+  or only contain <case> elements.
+  That is, mixing of <case> and <bitcase> usually doesn't make any sense.
+
+  The same value may appear in multiple <case> or <bitcase> elements.
+
+  New protocol definitions should prefer to use this instead of <valueparam>
+  and instead of <union>.
 
-  New protocol definitions should prefer to use this instead of <valueparam>.
 
 Expressions
 -----------
 
   Expressions consist of a tree of <op> elements with leaves consisting of
   <fieldref> or <value> elements.
 
-- 2.0.1