xcb-doc: add paramref

[free-sw/xcb/proto] / doc / xml-xcb.txt

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index 97ce5bf..f8129ea 100644 (file)
--- a/doc/xml-xcb.txt
+++ b/doc/xml-xcb.txt
@@ -184,11 +184,12 @@ separated by a single colon.  For example, to refer to the PIXMAP type defined
 in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
 than type="PIXMAP".
 
-Note: Most of the below may optionally contain an enum, altenum, or mask
+Note: Most of the below may optionally contain an enum, altenum, mask or altmask
 attribute, which follows the above rules for "type". "enum" is an exhaustive
 enum; the value is restricted to one of the constants named in the enum.
 "altenum" may be one of the values contained in the enum, but it need not be.
-"mask" refers to an enum to be used as a bitmask.
+"mask" refers to an exhaustive enum to be used as a bitmask.
+"altmask" may be a mask from the referred enum, but it need not be.
 
 <pad bytes="integer" />
 
@@ -243,18 +244,40 @@ enum; the value is restricted to one of the constants named in the enum.
   <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
 -----------
@@ -275,6 +298,23 @@ Expressions
   the structure containing this expression.  The identifier is the value of
   the "name" attribute on the referenced field.
 
+<paramref type="type">identifier</paramref>
+
+  A paramref is similar to a fieldref, but it refers to the value of
+  a field in the context which refers to the struct which contains the paramref.
+
+  So, it refers to a field outside of the structure where it is defined.
+  This has the following consequences:
+  * The generator cannot deduce its type.
+    So, it is mandatory to specify its type.
+  * The identifier-name must not be used as a field in the structure
+    which contaons the paramref.
+
+  For an example, see struct "DeviceTimeCoord" and request/reply
+  "GetDeviceMotionEvents" in xinput.xml, where paramref "num_axes"
+  in struct DeviceTimeCoord refers to field "num_axes" in
+  the DeviceTimeCoord reply.
+
 <value>integer</value>
 
   The value element represents a literal integer value in an expression.  The
@@ -299,10 +339,26 @@ Expressions
 
   This element represents a sumation of the elements of the referenced list.
 
+<sumof ref="identifier" >expression</sumof>
+
+  The expression is evaluated for each element of the referenced list,
+  in the context of this element.
+  This sumof element then represents a sumation of the results of these
+  evaluations.
+
+  expression will usually be a fieldref which references a field of
+  a list-element or an expression containing a fieldref,
+  such as popcount of a fieldref.
+
 <popcount>expression</popcount>
 
   This element represents the number of bits set in the expression.
 
+<listelement-ref/>
+
+  This element represents the current list-element when used inside
+  a list-iteration expression such as <sumof>.
+
 Documentation
 -------------