[PATCH] Add documentation

---
diff --git a/src/xproto.xml b/src/xproto.xml
index dea48df..6483dff 100644
--- a/src/xproto.xml
+++ b/src/xproto.xml
@@ -1147,6 +1147,27 @@ <enum name="WindowClass">
     <item name="CopyFromParent"><value>0</value></item>
     <item name="InputOutput">   <value>1</value></item>
     <item name="InputOnly">     <value>2</value></item>
+    <doc>
+      <field name="CopyFromParent"><![CDATA[
+The class is taken from the `parent`. A `depth` of zero for class `InputOutput`
+or `CopyFromParent` means the `depth` is taken from the `parent`.
+        ]]></field>
+      <field name="InputOutput"><![CDATA[
+An `InputOutput` window is the normal kind of opaque window, used for both
+input and output. `InputOutput` windows can have both `InputOutput` and
+`InputOnly` windows as inferiors.
+        ]]></field>
+      <field name="InputOnly"><![CDATA[
+An `InputOnly` window is a window that cannot be used for graphics requests.
+`InputOnly` windows are invisible and can be used to control such things as
+cursors, input event generation, and grabbing. `InputOnly` windows cannot have
+`InputOutput` windows as inferiors.
+
+The server essentially acts as if `InputOnly` windows do not exist for the
+purposes of graphics requests, exposure processing, and `VisibilityNotify`
+events.
+        ]]></field>
+    </doc>
   </enum>

   <!-- Window attributes for CreateWindow and ChangeWindowAttributes. -->
@@ -1250,20 +1271,23 @@ <enum name="CW">
 ancestor windows when no client has the event type selected in this window.
       ]]></field>
       <field name="Colormap"><![CDATA[
-The colormap specifies the colormap that best reflects the true
colors of the window. Servers
-capable of supporting multiple hardware colormaps may use this
information, and window man-
-agers may use it for InstallColormap requests. The colormap must have
the same visual type
-and root as the window (or a Match error results). If CopyFromParent
is specified, the parent's
-colormap is copied (subsequent changes to the parent's colormap
attribute do not affect the child).
-However, the window must have the same visual type as the parent (or
a Match error results),
-and the parent must not have a colormap of None (or a Match error
results). For an explanation
-of None, see FreeColormap request. The colormap is copied by sharing
the colormap object
-between the child and the parent, not by making a complete copy of
the colormap contents.
+The colormap specifies the colormap that best reflects the true colors of the
+window. Servers capable of supporting multiple hardware colormaps may use this
+information, and window man- agers may use it for `InstallColormap` requests.
+The colormap must have the same visual type and `root` as the window (or a
+`Match` error results). If `CopyFromParent` is specified, the parent's colormap
+is copied (subsequent changes to the parent's colormap attribute do not affect
+the child).  However, the window must have the same visual type as the parent
+(or a Match error results), and the parent must not have a colormap of `None`
+(or a `Match` error results). For an explanation of `None`, see `FreeColormap`
+request. The colormap is copied by sharing the colormap object between the
+child and the parent, not by making a complete copy of the colormap contents.
       ]]></field>
       <field name="Cursor"><![CDATA[
-If a cursor is specified, it will be used whenever the pointer is in
the window. If None is speci-
-fied, the parent's cursor will be used when the pointer is in the
window, and any change in the
-parent's cursor will cause an immediate change in the displayed cursor.
+If a cursor is specified, it will be used whenever the pointer is in the
+window. If `None` is specified, the parent's cursor will be used when the
+pointer is in the window, and any change in the parent's cursor will cause an
+immediate change in the displayed cursor.
       ]]></field>
     </doc>
   </enum>
@@ -1365,7 +1389,7 @@ <request name="CreateWindow" opcode="1">
     </switch>

     <doc>
-      <brief>Creates a window</brief>
+      <brief>Creates a window and assigns the identifier wid to it</brief>
       <description><![CDATA[
 Creates an unmapped window as child of the specified `parent` window. A
 CreateNotify event will be generated. The new window is placed on top in the
@@ -1387,7 +1411,7 @@ <request name="CreateWindow" opcode="1">
 `xcb_generate_id`.
       ]]></field>
       <field name="depth"><![CDATA[
-Specifies the new window's depth (TODO: what unit?).
+Specifies the new window's color depth in pits per pixel.

 The special value `XCB_COPY_FROM_PARENT` means the depth is taken from the
 `parent` window.
@@ -1403,35 +1427,63 @@ <request name="CreateWindow" opcode="1">
 The parent window of the new window.
       ]]></field>
       <field name="border_width"><![CDATA[
-      TODO:
+An `InputOutput` window can have a border of equal thickness on all
four sides of
+the window. A `pixmap` defines the contents of the border, and the server
+automatically maintains the contents of the border. Exposure events are never
+generated for border regions.

 Must be zero if the `class` is `InputOnly` or a `xcb_match_error_t` occurs.
       ]]></field>
       <field name="x"><![CDATA[The X coordinate of the new window.]]></field>
       <field name="y"><![CDATA[The Y coordinate of the new window.]]></field>
       <field name="width"><![CDATA[The width of the new window.]]></field>
-      <field name="height"><![CDATA[The height of the new window.]]></field>
+      <field name="height"><![CDATA[The height of the new window.
+
+The `width` and `height` specify the inside size, not including the
`border_width`,
+and must be nonzero (or a `Value` error results).
+      ]]></field>
+      <field name="value_mask" />
+      <field name="value_list"><![CDATA[
+Values for each of the attributes specified in the bitmask `value_mask`. The
+order has to correspond to the order of possible `value_mask` bits. See the
+example.
+      ]]></field>
       <error type="Colormap"><![CDATA[
-TODO: reasons?
+The value given for the `colormap` argument does not refer to a defined
+`xcb_colormap_t`.
       ]]></error>
       <error type="Match"><![CDATA[
-TODO: reasons?
+For an `InputOnly` window the `border_width` and the `depth` must be zero or
+`CopyFromParent`.
+
+For an `InputOutput` window, the visual type and the `depth` must be a
+combination supported for the screen. The parent of an `InputOutput` window
+must not be a window of class `InputOnly`.
       ]]></error>
       <error type="Cursor"><![CDATA[
-TODO: reasons?
+A value for a `xcb_cursor_t` argument does not refer to a defined
`xcb_cursor_t`.
       ]]></error>
       <error type="Pixmap"><![CDATA[
-TODO: reasons?
+A value for a `xcb_pixmap_t` argument does not refer to a defined
`xcb_pixmap_t`.
       ]]></error>
       <error type="Value"><![CDATA[
-TODO: reasons?
+Some numeric value falls outside the range of values accepted by the request.
+
+The `width` and `height` must be nonzero.
       ]]></error>
       <error type="Window"><![CDATA[
-TODO: reasons?
+The specified `window` does not exist.
       ]]></error>
       <error type="Alloc"><![CDATA[
-The X server could not allocate the requested resources (no memory?).
+The X server could not allocate the requested resource. Note that when a server
+runs out of allocation space the semantics are left unspecified, but a server
+may generate an `xcb_alloc_error_t` error on any request.
       ]]></error>
+    <example>
+      <![CDATA[
+See xcb_map_window(3).
+      ]]>
+    </example>
       <see type="function" name="xcb_generate_id" />
       <see type="request" name="MapWindow" />
       <see type="event" name="CreateNotify" />
@@ -1758,6 +1810,56 @@ <request name="MapWindow" opcode="8">
       <error type="Match"><![CDATA[
 The specified window does not exist.
       ]]></error>
+    <example>
+      <![CDATA[
+#include <unistd.h>      /* pause() */
+
+#include <xcb/xcb.h>
+
+int
+main ()
+{
+    /* Open the connection to the X server */
+    xcb_connection_t *connection = xcb_connect (NULL, NULL);
+
+
+    /* Get the first screen */
+    const xcb_setup_t      *setup  = xcb_get_setup (connection);
+    xcb_screen_iterator_t   iter   = xcb_setup_roots_iterator (setup);
+    xcb_screen_t           *screen = iter.data;
+
+
+    /* Create the window */
+    xcb_window_t window = xcb_generate_id (connection);
+    xcb_create_window (connection,                    /* Connection          */
+                       XCB_COPY_FROM_PARENT,          /* depth (same as root)*/
+                       window,                        /* window Id           */
+                       screen->root,                  /* parent window       */
+                       0, 0,                          /* x, y                */
+                       150, 150,                      /* width, height       */
+                       10,                            /* border_width        */
+                       XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
+                       screen->root_visual,           /* visual              */
+                       0, NULL );                     /* masks, not used yet */
+
+
+    /* Map the window on the screen */
+    xcb_map_window (connection, window);
+
+
+    /* Make sure commands are sent before we pause so that the window
gets shown */
+    xcb_flush (connection);
+
+
+    pause();    /* hold client until Ctrl-C */
+
+    xcb_disconnect (connection);
+
+    return 0;
+}
+
+      ]]>
+    </example>
       <see type="event" name="MapNotify" />
       <see type="event" name="Expose" />
       <see type="request" name="UnmapWindow" />
---
_______________________________________________
Xcb mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/xcb