Merge remote-tracking branch 'origin/released'

9 files changed, 4217 insertions, 465 deletions

diff --git a/libxcb/src/Makefile.am b/libxcb/src/Makefile.am
index 950de5c14..fed691447 100644
--- a/libxcb/src/Makefile.am
+++ b/libxcb/src/Makefile.am
@@ -225,8 +225,14 @@ endif
 nodist_xcbinclude_HEADERS = $(EXTHEADERS)
 noinst_HEADERS = xcbint.h
 
-BUILT_SOURCES = $(EXTSOURCES)
-CLEANFILES = $(EXTSOURCES) $(EXTHEADERS)
+STATIC_MANS = man/xcb-examples.3 man/xcb-requests.3
+BUILT_MANS = man/xcb_*.3
+man_MANS = = $(STATIC_MANS) $(BUILT_MANS)
+
+BUILT_SOURCES = $(EXTSOURCES) $(BUILT_MANS)
+CLEANFILES = $(EXTSOURCES) $(EXTHEADERS) $(BUILT_MANS)
 
 $(EXTSOURCES): c_client.py
 	$(PYTHON) $(srcdir)/c_client.py -p $(XCBPROTO_XCBPYTHONDIR) $(XCBPROTO_XCBINCLUDEDIR)/$(@:.c=.xml)
+
+$(man_MANS): $(EXTSOURCES)
diff --git a/libxcb/src/c_client.py b/libxcb/src/c_client.py
index 0f9974899..cbd235659 100644
--- a/libxcb/src/c_client.py
+++ b/libxcb/src/c_client.py
@@ -3,7 +3,9 @@ from xml.etree.cElementTree import *
 from os.path import basename
 from functools import reduce
 import getopt
+import os
 import sys
+import time
 import re
 
 # Jump to the bottom of this file for the main routine
@@ -31,6 +33,11 @@ finished_serializers = []
 finished_sizeof = []
 finished_switch = []
 
+# keeps enum objects so that we can refer to them when generating manpages.
+enums = {}
+
+manpaths = False
+
 def _h(fmt, *args):
     '''
     Writes the given line to the header file.
@@ -248,6 +255,8 @@ def c_enum(self, name):
     Exported function that handles enum declarations.
     '''
 
+    enums[name] = self
+
     tname = _t(name)
     if namecount[tname] > 1:
         tname = _t(name + ('enum',))
@@ -262,7 +271,10 @@ def c_enum(self, name):
         count = count - 1
         equals = ' = ' if eval != '' else ''
         comma = ',' if count > 0 else ''
-        _h('    %s%s%s%s', _n(name + (enam,)).upper(), equals, eval, comma)
+        doc = ''
+        if hasattr(self, "doc") and self.doc and enam in self.doc.fields:
+            doc = '\n/**< %s */\n' % self.doc.fields[enam]
+        _h('    %s%s%s%s%s', _n(name + (enam,)).upper(), equals, eval, comma, doc)
 
     _h('} %s;', tname)
 
@@ -1879,11 +1891,58 @@ def _c_request_helper(self, name, cookie_type, void, regular, aux=False):
     _c_setlevel(1)
     _h('')
     _h('/**')
-    _h(' * Delivers a request to the X server')
+    if hasattr(self, "doc") and self.doc:
+        if self.doc.brief:
+            _h(' * @brief ' + self.doc.brief)
+        else:
+            _h(' * No brief doc yet')
+
+    _h(' *')
     _h(' * @param c The connection')
+    param_names = [f.c_field_name for f in param_fields]
+    if hasattr(self, "doc") and self.doc:
+        for field in param_fields:
+            # XXX: hard-coded until we fix xproto.xml
+            base_func_name = self.c_request_name if not aux else self.c_aux_name
+            if base_func_name == 'xcb_change_gc' and field.c_field_name == 'value_mask':
+                field.enum = 'GC'
+            elif base_func_name == 'xcb_change_window_attributes' and field.c_field_name == 'value_mask':
+                field.enum = 'CW'
+            elif base_func_name == 'xcb_create_window' and field.c_field_name == 'value_mask':
+                field.enum = 'CW'
+            if field.enum:
+                # XXX: why the 'xcb' prefix?
+                key = ('xcb', field.enum)
+
+                tname = _t(key)
+                if namecount[tname] > 1:
+                    tname = _t(key + ('enum',))
+                _h(' * @param %s A bitmask of #%s values.' % (field.c_field_name, tname))
+
+            if self.doc and field.field_name in self.doc.fields:
+                desc = self.doc.fields[field.field_name]
+                for name in param_names:
+                    desc = desc.replace('`%s`' % name, '\\a %s' % (name))
+                desc = desc.split("\n")
+                desc = [line if line != '' else '\\n' for line in desc]
+                _h(' * @param %s %s' % (field.c_field_name, "\n * ".join(desc)))
+            # If there is no documentation yet, we simply don't generate an
+            # @param tag. Doxygen will then warn about missing documentation.
+
     _h(' * @return A cookie')
     _h(' *')
-    _h(' * Delivers a request to the X server.')
+
+    if hasattr(self, "doc") and self.doc:
+        if self.doc.description:
+            desc = self.doc.description
+            for name in param_names:
+                desc = desc.replace('`%s`' % name, '\\a %s' % (name))
+            desc = desc.split("\n")
+            _h(' * ' + "\n * ".join(desc))
+        else:
+            _h(' * No description yet')
+    else:
+        _h(' * Delivers a request to the X server.')
     _h(' * ')
     if checked:
         _h(' * This form can be used only if the request will not cause')
@@ -2202,6 +2261,523 @@ def _c_cookie(self, name):
     _h('    unsigned int sequence; /**<  */')
     _h('} %s;', self.c_cookie_type)
 
+def _man_request(self, name, cookie_type, void, aux):
+    param_fields = [f for f in self.fields if f.visible]
+
+    func_name = self.c_request_name if not aux else self.c_aux_name
+
+    def create_link(linkname):
+        name = 'man/%s.3' % linkname
+        if manpaths:
+            sys.stdout.write(name)
+        f = open(name, 'w')
+        f.write('.so man3/%s.3' % func_name)
+        f.close()
+
+    if manpaths:
+        sys.stdout.write('man/%s.3 ' % func_name)
+    # Our CWD is src/, so this will end up in src/man/
+    f = open('man/%s.3' % func_name, 'w')
+    f.write('.TH %s 3  %s "XCB" "XCB Requests"\n' % (func_name, today))
+    # Left-adjust instead of adjusting to both sides
+    f.write('.ad l\n')
+    f.write('.SH NAME\n')
+    brief = self.doc.brief if hasattr(self, "doc") and self.doc else ''
+    f.write('%s \\- %s\n' % (func_name, brief))
+    f.write('.SH SYNOPSIS\n')
+    # Don't split words (hyphenate)
+    f.write('.hy 0\n')
+    f.write('.B #include <xcb/%s.h>\n' % _ns.header)
+
+    # function prototypes
+    prototype = ''
+    count = len(param_fields)
+    for field in param_fields:
+        count = count - 1
+        c_field_const_type = field.c_field_const_type
+        c_pointer = field.c_pointer
+        if c_pointer == ' ':
+            c_pointer = ''
+        if field.type.need_serialize and not aux:
+            c_field_const_type = "const void"
+            c_pointer = '*'
+        comma = ', ' if count else ');'
+        prototype += '%s\\ %s\\fI%s\\fP%s' % (c_field_const_type, c_pointer, field.c_field_name, comma)
+
+    f.write('.SS Request function\n')
+    f.write('.HP\n')
+    base_func_name = self.c_request_name if not aux else self.c_aux_name
+    f.write('%s \\fB%s\\fP(xcb_connection_t\\ *\\fIconn\\fP, %s\n' % (cookie_type, base_func_name, prototype))
+    create_link('%s_%s' % (base_func_name, ('checked' if void else 'unchecked')))
+    if not void:
+        f.write('.PP\n')
+        f.write('.SS Reply datastructure\n')
+        f.write('.nf\n')
+        f.write('.sp\n')
+        f.write('typedef %s %s {\n' % (self.reply.c_container, self.reply.c_type))
+        struct_fields = []
+        maxtypelen = 0
+
+        for field in self.reply.fields:
+            if not field.type.fixed_size() and not self.is_switch and not self.is_union:
+                continue
+            if field.wire:
+                struct_fields.append(field)
+
+        for field in struct_fields:
+            length = len(field.c_field_type)
+            # account for '*' pointer_spec
+            if not field.type.fixed_size():
+                length += 1
+            maxtypelen = max(maxtypelen, length)
+
+        def _c_complex_field(self, field, space=''):
+            if (field.type.fixed_size() or
+                # in case of switch with switch children, don't make the field a pointer
+                # necessary for unserialize to work
+                (self.is_switch and field.type.is_switch)):
+                spacing = ' ' * (maxtypelen - len(field.c_field_type))
+                f.write('%s    %s%s \\fI%s\\fP%s;\n' % (space, field.c_field_type, spacing, field.c_field_name, field.c_subscript))
+            else:
+                spacing = ' ' * (maxtypelen - (len(field.c_field_type) + 1))
+                f.write('ELSE %s = %s\n' % (field.c_field_type, field.c_field_name))
+                #_h('%s    %s%s *%s%s; /**<  */', space, field.c_field_type, spacing, field.c_field_name, field.c_subscript)
+
+        if not self.is_switch:
+            for field in struct_fields:
+                _c_complex_field(self, field)
+        else:
+            for b in self.bitcases:
+                space = ''
+                if b.type.has_name:
+                    space = '    '
+                for field in b.type.fields:
+                    _c_complex_field(self, field, space)
+                if b.type.has_name:
+                    print >> sys.stderr, 'ERROR: New unhandled documentation case'
+                    pass
+
+        f.write('} \\fB%s\\fP;\n' % self.reply.c_type)
+        f.write('.fi\n')
+
+        f.write('.SS Reply function\n')
+        f.write('.HP\n')
+        f.write(('%s *\\fB%s\\fP(xcb_connection_t\\ *\\fIconn\\fP, %s\\ '
+                 '\\fIcookie\\fP, xcb_generic_error_t\\ **\\fIe\\fP);\n') %
+                (self.c_reply_type, self.c_reply_name, self.c_cookie_type))
+        create_link('%s' % self.c_reply_name)
+
+        has_accessors = False
+        for field in self.reply.fields:
+            if field.type.is_list and not field.type.fixed_size():
+                has_accessors = True
+            elif field.prev_varsized_field is not None or not field.type.fixed_size():
+                has_accessors = True
+
+        if has_accessors:
+            f.write('.SS Reply accessors\n')
+
+        def _c_accessors_field(self, field):
+            '''
+            Declares the accessor functions for a non-list field that follows a variable-length field.
+            '''
+            c_type = self.c_type
+
+            # special case: switch
+            switch_obj = self if self.is_switch else None
+            if self.is_bitcase:
+                switch_obj = self.parents[-1]
+            if switch_obj is not None:
+                c_type = switch_obj.c_type
+
+            if field.type.is_simple:
+                f.write('%s %s (const %s *reply)\n' % (field.c_field_type, field.c_accessor_name, c_type))
+                create_link('%s' % field.c_accessor_name)
+            else:
+                f.write('%s *%s (const %s *reply)\n' % (field.c_field_type, field.c_accessor_name, c_type))
+                create_link('%s' % field.c_accessor_name)
+
+        def _c_accessors_list(self, field):
+            '''
+            Declares the accessor functions for a list field.
+            Declares a direct-accessor function only if the list members are fixed size.
+            Declares length and get-iterator functions always.
+            '''
+            list = field.type
+            c_type = self.reply.c_type
+
+            # special case: switch
+            # in case of switch, 2 params have to be supplied to certain accessor functions:
+            #   1. the anchestor object (request or reply)
+            #   2. the (anchestor) switch object
+            # the reason is that switch is either a child of a request/reply or nested in another switch,
+            # so whenever we need to access a length field, we might need to refer to some anchestor type
+            switch_obj = self if self.is_switch else None
+            if self.is_bitcase:
+                switch_obj = self.parents[-1]
+            if switch_obj is not None:
+                c_type = switch_obj.c_type
+
+            params = []
+            fields = {}
+            parents = self.parents if hasattr(self, 'parents') else [self]
+            # 'R': parents[0] is always the 'toplevel' container type
+            params.append(('const %s *\\fIreply\\fP' % parents[0].c_type, parents[0]))
+            fields.update(_c_helper_field_mapping(parents[0], [('R', '->', parents[0])], flat=True))
+            # auxiliary object for 'R' parameters
+            R_obj = parents[0]
+
+            if switch_obj is not None:
+                # now look where the fields are defined that are needed to evaluate
+                # the switch expr, and store the parent objects in accessor_params and
+                # the fields in switch_fields
+
+                # 'S': name for the 'toplevel' switch
+                toplevel_switch = parents[1]
+                params.append(('const %s *S' % toplevel_switch.c_type, toplevel_switch))
+                fields.update(_c_helper_field_mapping(toplevel_switch, [('S', '->', toplevel_switch)], flat=True))
+
+                # initialize prefix for everything "below" S
+                prefix_str = '/* %s */ S' % toplevel_switch.name[-1]
+                prefix = [(prefix_str, '->', toplevel_switch)]
+
+                # look for fields in the remaining containers
+                for p in parents[2:] + [self]:
+                    # the separator between parent and child is always '.' here,
+                    # because of nested switch statements
+                    if not p.is_bitcase or (p.is_bitcase and p.has_name):
+                        prefix.append((p.name[-1], '.', p))
+                    fields.update(_c_helper_field_mapping(p, prefix, flat=True))
+
+                # auxiliary object for 'S' parameter
+                S_obj = parents[1]
+
+            if list.member.fixed_size():
+                idx = 1 if switch_obj is not None else 0
+                f.write('.HP\n')
+                f.write('%s *\\fB%s\\fP(%s);\n' %
+                        (field.c_field_type, field.c_accessor_name, params[idx][0]))
+                create_link('%s' % field.c_accessor_name)
+
+            f.write('.HP\n')
+            f.write('int \\fB%s\\fP(const %s *\\fIreply\\fP);\n' %
+                    (field.c_length_name, c_type))
+            create_link('%s' % field.c_length_name)
+
+            if field.type.member.is_simple:
+                f.write('.HP\n')
+                f.write('xcb_generic_iterator_t \\fB%s\\fP(const %s *\\fIreply\\fP);\n' %
+                        (field.c_end_name, c_type))
+                create_link('%s' % field.c_end_name)
+            else:
+                f.write('.HP\n')
+                f.write('%s \\fB%s\\fP(const %s *\\fIreply\\fP);\n' %
+                        (field.c_iterator_type, field.c_iterator_name,
+                         c_type))
+                create_link('%s' % field.c_iterator_name)
+
+        for field in self.reply.fields:
+            if field.type.is_list and not field.type.fixed_size():
+                _c_accessors_list(self, field)
+            elif field.prev_varsized_field is not None or not field.type.fixed_size():
+                _c_accessors_field(self, field)
+
+
+    f.write('.br\n')
+    # Re-enable hyphenation and adjusting to both sides
+    f.write('.hy 1\n')
+
+    # argument reference
+    f.write('.SH REQUEST ARGUMENTS\n')
+    f.write('.IP \\fI%s\\fP 1i\n' % 'conn')
+    f.write('The XCB connection to X11.\n')
+    for field in param_fields:
+        f.write('.IP \\fI%s\\fP 1i\n' % (field.c_field_name))
+        printed_enum = False
+        # XXX: hard-coded until we fix xproto.xml
+        if base_func_name == 'xcb_change_gc' and field.c_field_name == 'value_mask':
+            field.enum = 'GC'
+        elif base_func_name == 'xcb_change_window_attributes' and field.c_field_name == 'value_mask':
+            field.enum = 'CW'
+        elif base_func_name == 'xcb_create_window' and field.c_field_name == 'value_mask':
+            field.enum = 'CW'
+        if hasattr(field, "enum") and field.enum:
+            # XXX: why the 'xcb' prefix?
+            key = ('xcb', field.enum)
+            if key in enums:
+                f.write('One of the following values:\n')
+                f.write('.RS 1i\n')
+                enum = enums[key]
+                count = len(enum.values)
+                for (enam, eval) in enum.values:
+                    count = count - 1
+                    f.write('.IP \\fI%s\\fP 1i\n' % (_n(key + (enam,)).upper()))
+                    if hasattr(enum, "doc") and enum.doc and enam in enum.doc.fields:
+                        desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', enum.doc.fields[enam])
+                        f.write('%s\n' % desc)
+                    else:
+                        f.write('TODO: NOT YET DOCUMENTED.\n')
+                f.write('.RE\n')
+                f.write('.RS 1i\n')
+                printed_enum = True
+
+        if hasattr(self, "doc") and self.doc and field.field_name in self.doc.fields:
+            desc = self.doc.fields[field.field_name]
+            desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+            if printed_enum:
+                f.write('\n')
+            f.write('%s\n' % desc)
+        else:
+            f.write('TODO: NOT YET DOCUMENTED.\n')
+        if printed_enum:
+            f.write('.RE\n')
+
+    # Reply reference
+    if not void:
+        f.write('.SH REPLY FIELDS\n')
+        # These fields are present in every reply:
+        f.write('.IP \\fI%s\\fP 1i\n' % 'response_type')
+        f.write(('The type of this reply, in this case \\fI%s\\fP. This field '
+                 'is also present in the \\fIxcb_generic_reply_t\\fP and can '
+                 'be used to tell replies apart from each other.\n') %
+                 _n(self.reply.name).upper())
+        f.write('.IP \\fI%s\\fP 1i\n' % 'sequence')
+        f.write('The sequence number of the last request processed by the X11 server.\n')
+        f.write('.IP \\fI%s\\fP 1i\n' % 'length')
+        f.write('The length of the reply, in words (a word is 4 bytes).\n')
+        for field in self.reply.fields:
+            if (field.c_field_name in frozenset(['response_type', 'sequence', 'length']) or
+                field.c_field_name.startswith('pad')):
+                continue
+
+            if field.type.is_list and not field.type.fixed_size():
+                continue
+            elif field.prev_varsized_field is not None or not field.type.fixed_size():
+                continue
+            f.write('.IP \\fI%s\\fP 1i\n' % (field.c_field_name))
+            printed_enum = False
+            if hasattr(field, "enum") and field.enum:
+                # XXX: why the 'xcb' prefix?
+                key = ('xcb', field.enum)
+                if key in enums:
+                    f.write('One of the following values:\n')
+                    f.write('.RS 1i\n')
+                    enum = enums[key]
+                    count = len(enum.values)
+                    for (enam, eval) in enum.values:
+                        count = count - 1
+                        f.write('.IP \\fI%s\\fP 1i\n' % (_n(key + (enam,)).upper()))
+                        if enum.doc and enam in enum.doc.fields:
+                            desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', enum.doc.fields[enam])
+                            f.write('%s\n' % desc)
+                        else:
+                            f.write('TODO: NOT YET DOCUMENTED.\n')
+                    f.write('.RE\n')
+                    f.write('.RS 1i\n')
+                    printed_enum = True
+
+            if hasattr(self.reply, "doc") and self.reply.doc and field.field_name in self.reply.doc.fields:
+                desc = self.reply.doc.fields[field.field_name]
+                desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+                if printed_enum:
+                    f.write('\n')
+                f.write('%s\n' % desc)
+            else:
+                f.write('TODO: NOT YET DOCUMENTED.\n')
+            if printed_enum:
+                f.write('.RE\n')
+
+
+
+    # text description
+    f.write('.SH DESCRIPTION\n')
+    if hasattr(self, "doc") and self.doc and self.doc.description:
+        desc = self.doc.description
+        desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+        lines = desc.split('\n')
+        f.write('\n'.join(lines) + '\n')
+
+    f.write('.SH RETURN VALUE\n')
+    if void:
+        f.write(('Returns an \\fIxcb_void_cookie_t\\fP. Errors (if any) '
+                 'have to be handled in the event loop.\n\nIf you want to '
+                 'handle errors directly with \\fIxcb_request_check\\fP '
+                 'instead, use \\fI%s_checked\\fP. See '
+                 '\\fBxcb-requests(3)\\fP for details.\n') % (base_func_name))
+    else:
+        f.write(('Returns an \\fI%s\\fP. Errors have to be handled when '
+                 'calling the reply function \\fI%s\\fP.\n\nIf you want to '
+                 'handle errors in the event loop instead, use '
+                 '\\fI%s_unchecked\\fP. See \\fBxcb-requests(3)\\fP for '
+                 'details.\n') %
+                (cookie_type, self.c_reply_name, base_func_name))
+    f.write('.SH ERRORS\n')
+    if hasattr(self, "doc") and self.doc:
+        for errtype, errtext in self.doc.errors.iteritems():
+            f.write('.IP \\fI%s\\fP 1i\n' % (_t(('xcb', errtype, 'error'))))
+            errtext = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', errtext)
+            f.write('%s\n' % (errtext))
+    if not hasattr(self, "doc") or not self.doc or len(self.doc.errors) == 0:
+        f.write('This request does never generate any errors.\n')
+    if hasattr(self, "doc") and self.doc and self.doc.example:
+        f.write('.SH EXAMPLE\n')
+        f.write('.nf\n')
+        f.write('.sp\n')
+        lines = self.doc.example.split('\n')
+        f.write('\n'.join(lines) + '\n')
+        f.write('.fi\n')
+    f.write('.SH SEE ALSO\n')
+    if hasattr(self, "doc") and self.doc:
+        see = ['.BR %s (3)' % 'xcb-requests']
+        if self.doc.example:
+            see.append('.BR %s (3)' % 'xcb-examples')
+        for seename, seetype in self.doc.see.iteritems():
+            if seetype == 'program':
+                see.append('.BR %s (1)' % seename)
+            elif seetype == 'event':
+                see.append('.BR %s (3)' % _t(('xcb', seename, 'event')))
+            elif seetype == 'request':
+                see.append('.BR %s (3)' % _n(('xcb', seename)))
+            elif seetype == 'function':
+                see.append('.BR %s (3)' % seename)
+            else:
+                see.append('TODO: %s (type %s)' % (seename, seetype))
+        f.write(',\n'.join(see) + '\n')
+    f.write('.SH AUTHOR\n')
+    f.write('Generated from %s.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.\n' % _ns.header)
+    f.close()
+
+def _man_event(self, name):
+    if manpaths:
+        sys.stdout.write('man/%s.3 ' % self.c_type)
+    # Our CWD is src/, so this will end up in src/man/
+    f = open('man/%s.3' % self.c_type, 'w')
+    f.write('.TH %s 3  %s "XCB" "XCB Events"\n' % (self.c_type, today))
+    # Left-adjust instead of adjusting to both sides
+    f.write('.ad l\n')
+    f.write('.SH NAME\n')
+    brief = self.doc.brief if hasattr(self, "doc") and self.doc else ''
+    f.write('%s \\- %s\n' % (self.c_type, brief))
+    f.write('.SH SYNOPSIS\n')
+    # Don't split words (hyphenate)
+    f.write('.hy 0\n')
+    f.write('.B #include <xcb/%s.h>\n' % _ns.header)
+
+    f.write('.PP\n')
+    f.write('.SS Event datastructure\n')
+    f.write('.nf\n')
+    f.write('.sp\n')
+    f.write('typedef %s %s {\n' % (self.c_container, self.c_type))
+    struct_fields = []
+    maxtypelen = 0
+
+    for field in self.fields:
+        if not field.type.fixed_size() and not self.is_switch and not self.is_union:
+            continue
+        if field.wire:
+            struct_fields.append(field)
+
+    for field in struct_fields:
+        length = len(field.c_field_type)
+        # account for '*' pointer_spec
+        if not field.type.fixed_size():
+            length += 1
+        maxtypelen = max(maxtypelen, length)
+
+    def _c_complex_field(self, field, space=''):
+        if (field.type.fixed_size() or
+            # in case of switch with switch children, don't make the field a pointer
+            # necessary for unserialize to work
+            (self.is_switch and field.type.is_switch)):
+            spacing = ' ' * (maxtypelen - len(field.c_field_type))
+            f.write('%s    %s%s \\fI%s\\fP%s;\n' % (space, field.c_field_type, spacing, field.c_field_name, field.c_subscript))
+        else:
+            print >> sys.stderr, 'ERROR: New unhandled documentation case'
+
+    if not self.is_switch:
+        for field in struct_fields:
+            _c_complex_field(self, field)
+    else:
+        for b in self.bitcases:
+            space = ''
+            if b.type.has_name:
+                space = '    '
+            for field in b.type.fields:
+                _c_complex_field(self, field, space)
+            if b.type.has_name:
+                print >> sys.stderr, 'ERROR: New unhandled documentation case'
+                pass
+
+    f.write('} \\fB%s\\fP;\n' % self.c_type)
+    f.write('.fi\n')
+
+
+    f.write('.br\n')
+    # Re-enable hyphenation and adjusting to both sides
+    f.write('.hy 1\n')
+
+    # argument reference
+    f.write('.SH EVENT FIELDS\n')
+    f.write('.IP \\fI%s\\fP 1i\n' % 'response_type')
+    f.write(('The type of this event, in this case \\fI%s\\fP. This field is '
+             'also present in the \\fIxcb_generic_event_t\\fP and can be used '
+             'to tell events apart from each other.\n') % _n(name).upper())
+    f.write('.IP \\fI%s\\fP 1i\n' % 'sequence')
+    f.write('The sequence number of the last request processed by the X11 server.\n')
+
+    if not self.is_switch:
+        for field in struct_fields:
+            # Skip the fields which every event has, we already documented
+            # them (see above).
+            if field.c_field_name in ('response_type', 'sequence'):
+                continue
+            if isinstance(field.type, PadType):
+                continue
+            f.write('.IP \\fI%s\\fP 1i\n' % (field.c_field_name))
+            if hasattr(self, "doc") and self.doc and field.field_name in self.doc.fields:
+                desc = self.doc.fields[field.field_name]
+                desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+                f.write('%s\n' % desc)
+            else:
+                f.write('NOT YET DOCUMENTED.\n')
+
+    # text description
+    f.write('.SH DESCRIPTION\n')
+    if hasattr(self, "doc") and self.doc and self.doc.description:
+        desc = self.doc.description
+        desc = re.sub(r'`([^`]+)`', r'\\fI\1\\fP', desc)
+        lines = desc.split('\n')
+        f.write('\n'.join(lines) + '\n')
+
+    if hasattr(self, "doc") and self.doc and self.doc.example:
+        f.write('.SH EXAMPLE\n')
+        f.write('.nf\n')
+        f.write('.sp\n')
+        lines = self.doc.example.split('\n')
+        f.write('\n'.join(lines) + '\n')
+        f.write('.fi\n')
+    f.write('.SH SEE ALSO\n')
+    if hasattr(self, "doc") and self.doc:
+        see = ['.BR %s (3)' % 'xcb_generic_event_t']
+        if self.doc.example:
+            see.append('.BR %s (3)' % 'xcb-examples')
+        for seename, seetype in self.doc.see.iteritems():
+            if seetype == 'program':
+                see.append('.BR %s (1)' % seename)
+            elif seetype == 'event':
+                see.append('.BR %s (3)' % _t(('xcb', seename, 'event')))
+            elif seetype == 'request':
+                see.append('.BR %s (3)' % _n(('xcb', seename)))
+            elif seetype == 'function':
+                see.append('.BR %s (3)' % seename)
+            else:
+                see.append('TODO: %s (type %s)' % (seename, seetype))
+        f.write(',\n'.join(see) + '\n')
+    f.write('.SH AUTHOR\n')
+    f.write('Generated from %s.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.\n' % _ns.header)
+    f.close()
+
+
 def c_request(self, name):
     '''
     Exported function that handles request declarations.
@@ -2239,6 +2815,10 @@ def c_request(self, name):
             _c_request_helper(self, name, 'xcb_void_cookie_t', True, False, True)
             _c_request_helper(self, name, 'xcb_void_cookie_t', True, True, True)
 
+    # We generate the manpage afterwards because _c_type_setup has been called.
+    # TODO: what about aux helpers?
+    cookie_type = self.c_cookie_type if self.reply else 'xcb_void_cookie_t'
+    _man_request(self, name, cookie_type, not self.reply, False)
 
 def c_event(self, name):
     '''
@@ -2257,6 +2837,8 @@ def c_event(self, name):
         _h('')
         _h('typedef %s %s;', _t(self.name + ('event',)), _t(name + ('event',)))
 
+    _man_event(self, name)
+
 def c_error(self, name):
     '''
     Exported function that handles error declarations.
@@ -2293,7 +2875,7 @@ output = {'open'    : c_open,
 
 # Check for the argument that specifies path to the xcbgen python package.
 try:
-    opts, args = getopt.getopt(sys.argv[1:], 'p:')
+    opts, args = getopt.getopt(sys.argv[1:], 'p:m')
 except getopt.GetoptError as err:
     print(err)
     print('Usage: c_client.py [-p path] file.xml')
@@ -2302,10 +2884,14 @@ except getopt.GetoptError as err:
 for (opt, arg) in opts:
     if opt == '-p':
         sys.path.insert(1, arg)
+    elif opt == '-m':
+        manpaths = True
+        sys.stdout.write('man_MANS = ')
 
 # Import the module class
 try:
     from xcbgen.state import Module
+    from xcbgen.xtypes import *
 except ImportError:
     print('''
 Failed to load the xcbgen Python package!
@@ -2316,6 +2902,12 @@ Refer to the README file in xcb/proto for more info.
 ''')
     raise
 
+# Ensure the man subdirectory exists
+if not os.path.exists('man'):
+    os.mkdir('man')
+
+today = time.strftime('%Y-%m-%d', time.gmtime(os.path.getmtime(args[0])))
+
 # Parse the xml header
 module = Module(args[0], output)
 
diff --git a/libxcb/src/man/xcb-examples.3 b/libxcb/src/man/xcb-examples.3
new file mode 100644
index 000000000..291af37d0
--- /dev/null
+++ b/libxcb/src/man/xcb-examples.3
@@ -0,0 +1,59 @@
+.TH xcb-examples 3 2011-12-11 "XCB" "XCB examples"
+.ad l
+.SH NAME
+xcb-examples \- manpage examples
+.SH DESCRIPTION
+Many of the XCB manpages contain example code. These examples intend to explain
+how to use one particular part of XCB. They almost never represent a standalone
+(or even useful) program - X11 programs are relatively involved and
+thus beyond the scope of a manpage example.
+
+.SH ENVIRONMENT
+
+Every example assumes you have an \fIxcb_connection\fP and possibly other
+variables at hand. For illustrating how \fIxcb_get_property\fP works, you need
+the window of which you want to get the property, for example. To make it clear
+that these variables are your responsibility, these examples consist of a
+single function which takes the necessary variables as parameters.
+
+.SH FLUSHING
+
+Flushing means calling \fIxcb_flush\fP to clear the XCB-internal write buffer
+and send all pending requests to the X11 server. You don't explicitly need to
+flush before using a reply function (like \fIxcb_query_pointer_reply\fP), but
+you do need to flush before entering the event loop of your program.
+
+There are only two cases when XCB flushes by itself. The first case is when
+its write buffer becomes full, the second case is when you are asking for
+the reply of a request which wasn't flushed out yet (like
+\fIxcb_query_pointer_reply\fP). This last point also includes
+xcb_request_check(). Please note that waiting for an event does \fBNOT\fP
+flush.
+
+Examples generally include the \fIxcb_flush\fP call where appropriate (for
+example after setting a property). Therefore, including these functions and
+calling them in your application should just work. However, you might get
+better results when flushing outside of the function, depending on the
+architecture of your program.
+
+.SH COMPILATION
+
+If an example does not compile (without warnings) when using \fI-std=c99\fP,
+that is considered a documentation bug. Similarly, not handling errors or
+leaking memory is also considered a documentation bug. Please inform us about
+it on xcb@lists.freedesktop.org.
+
+.SH CODING STYLE
+
+Every example uses 4 spaces for indention.
+
+Comments are in asterisks, like /* this */.
+
+No line is longer than 80 characters (including indention).
+
+.SH SEE ALSO
+.BR xcb_connect (3),
+.BR xcb_get_property (3),
+.BR xcb_flush (3)
+.SH AUTHOR
+Michael Stapelberg <michael+xcb at stapelberg dot de>
diff --git a/libxcb/src/man/xcb-requests.3 b/libxcb/src/man/xcb-requests.3
new file mode 100644
index 000000000..278bcff13
--- /dev/null
+++ b/libxcb/src/man/xcb-requests.3
@@ -0,0 +1,165 @@
+.TH xcb-requests 3 2011-12-11 "XCB" "XCB examples"
+.ad l
+.SH NAME
+xcb-requests \- about request manpages
+.SH DESCRIPTION
+Every request in X11, like \fIMapWindow\fP, corresponds to a number of
+functions and data structures in XCB. For \fIMapWindow\fP, XCB provides the
+function \fIxcb_map_window\fP, which fills the \fIxcb_map_window_request_t\fP
+data structure and writes that to the X11 connection. Since the \fIMapWindow\fP
+request does not have a reply, this is the most simple case.
+
+.SH REPLIES
+
+Many requests have replies. For each reply, XCB provides at least a
+corresponding data structure and a function to return a pointer to a filled
+data structure. Let's take the \fIInternAtom\fP request as an example: XCB
+provides the \fIxcb_intern_atom_reply_t\fP data structure and
+\fIxcb_intern_atom_reply\fP function. For replies which are more complex (for
+example lists, such as in \fIxcb_list_fonts\fP), accessor functions are
+provided.
+
+.SH COOKIES
+
+XCB returns a cookie for each request you send. This is an XCB-specific data
+structure containing the sequence number with which the request was sent to the
+X11 server. To get any reply, you have to provide that cookie (so that XCB
+knows which of the waiting replies you want). Here is an example to illustrate
+the use of cookies:
+
+.nf
+.sp
+void my_example(xcb_connection *conn) {
+    xcb_intern_atom_cookie_t cookie;
+    xcb_intern_atom_reply_t *reply;
+
+    cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
+    /* ... do other work here if possible ... */
+    if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) {
+        printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+    }
+    free(reply);
+}
+.fi
+
+.SH CHECKED VS. UNCHECKED
+
+The checked and unchecked suffixes for functions determine which kind of error
+handling is used for this specific request.
+
+For requests which have no reply (for example \fIxcb_map_window\fP), errors
+will be delivered to the event loop (you will receive an X11 event of type 0
+when calling \fIxcb_poll_for_event\fP).
+If you want to explicitly check for errors in a blocking fashion, call the
+_checked version of the function (for example \fIxcb_map_window_checked\fP) and
+use \fIxcb_request_check\fP.
+
+For requests which have a reply (for example \fIxcb_intern_atom\fP), errors
+will be checked when calling the reply function. To get errors in the event
+loop instead, use the _unchecked version of the function (for example
+\fIxcb_intern_atom_unchecked\fP).
+
+Here is an example which illustrates the four different ways of handling errors:
+
+.nf
+.sp
+/*
+ * Request without a reply, handling errors in the event loop (default)
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+    /* This is a request without a reply. Errors will be delivered to the event
+     * loop. Getting an error to xcb_map_window most likely is a bug in our
+     * program, so we don't need to check for that in a blocking way. */
+    xcb_map_window(conn, window);
+
+    /* ... of course your event loop would not be in the same function ... */
+    while ((event = xcb_wait_for_event(conn)) != NULL) {
+        if (event->response_type == 0) {
+            fprintf("Received X11 error %d\\n", error->error_code);
+            free(event);
+            continue;
+        }
+
+        /* ... handle a normal event ... */
+    }
+}
+
+/*
+ * Request without a reply, handling errors directly
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) {
+    /* A reparenting window manager wants to know whether a new window was
+     * successfully reparented. If not (because the window got destroyed
+     * already, for example), it does not make sense to map an empty window
+     * decoration at all, so we need to know this right now. */
+    xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window,
+                                                           deco, 0, 0);
+    xcb_generic_error_t *error;
+    if ((error = xcb_request_check(conn, cookie))) {
+        fprintf(stderr, "Could not reparent the window\\n");
+        free(error);
+        return;
+    }
+
+    /* ... do window manager stuff here ... */
+}
+
+/*
+ * Request with a reply, handling errors directly (default)
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+    xcb_intern_atom_cookie_t cookie;
+    xcb_intern_atom_reply_t *reply;
+    xcb_generic_error_t *error;
+
+    cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
+    /* ... do other work here if possible ... */
+    if ((reply = xcb_intern_atom_reply(c, cookie, &error))) {
+        printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+        free(reply);
+    } else {
+        fprintf(stderr, "X11 Error %d\\n", error->error_code);
+        free(error);
+    }
+}
+
+/*
+ * Request with a reply, handling errors in the event loop
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+    xcb_intern_atom_cookie_t cookie;
+    xcb_intern_atom_reply_t *reply;
+
+    cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"),
+                                       "_NET_WM_NAME");
+    /* ... do other work here if possible ... */
+    if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
+        printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+        free(reply);
+    }
+
+    /* ... of course your event loop would not be in the same function ... */
+    while ((event = xcb_wait_for_event(conn)) != NULL) {
+        if (event->response_type == 0) {
+            fprintf("Received X11 error %d\\n", error->error_code);
+            free(event);
+            continue;
+        }
+
+        /* ... handle a normal event ... */
+    }
+}
+.fi
+
+.SH SEE ALSO
+.BR xcb_map_window (3),
+.BR xcb_intern_atom (3),
+.BR xcb_list_fonts (3),
+.BR xcb_poll_for_event (3),
+.BR xcb_request_check (3)
+.SH AUTHOR
+Michael Stapelberg <michael+xcb at stapelberg dot de>
diff --git a/libxcb/xcb-proto/doc/xml-xcb.txt b/libxcb/xcb-proto/doc/xml-xcb.txt
index 3c6a15519..705772736 100644
--- a/libxcb/xcb-proto/doc/xml-xcb.txt
+++ b/libxcb/xcb-proto/doc/xml-xcb.txt
@@ -284,3 +284,38 @@ Expressions
 
   This element represents the number of bits set in the expression.
 
+Documentation
+-------------
+
+  Documentation for each request, reply or event is stored in the appropriate
+  element using a <doc> element. The <doc> element can contain the following
+  elements:
+
+<brief>brief description</brief>
+
+  A short description of the request, reply or event. For example "makes a
+  window visible" for MapWindow. This will end up in the manpage NAME section
+  and in the doxygen @brief description.
+
+<description><![CDATA[longer description]]></description>
+
+  The full description. Use `` to highlight words, such as "Draws
+  `points_len`-1 lines between each pair of points…"
+
+<example><![CDATA[example code]]</description>
+
+  Example C code illustrating the usage of the particular request, reply or
+  event.
+
+<field name="name">field description</field>
+
+  The full description for the specified field. Depending on the context, this
+  is either a request parameter or a reply/event datastructure field.
+
+<error type="type">error description</field>
+
+  The full description for an error which can occur due to this request.
+
+<see type="request" name="name" />
+
+  A reference to another relevant program, function, request or event.
diff --git a/libxcb/xcb-proto/src/xcb.xsd b/libxcb/xcb-proto/src/xcb.xsd
index 89e27846f..cfa90c9c2 100644
--- a/libxcb/xcb-proto/src/xcb.xsd
+++ b/libxcb/xcb-proto/src/xcb.xsd
@@ -1,314 +1,375 @@
-<?xml version="1.0" encoding="utf-8"?>

-<!--

-Copyright (C) 2004 Josh Triplett.  All Rights Reserved.

-

-Permission is hereby granted, free of charge, to any person obtaining a copy

-of this software and associated documentation files (the "Software"), to deal

-in the Software without restriction, including without limitation the rights

-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

-copies of the Software, and to permit persons to whom the Software is

-furnished to do so, subject to the following conditions:

-

-The above copyright notice and this permission notice shall be included in all

-copies or substantial portions of the Software.

-

-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

-AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

-ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

-

-Except as contained in this notice, the names of the authors or their

-institutions shall not be used in advertising or otherwise to promote the

-sale, use or other dealings in this Software without prior written

-authorization from the authors.

--->

-<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

-

-  <!-- The root element -->

-  <xsd:element name="xcb">

-    <xsd:complexType>

-      <xsd:group ref="macro" minOccurs="0" maxOccurs="unbounded" />

-      <xsd:attribute name="header" type="xsd:string" use="required" />

-      <xsd:attribute name="extension-xname" type="xsd:string" use="optional" />

-      <xsd:attribute name="extension-name"  type="xsd:string" use="optional" />

-      <xsd:attribute name="extension-multiword" type="xsd:boolean" use="optional" default="false" />

-      <xsd:attribute name="major-version"   type="xsd:integer" use="optional" />

-      <xsd:attribute name="minor-version"   type="xsd:integer" use="optional" />

-    </xsd:complexType>

-  </xsd:element>

-

-  <!-- Padding -->

-  <xsd:element name="pad">

-    <xsd:complexType>

-      <xsd:attribute name="bytes" type="xsd:integer" use="required" />

-    </xsd:complexType>

-  </xsd:element>

-

-  <!-- Type for fields or parameters with attributes "name" and "type" -->

-  <xsd:complexType name="var">

-    <xsd:attribute name="name" type="xsd:string" use="required" />

-    <xsd:attribute name="type" type="xsd:string" use="required" />

-    <xsd:attribute name="enum" type="xsd:string" use="optional" />

-    <xsd:attribute name="altenum" type="xsd:string" use="optional" />

-    <xsd:attribute name="mask" type="xsd:string" use="optional" />

-  </xsd:complexType>

-

-  <!-- case expression -->

-  <xsd:complexType name="caseexpr">

-    <xsd:sequence>

-      <!-- case expression: -->

-      <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />

-      <!-- match -->

-      <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />

-      <xsd:choice>

-        <xsd:element ref="switch" minOccurs="0" maxOccurs="unbounded" />

-      </xsd:choice>

-    </xsd:sequence>

-    <xsd:attribute name="name" type="xsd:string" use="optional" />

-  </xsd:complexType>

-

-  <!-- switch expression -->

-  <xsd:complexType name="switchexpr">

-    <xsd:sequence>

-      <!-- switch(expression) -->

-      <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />

-      <xsd:choice>

-        <!-- bitcase expression - bit test -->

-        <xsd:element name="bitcase" type="caseexpr" minOccurs="1" maxOccurs="unbounded" />

-      </xsd:choice>

-      <!-- default: -->

-      <xsd:group ref="fields" minOccurs="0" maxOccurs="1" />

-    </xsd:sequence>

-    <xsd:attribute name="name" type="xsd:string" use="required" />

-  </xsd:complexType>

-

-  <xsd:element name="switch" type="switchexpr" />

-

-  <!-- field replaces FIELD, PARAM, and REPLY. -->

-  <xsd:element name="field" type="var" />

-

-  <!-- list replaces ARRAYFIELD, LISTPARAM, and ARRAYREPLY.  The name and type

-       are specified as attributes.  The content is an expression giving the

-       length. -->

-  <xsd:element name="list">

-    <xsd:complexType>

-      <xsd:complexContent>

-        <xsd:extension base="var">

-          <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />

-        </xsd:extension>

-      </xsd:complexContent>

-    </xsd:complexType>

-  </xsd:element>

-

-  <!-- Expressions -->

-  <xsd:group name="expression">

-    <xsd:choice>

-      <xsd:element name="op">

-        <xsd:complexType>

-          <xsd:sequence>

-            <xsd:group ref="expression" />

-            <xsd:group ref="expression" />

-          </xsd:sequence>

-          <xsd:attribute name="op" use="required">

-            <xsd:simpleType>

-              <xsd:restriction base="xsd:string">

-                <xsd:pattern value="\+|-|\*|/|&amp;|&lt;&lt;" />

-              </xsd:restriction>

-            </xsd:simpleType>

-          </xsd:attribute>

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="unop">

-         <xsd:complexType>

-            <xsd:sequence>

-              <xsd:group ref="expression" />

-            </xsd:sequence>

-            <xsd:attribute name="op" use="required">

-              <xsd:simpleType>

-                <xsd:restriction base="xsd:string">

-                  <xsd:pattern value="~" />

-                </xsd:restriction>

-              </xsd:simpleType>

-            </xsd:attribute>

-         </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="fieldref" type="xsd:string" />

-      <xsd:element name="enumref">

-        <xsd:complexType>

-          <xsd:simpleContent>

-            <xsd:extension base="xsd:string">

-              <xsd:attribute name="ref" use="required" type="xsd:string" />

-            </xsd:extension>

-          </xsd:simpleContent>

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="popcount">

-        <xsd:complexType>

-          <xsd:group ref="expression" />

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="sumof">

-        <xsd:complexType>

-          <xsd:attribute name="ref" use="required" type="xsd:string" />

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="value" type="dec-or-hex-integer" />

-      <xsd:element name="bit" type="xsd:integer" />

-    </xsd:choice>

-  </xsd:group>

-  

-  <!-- Fields in requests that are calculated from other information, not

-       supplied by the caller. -->

-  <xsd:element name="exprfield" >

-    <xsd:complexType>

-      <xsd:complexContent>

-        <xsd:extension base="var">

-          <xsd:group ref="expression" />

-        </xsd:extension>

-      </xsd:complexContent>

-    </xsd:complexType>

-  </xsd:element>

-

-  <!-- BITMASK/LISTofVALUE parameter pairs. -->

-  <xsd:element name="valueparam">

-    <xsd:complexType>

-      <xsd:attribute name="value-mask-type" type="xsd:string" use="required" />

-      <xsd:attribute name="value-mask-name" type="xsd:string" use="required" />

-      <xsd:attribute name="value-list-name" type="xsd:string" use="required" />

-    </xsd:complexType>

-  </xsd:element>

-

-  <xsd:group name="fields">

-    <xsd:choice>

-      <xsd:element ref="pad" />

-      <xsd:element ref="field" />

-      <xsd:element ref="list" />

-    </xsd:choice>

-  </xsd:group>

-

-  <!-- Type for a structure -->

-  <xsd:complexType name="struct">

-    <xsd:sequence>

-      <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />

-      <xsd:choice minOccurs="0" maxOccurs="1">

-        <xsd:element ref="switch" />

-      </xsd:choice>

-    </xsd:sequence>

-    <xsd:attribute name="name" type="xsd:string" use="required" />

-  </xsd:complexType>

-

-  <!-- Type for a packet structure -->

-  <xsd:complexType name="packet-struct">

-    <xsd:group ref="fields" minOccurs="0" maxOccurs="unbounded" />

-    <xsd:attribute name="name" type="xsd:string" use="required" />

-    <xsd:attribute name="number" type="xsd:integer" use="required" />

-  </xsd:complexType>

-

-  <!-- Type for a packet structure copy -->

-  <xsd:complexType name="packet-struct-copy">

-    <xsd:attribute name="name" type="xsd:string" use="required" />

-    <xsd:attribute name="number" type="xsd:integer" use="required" />

-    <xsd:attribute name="ref" type="xsd:string" use="required" />

-  </xsd:complexType>

-

-  <!-- Type for hex integers -->

-  <xsd:simpleType name="hex-integer">

-    <xsd:restriction base="xsd:string">

-      <xsd:pattern value="0x[0-9a-fA-F]+" />

-    </xsd:restriction>

-  </xsd:simpleType>

-

-  <!-- Type for integers in either decimal or hex -->

-  <xsd:simpleType name="dec-or-hex-integer">

-    <xsd:union memberTypes="xsd:integer hex-integer" />

-  </xsd:simpleType>

-

-  <xsd:group name="macro">

-    <xsd:choice>

-      <xsd:element name="request">

-        <xsd:complexType>

-          <xsd:sequence>

-            <xsd:choice minOccurs="0" maxOccurs="unbounded">

-              <xsd:group ref="fields" />

-              <xsd:element ref="exprfield" />

-              <xsd:element ref="valueparam" />

-            </xsd:choice>

-            <xsd:choice minOccurs="0" maxOccurs="1">

-              <xsd:element ref="switch" />

-            </xsd:choice>

-            <xsd:element name="reply" minOccurs="0" maxOccurs="1">

-              <xsd:complexType>

-                <xsd:sequence>

-                  <xsd:choice minOccurs="1" maxOccurs="unbounded">

-                    <xsd:group ref="fields" />

-                    <xsd:element ref="valueparam" />

-                  </xsd:choice>

-                  <xsd:choice minOccurs="0" maxOccurs="1">

-                    <xsd:element ref="switch" />

-                  </xsd:choice>

-                </xsd:sequence>

-              </xsd:complexType>

-            </xsd:element>

-          </xsd:sequence>

-          <xsd:attribute name="name" type="xsd:string" use="required" />

-          <xsd:attribute name="opcode" type="xsd:integer" use="required" />

-          <xsd:attribute name="combine-adjacent" type="xsd:boolean"

-                         use="optional"/>

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="event">

-        <xsd:complexType>

-          <xsd:complexContent>

-            <xsd:extension base="packet-struct">

-              <xsd:attribute name="no-sequence-number" type="xsd:boolean"

-                             use="optional" />

-            </xsd:extension>

-          </xsd:complexContent>

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="eventcopy" type="packet-struct-copy" />

-      <xsd:element name="error" type="packet-struct" />

-      <xsd:element name="errorcopy" type="packet-struct-copy" />

-      <xsd:element name="struct" type="struct" />

-      <xsd:element name="union" type="struct" />

-      <xsd:element name="xidtype">

-        <xsd:complexType>

-          <xsd:attribute name="name" type="xsd:string" use="required" />

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="xidunion">

-        <xsd:complexType>

-          <xsd:sequence>

-            <xsd:element name="type" type="xsd:string"

-                         minOccurs="1" maxOccurs="unbounded" />

-          </xsd:sequence>

-          <xsd:attribute name="name" type="xsd:string" use="required" />

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="enum">

-        <xsd:complexType>

-          <xsd:sequence minOccurs="1" maxOccurs="unbounded">

-            <xsd:element name="item">

-              <xsd:complexType>

-                <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />

-                <xsd:attribute name="name" type="xsd:string" use="required" />

-              </xsd:complexType>

-            </xsd:element>

-          </xsd:sequence>

-          <xsd:attribute name="name" type="xsd:string" use="required" />

-        </xsd:complexType>

-      </xsd:element>

-      <xsd:element name="typedef">

-        <xsd:complexType>

-          <xsd:attribute name="oldname" type="xsd:string" use="required" />

-          <xsd:attribute name="newname" type="xsd:string" use="required" />

-        </xsd:complexType>

-      </xsd:element>

-      <!-- The import element allows a protocol description to reference the

-           declarations of another protocol description. -->

-      <xsd:element name="import" type="xsd:string" />

-    </xsd:choice>

-  </xsd:group>

-</xsd:schema>

+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Copyright (C) 2004 Josh Triplett.  All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the names of the authors or their
+institutions shall not be used in advertising or otherwise to promote the
+sale, use or other dealings in this Software without prior written
+authorization from the authors.
+-->
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
+  <!-- The root element -->
+  <xsd:element name="xcb">
+    <xsd:complexType>
+      <xsd:group ref="macro" minOccurs="0" maxOccurs="unbounded" />
+      <xsd:attribute name="header" type="xsd:string" use="required" />
+      <xsd:attribute name="extension-xname" type="xsd:string" use="optional" />
+      <xsd:attribute name="extension-name"  type="xsd:string" use="optional" />
+      <xsd:attribute name="extension-multiword" type="xsd:boolean" use="optional" default="false" />
+      <xsd:attribute name="major-version"   type="xsd:integer" use="optional" />
+      <xsd:attribute name="minor-version"   type="xsd:integer" use="optional" />
+    </xsd:complexType>
+  </xsd:element>
+
+  <!-- Padding -->
+  <xsd:element name="pad">
+    <xsd:complexType>
+      <xsd:attribute name="bytes" type="xsd:integer" use="required" />
+    </xsd:complexType>
+  </xsd:element>
+
+  <!-- Type for fields or parameters with attributes "name" and "type" -->
+  <xsd:complexType name="var">
+    <xsd:attribute name="name" type="xsd:string" use="required" />
+    <xsd:attribute name="type" type="xsd:string" use="required" />
+    <xsd:attribute name="enum" type="xsd:string" use="optional" />
+    <xsd:attribute name="altenum" type="xsd:string" use="optional" />
+    <xsd:attribute name="mask" type="xsd:string" use="optional" />
+  </xsd:complexType>
+
+  <!-- case expression -->
+  <xsd:complexType name="caseexpr">
+    <xsd:sequence>
+      <!-- case expression: -->
+      <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />
+      <!-- match -->
+      <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />
+      <xsd:choice>
+        <xsd:element ref="switch" minOccurs="0" maxOccurs="unbounded" />
+      </xsd:choice>
+    </xsd:sequence>
+    <xsd:attribute name="name" type="xsd:string" use="optional" />
+  </xsd:complexType>
+
+  <!-- switch expression -->
+  <xsd:complexType name="switchexpr">
+    <xsd:sequence>
+      <!-- switch(expression) -->
+      <xsd:group ref="expression" minOccurs="1" maxOccurs="1" />
+      <xsd:choice>
+        <!-- bitcase expression - bit test -->
+        <xsd:element name="bitcase" type="caseexpr" minOccurs="1" maxOccurs="unbounded" />
+      </xsd:choice>
+      <!-- default: -->
+      <xsd:group ref="fields" minOccurs="0" maxOccurs="1" />
+    </xsd:sequence>
+    <xsd:attribute name="name" type="xsd:string" use="required" />
+  </xsd:complexType>
+
+  <xsd:element name="switch" type="switchexpr" />
+
+  <!-- field replaces FIELD, PARAM, and REPLY. -->
+  <xsd:element name="field" type="var" />
+
+  <!-- list replaces ARRAYFIELD, LISTPARAM, and ARRAYREPLY.  The name and type
+       are specified as attributes.  The content is an expression giving the
+       length. -->
+  <xsd:element name="list">
+    <xsd:complexType>
+      <xsd:complexContent>
+        <xsd:extension base="var">
+          <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />
+        </xsd:extension>
+      </xsd:complexContent>
+    </xsd:complexType>
+  </xsd:element>
+
+  <!-- Expressions -->
+  <xsd:group name="expression">
+    <xsd:choice>
+      <xsd:element name="op">
+        <xsd:complexType>
+          <xsd:sequence>
+            <xsd:group ref="expression" />
+            <xsd:group ref="expression" />
+          </xsd:sequence>
+          <xsd:attribute name="op" use="required">
+            <xsd:simpleType>
+              <xsd:restriction base="xsd:string">
+                <xsd:pattern value="\+|-|\*|/|&amp;|&lt;&lt;" />
+              </xsd:restriction>
+            </xsd:simpleType>
+          </xsd:attribute>
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="unop">
+         <xsd:complexType>
+            <xsd:sequence>
+              <xsd:group ref="expression" />
+            </xsd:sequence>
+            <xsd:attribute name="op" use="required">
+              <xsd:simpleType>
+                <xsd:restriction base="xsd:string">
+                  <xsd:pattern value="~" />
+                </xsd:restriction>
+              </xsd:simpleType>
+            </xsd:attribute>
+         </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="fieldref" type="xsd:string" />
+      <xsd:element name="enumref">
+        <xsd:complexType>
+          <xsd:simpleContent>
+            <xsd:extension base="xsd:string">
+              <xsd:attribute name="ref" use="required" type="xsd:string" />
+            </xsd:extension>
+          </xsd:simpleContent>
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="popcount">
+        <xsd:complexType>
+          <xsd:group ref="expression" />
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="sumof">
+        <xsd:complexType>
+          <xsd:attribute name="ref" use="required" type="xsd:string" />
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="value" type="dec-or-hex-integer" />
+      <xsd:element name="bit" type="xsd:integer" />
+    </xsd:choice>
+  </xsd:group>
+  
+  <!-- Fields in requests that are calculated from other information, not
+       supplied by the caller. -->
+  <xsd:element name="exprfield" >
+    <xsd:complexType>
+      <xsd:complexContent>
+        <xsd:extension base="var">
+          <xsd:group ref="expression" />
+        </xsd:extension>
+      </xsd:complexContent>
+    </xsd:complexType>
+  </xsd:element>
+
+  <!-- BITMASK/LISTofVALUE parameter pairs. -->
+  <xsd:element name="valueparam">
+    <xsd:complexType>
+      <xsd:attribute name="value-mask-type" type="xsd:string" use="required" />
+      <xsd:attribute name="value-mask-name" type="xsd:string" use="required" />
+      <xsd:attribute name="value-list-name" type="xsd:string" use="required" />
+    </xsd:complexType>
+  </xsd:element>
+
+  <xsd:group name="fields">
+    <xsd:choice>
+      <xsd:element ref="pad" />
+      <xsd:element ref="field" />
+      <xsd:element ref="list" />
+    </xsd:choice>
+  </xsd:group>
+
+  <!-- Type for a structure -->
+  <xsd:complexType name="struct">
+    <xsd:sequence>
+      <xsd:group ref="fields" minOccurs="1" maxOccurs="unbounded" />
+      <xsd:choice minOccurs="0" maxOccurs="1">
+        <xsd:element ref="switch" />
+      </xsd:choice>
+    </xsd:sequence>
+    <xsd:attribute name="name" type="xsd:string" use="required" />
+  </xsd:complexType>
+
+  <!-- Type for a packet structure -->
+  <xsd:complexType name="packet-struct">
+    <xsd:sequence>
+      <xsd:group ref="fields" minOccurs="0" maxOccurs="unbounded" />
+    </xsd:sequence>
+    <xsd:attribute name="name" type="xsd:string" use="required" />
+    <xsd:attribute name="number" type="xsd:integer" use="required" />
+  </xsd:complexType>
+
+  <!-- Type for a packet structure copy -->
+  <xsd:complexType name="packet-struct-copy">
+    <xsd:attribute name="name" type="xsd:string" use="required" />
+    <xsd:attribute name="number" type="xsd:integer" use="required" />
+    <xsd:attribute name="ref" type="xsd:string" use="required" />
+  </xsd:complexType>
+
+  <!-- Type for hex integers -->
+  <xsd:simpleType name="hex-integer">
+    <xsd:restriction base="xsd:string">
+      <xsd:pattern value="0x[0-9a-fA-F]+" />
+    </xsd:restriction>
+  </xsd:simpleType>
+
+  <!-- Type for integers in either decimal or hex -->
+  <xsd:simpleType name="dec-or-hex-integer">
+    <xsd:union memberTypes="xsd:integer hex-integer" />
+  </xsd:simpleType>
+
+  <!-- Type for documentation -->
+  <xsd:group name="doc-fields">
+    <xsd:sequence>
+      <xsd:element name="field">
+        <xsd:complexType>
+          <xsd:simpleContent>
+            <xsd:extension base="xsd:string">
+              <xsd:attribute name="name" type="xsd:string" />
+            </xsd:extension>
+          </xsd:simpleContent>
+        </xsd:complexType>
+      </xsd:element>
+    </xsd:sequence>
+  </xsd:group>
+
+  <xsd:group name="error-fields">
+    <xsd:sequence>
+      <xsd:element name="error">
+        <xsd:complexType>
+          <xsd:simpleContent>
+            <xsd:extension base="xsd:string">
+              <xsd:attribute name="type" type="xsd:string" />
+            </xsd:extension>
+          </xsd:simpleContent>
+        </xsd:complexType>
+      </xsd:element>
+    </xsd:sequence>
+  </xsd:group>
+
+  <xsd:group name="see-fields">
+    <xsd:sequence>
+      <xsd:element name="see">
+        <xsd:complexType>
+          <xsd:attribute name="name" type="xsd:string" />
+          <xsd:attribute name="type" type="xsd:string" />
+        </xsd:complexType>
+      </xsd:element>
+    </xsd:sequence>
+  </xsd:group>
+
+  <xsd:element name="doc">
+    <xsd:complexType mixed="true">
+      <xsd:sequence>
+        <xsd:element name="brief" type="xsd:string" minOccurs="0" maxOccurs="1" />
+        <xsd:element name="description" type="xsd:string" minOccurs="0" maxOccurs="1" />
+        <xsd:element name="example" type="xsd:string" minOccurs="0" maxOccurs="1" />
+        <xsd:group ref="doc-fields" minOccurs="0" maxOccurs="unbounded" />
+        <xsd:group ref="error-fields" minOccurs="0" maxOccurs="unbounded" />
+        <xsd:group ref="see-fields" minOccurs="0" maxOccurs="unbounded" />
+      </xsd:sequence>
+    </xsd:complexType>
+  </xsd:element>
+
+  <xsd:group name="macro">
+    <xsd:choice>
+      <xsd:element name="request">
+        <xsd:complexType>
+          <xsd:sequence>
+            <xsd:choice minOccurs="0" maxOccurs="unbounded">
+              <xsd:group ref="fields" />
+              <xsd:element ref="exprfield" />
+              <xsd:element ref="valueparam" />
+            </xsd:choice>
+            <xsd:choice minOccurs="0" maxOccurs="1">
+              <xsd:element ref="switch" />
+            </xsd:choice>
+            <xsd:element name="reply" minOccurs="0" maxOccurs="1">
+              <xsd:complexType>
+                <xsd:sequence>
+                  <xsd:choice minOccurs="1" maxOccurs="unbounded">
+                    <xsd:group ref="fields" />
+                    <xsd:element ref="valueparam" />
+                  </xsd:choice>
+                  <xsd:choice minOccurs="0" maxOccurs="1">
+                    <xsd:element ref="switch" />
+                  </xsd:choice>
+                  <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+                </xsd:sequence>
+              </xsd:complexType>
+            </xsd:element>
+            <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+          </xsd:sequence>
+          <xsd:attribute name="name" type="xsd:string" use="required" />
+          <xsd:attribute name="opcode" type="xsd:integer" use="required" />
+          <xsd:attribute name="combine-adjacent" type="xsd:boolean"
+                         use="optional"/>
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="event">
+        <xsd:complexType>
+          <xsd:complexContent>
+            <xsd:extension base="packet-struct">
+              <xsd:sequence>
+                <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+              </xsd:sequence>
+              <xsd:attribute name="no-sequence-number" type="xsd:boolean"
+                             use="optional" />
+            </xsd:extension>
+          </xsd:complexContent>
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="eventcopy" type="packet-struct-copy" />
+      <xsd:element name="error" type="packet-struct" />
+      <xsd:element name="errorcopy" type="packet-struct-copy" />
+      <xsd:element name="struct" type="struct" />
+      <xsd:element name="union" type="struct" />
+      <xsd:element name="xidtype">
+        <xsd:complexType>
+          <xsd:attribute name="name" type="xsd:string" use="required" />
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="xidunion">
+        <xsd:complexType>
+          <xsd:sequence>
+            <xsd:element name="type" type="xsd:string"
+                         minOccurs="1" maxOccurs="unbounded" />
+          </xsd:sequence>
+          <xsd:attribute name="name" type="xsd:string" use="required" />
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="enum">
+        <xsd:complexType>
+          <xsd:sequence minOccurs="1" maxOccurs="unbounded">
+            <xsd:element name="item">
+              <xsd:complexType>
+                <xsd:group ref="expression" minOccurs="0" maxOccurs="1" />
+                <xsd:attribute name="name" type="xsd:string" use="required" />
+              </xsd:complexType>
+            </xsd:element>
+            <xsd:element ref="doc" minOccurs="0" maxOccurs="1" />
+          </xsd:sequence>
+          <xsd:attribute name="name" type="xsd:string" use="required" />
+        </xsd:complexType>
+      </xsd:element>
+      <xsd:element name="typedef">
+        <xsd:complexType>
+          <xsd:attribute name="oldname" type="xsd:string" use="required" />
+          <xsd:attribute name="newname" type="xsd:string" use="required" />
+        </xsd:complexType>
+      </xsd:element>
+      <!-- The import element allows a protocol description to reference the
+           declarations of another protocol description. -->
+      <xsd:element name="import" type="xsd:string" />
+    </xsd:choice>
+  </xsd:group>
+</xsd:schema>
diff --git a/libxcb/xcb-proto/src/xproto.xml b/libxcb/xcb-proto/src/xproto.xml
index 42a6852a1..bf4dcbf0f 100644
--- a/libxcb/xcb-proto/src/xproto.xml
+++ b/libxcb/xcb-proto/src/xproto.xml
@@ -307,6 +307,44 @@ authorization from the authors.
     <field type="CARD16" name="state" mask="KeyButMask" />
     <field type="BOOL" name="same_screen" />
     <pad bytes="1" />
+    <doc>
+      <brief>a key was pressed/released</brief>
+      <field name="detail"><![CDATA[
+The keycode (a number representing a physical key on the keyboard) of the key
+which was pressed.
+      ]]></field>
+      <field name="time"><![CDATA[
+Time when the event was generated (in milliseconds).
+      ]]></field>
+      <field name="root"><![CDATA[
+The root window of `child`.
+      ]]></field>
+      <field name="same_screen"><![CDATA[
+Whether the `event` window is on the same screen as the `root` window.
+      ]]></field>
+      <field name="event_x"><![CDATA[
+If `same_screen` is true, this is the X coordinate relative to the `event`
+window's origin. Otherwise, `event_x` will be set to zero.
+      ]]></field>
+      <field name="event_y"><![CDATA[
+If `same_screen` is true, this is the Y coordinate relative to the `event`
+window's origin. Otherwise, `event_y` will be set to zero.
+      ]]></field>
+      <field name="root_x"><![CDATA[
+The X coordinate of the pointer relative to the `root` window at the time of
+the event.
+      ]]></field>
+      <field name="root_y"><![CDATA[
+The Y coordinate of the pointer relative to the `root` window at the time of
+the event.
+      ]]></field>
+      <field name="state"><![CDATA[
+The logical state of the pointer buttons and modifier keys just prior to the
+event.
+      ]]></field>
+      <see type="request" name="GrabKey" />
+      <see type="request" name="GrabKeyboard" />
+    </doc>
   </event>
 
   <eventcopy name="KeyRelease" number="3" ref="KeyPress" />
@@ -333,6 +371,44 @@ authorization from the authors.
     <field type="CARD16" name="state" mask="KeyButMask" />
     <field type="BOOL" name="same_screen" />
     <pad bytes="1" />
+    <doc>
+      <brief>a mouse button was pressed/released</brief>
+      <field name="detail"><![CDATA[
+The keycode (a number representing a physical key on the keyboard) of the key
+which was pressed.
+      ]]></field>
+      <field name="time"><![CDATA[
+Time when the event was generated (in milliseconds).
+      ]]></field>
+      <field name="root"><![CDATA[
+The root window of `child`.
+      ]]></field>
+      <field name="same_screen"><![CDATA[
+Whether the `event` window is on the same screen as the `root` window.
+      ]]></field>
+      <field name="event_x"><![CDATA[
+If `same_screen` is true, this is the X coordinate relative to the `event`
+window's origin. Otherwise, `event_x` will be set to zero.
+      ]]></field>
+      <field name="event_y"><![CDATA[
+If `same_screen` is true, this is the Y coordinate relative to the `event`
+window's origin. Otherwise, `event_y` will be set to zero.
+      ]]></field>
+      <field name="root_x"><![CDATA[
+The X coordinate of the pointer relative to the `root` window at the time of
+the event.
+      ]]></field>
+      <field name="root_y"><![CDATA[
+The Y coordinate of the pointer relative to the `root` window at the time of
+the event.
+      ]]></field>
+      <field name="state"><![CDATA[
+The logical state of the pointer buttons and modifier keys just prior to the
+event.
+      ]]></field>
+      <see type="request" name="GrabButton" />
+      <see type="request" name="GrabPointer" />
+    </doc>
   </event>
 
   <eventcopy name="ButtonRelease" number="5" ref="ButtonPress" />
@@ -356,6 +432,44 @@ authorization from the authors.
     <field type="CARD16" name="state" mask="KeyButMask" />
     <field type="BOOL" name="same_screen" />
     <pad bytes="1" />
+    <doc>
+      <brief>a key was pressed</brief>
+      <field name="detail"><![CDATA[
+The keycode (a number representing a physical key on the keyboard) of the key
+which was pressed.
+      ]]></field>
+      <field name="time"><![CDATA[
+Time when the event was generated (in milliseconds).
+      ]]></field>
+      <field name="root"><![CDATA[
+The root window of `child`.
+      ]]></field>
+      <field name="same_screen"><![CDATA[
+Whether the `event` window is on the same screen as the `root` window.
+      ]]></field>
+      <field name="event_x"><![CDATA[
+If `same_screen` is true, this is the X coordinate relative to the `event`
+window's origin. Otherwise, `event_x` will be set to zero.
+      ]]></field>
+      <field name="event_y"><![CDATA[
+If `same_screen` is true, this is the Y coordinate relative to the `event`
+window's origin. Otherwise, `event_y` will be set to zero.
+      ]]></field>
+      <field name="root_x"><![CDATA[
+The X coordinate of the pointer relative to the `root` window at the time of
+the event.
+      ]]></field>
+      <field name="root_y"><![CDATA[
+The Y coordinate of the pointer relative to the `root` window at the time of
+the event.
+      ]]></field>
+      <field name="state"><![CDATA[
+The logical state of the pointer buttons and modifier keys just prior to the
+event.
+      ]]></field>
+      <see type="request" name="GrabKey" />
+      <see type="request" name="GrabKeyboard" />
+    </doc>
   </event>
 
   <enum name="NotifyDetail">
@@ -389,6 +503,34 @@ authorization from the authors.
     <field type="CARD16" name="state" mask="KeyButMask" />
     <field type="BYTE" name="mode" enum="NotifyMode" />
     <field type="BYTE" name="same_screen_focus" />
+    <doc>
+      <brief>the pointer is in a different window</brief>
+      <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+      ]]></field>
+      <field name="window"><![CDATA[
+The window that was unmapped.
+      ]]></field>
+      <field name="root"><![CDATA[
+The root window for the final cursor position.
+      ]]></field>
+      <field name="root_x"><![CDATA[
+The pointer X coordinate relative to `root`'s origin at the time of the event.
+      ]]></field>
+      <field name="root_y"><![CDATA[
+The pointer Y coordinate relative to `root`'s origin at the time of the event.
+      ]]></field>
+      <field name="event_x"><![CDATA[
+If `event` is on the same screen as `root`, this is the pointer X coordinate
+relative to the event window's origin.
+      ]]></field>
+      <field name="event_y"><![CDATA[
+If `event` is on the same screen as `root`, this is the pointer Y coordinate
+relative to the event window's origin.
+      ]]></field>
+      <field name="mode" />
+    </doc>
   </event>
 
   <eventcopy name="LeaveNotify" number="8" ref="EnterNotify" />
@@ -398,6 +540,16 @@ authorization from the authors.
     <field type="WINDOW" name="event" />
     <field type="BYTE" name="mode" enum="NotifyMode" />
     <pad bytes="3" />
+    <doc>
+      <brief>NOT YET DOCUMENTED</brief>
+      <field name="event"><![CDATA[
+The window on which the focus event was generated. This is the window used by
+the X server to report the event.
+      ]]></field>
+      <!-- enum documentation is sufficient -->
+      <field name="detail" />
+      <field name="mode" />
+    </doc>
   </event>
 
   <eventcopy name="FocusOut" number="10" ref="FocusIn" />
@@ -415,6 +567,32 @@ authorization from the authors.
     <field type="CARD16" name="height" />
     <field type="CARD16" name="count" />
     <pad bytes="2" />
+    <doc>
+      <brief>NOT YET DOCUMENTED</brief>
+      <field name="window"><![CDATA[
+The exposed (damaged) window.
+      ]]></field>
+      <field name="x"><![CDATA[
+The X coordinate of the left-upper corner of the exposed rectangle, relative to
+the `window`'s origin.
+      ]]></field>
+      <field name="y"><![CDATA[
+The Y coordinate of the left-upper corner of the exposed rectangle, relative to
+the `window`'s origin.
+      ]]></field>
+      <field name="width"><![CDATA[
+The width of the exposed rectangle.
+      ]]></field>
+      <field name="height"><![CDATA[
+The height of the exposed rectangle.
+      ]]></field>
+      <field name="count"><![CDATA[
+The amount of `Expose` events following this one. Simple applications that do
+not want to optimize redisplay by distinguishing between subareas of its window
+can just ignore all Expose events with nonzero counts and perform full
+redisplays on events with zero counts.
+      ]]></field>
+    </doc>
   </event>
 
   <event name="GraphicsExposure" number="13">
@@ -468,6 +646,17 @@ authorization from the authors.
     <pad bytes="1" />
     <field type="WINDOW" name="event" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>a window is destroyed</brief>
+      <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+      ]]></field>
+      <field name="window"><![CDATA[
+The window that is destroyed.
+      ]]></field>
+      <see type="request" name="DestroyWindow" />
+    </doc>
   </event>
 
   <event name="UnmapNotify" number="18">
@@ -476,6 +665,21 @@ authorization from the authors.
     <field type="WINDOW" name="window" />
     <field type="BOOL" name="from_configure" />
     <pad bytes="3" />
+    <doc>
+      <brief>a window is unmapped</brief>
+      <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+      ]]></field>
+      <field name="window"><![CDATA[
+The window that was unmapped.
+      ]]></field>
+      <field name="from_configure"><![CDATA[
+Set to 1 if the event was generated as a result of a resizing of the window's
+parent when `window` had a win_gravity of `UnmapGravity`.
+      ]]></field>
+      <see type="request" name="UnmapWindow" />
+    </doc>
   </event>
 
   <event name="MapNotify" number="19">
@@ -484,12 +688,36 @@ authorization from the authors.
     <field type="WINDOW" name="window" />
     <field type="BOOL" name="override_redirect" />
     <pad bytes="3" />
+    <doc>
+      <brief>a window was mapped</brief>
+      <field name="event"><![CDATA[
+The window which was mapped or its parent, depending on whether
+`StructureNotify` or `SubstructureNotify` was selected.
+      ]]></field>
+      <field name="window"><![CDATA[
+The window that was mapped.
+      ]]></field>
+      <field name="override_redirect"><![CDATA[
+Window managers should ignore this window if `override_redirect` is 1.
+      ]]></field>
+      <see type="request" name="MapWindow" />
+    </doc>
   </event>
 
   <event name="MapRequest" number="20">
     <pad bytes="1" />
     <field type="WINDOW" name="parent" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>window wants to be mapped</brief>
+      <field name="parent"><![CDATA[
+The parent of `window`.
+      ]]></field>
+      <field name="window"><![CDATA[
+The window to be mapped.
+      ]]></field>
+      <see type="request" name="MapWindow" />
+    </doc>
   </event>
 
   <event name="ReparentNotify" number="21">
@@ -515,6 +743,42 @@ authorization from the authors.
     <field type="CARD16" name="border_width" />
     <field type="BOOL" name="override_redirect" />
     <pad bytes="1" />
+    <doc>
+      <brief>NOT YET DOCUMENTED</brief>
+      <field name="event"><![CDATA[
+The reconfigured window or its parent, depending on whether `StructureNotify`
+or `SubstructureNotify` was selected.
+      ]]></field>
+      <field name="window"><![CDATA[
+The window whose size, position, border, and/or stacking order was changed.
+      ]]></field>
+      <field name="above_sibling"><![CDATA[
+If `XCB_NONE`, the `window` is on the bottom of the stack with respect to
+sibling windows. However, if set to a sibling window, the `window` is placed on
+top of this sibling window.
+      ]]></field>
+      <field name="x"><![CDATA[
+The X coordinate of the upper-left outside corner of `window`, relative to the
+parent window's origin.
+      ]]></field>
+      <field name="y"><![CDATA[
+The Y coordinate of the upper-left outside corner of `window`, relative to the
+parent window's origin.
+      ]]></field>
+      <field name="width"><![CDATA[
+The inside width of `window`, not including the border.
+      ]]></field>
+      <field name="height"><![CDATA[
+The inside height of `window`, not including the border.
+      ]]></field>
+      <field name="border_width"><![CDATA[
+The border width of `window`.
+      ]]></field>
+      <field name="override_redirect"><![CDATA[
+Window managers should ignore this window if `override_redirect` is 1.
+      ]]></field>
+      <see type="request" name="FreeColormap" />
+    </doc>
   </event>
 
   <event name="ConfigureRequest" number="23">
@@ -548,6 +812,14 @@ authorization from the authors.
   <enum name="Place">
     <item name="OnTop">   <value>0</value></item>
     <item name="OnBottom"><value>1</value></item>
+    <doc>
+      <field name="OnTop"><![CDATA[
+The window is now on top of all siblings.
+      ]]></field>
+      <field name="OnBottom"><![CDATA[
+The window is now below all siblings.
+      ]]></field>
+    </doc>
   </enum>
 
   <event name="CirculateNotify" number="26">
@@ -557,6 +829,19 @@ authorization from the authors.
     <pad bytes="4" />
     <field type="BYTE" name="place" enum="Place" />
     <pad bytes="3" />
+    <doc>
+      <brief>NOT YET DOCUMENTED</brief>
+      <field name="event"><![CDATA[
+Either the restacked window or its parent, depending on whether
+`StructureNotify` or `SubstructureNotify` was selected.
+      ]]></field>
+      <field name="window"><![CDATA[
+The restacked window.
+      ]]></field>
+      <!-- the enum doc is sufficient -->
+      <field name="place" />
+      <see type="request" name="CirculateWindow" />
+    </doc>
   </event>
 
   <eventcopy name="CirculateRequest" number="27" ref="CirculateNotify" />
@@ -573,6 +858,21 @@ authorization from the authors.
     <field type="TIMESTAMP" name="time" />
     <field type="BYTE" name="state" enum="Property" />
     <pad bytes="3" />
+    <doc>
+      <brief>a window property changed</brief>
+      <field name="window"><![CDATA[
+The window whose associated property was changed.
+      ]]></field>
+      <field name="atom"><![CDATA[
+The property's atom, to indicate which property was changed.
+      ]]></field>
+      <field name="time"><![CDATA[
+A timestamp of the server time when the property was changed.
+      ]]></field>
+      <!-- enum documentation is sufficient -->
+      <field name="state" />
+      <see type="request" name="ChangeProperty" />
+    </doc>
   </event>
 
   <event name="SelectionClear" number="29">
@@ -681,6 +981,14 @@ authorization from the authors.
   <enum name="ColormapState">
     <item name="Uninstalled"><value>0</value></item>
     <item name="Installed">  <value>1</value></item>
+    <doc>
+      <field name="Uninstalled"><![CDATA[
+The colormap was uninstalled.
+      ]]></field>
+      <field name="Installed"><![CDATA[
+The colormap was installed.
+      ]]></field>
+    </doc>
   </enum>
 
   <enum name="Colormap">
@@ -694,6 +1002,22 @@ authorization from the authors.
     <field type="BOOL" name="new" />
     <field type="BYTE" name="state" enum="ColormapState" />
     <pad bytes="2" />
+    <doc>
+      <brief>the colormap for some window changed</brief>
+      <field name="window"><![CDATA[
+The window whose associated colormap is changed, installed or uninstalled.
+      ]]></field>
+      <field name="colormap"><![CDATA[
+The colormap which is changed, installed or uninstalled. This is `XCB_NONE`
+when the colormap is changed by a call to `FreeColormap`.
+      ]]></field>
+      <field name="_new"><![CDATA[
+Indicates whether the colormap was changed (1) or installed/uninstalled (0).
+      ]]></field>
+      <!-- enum doc is sufficient -->
+      <field name="state" />
+      <see type="request" name="FreeColormap" />
+    </doc>
   </event>
 
   <union name="ClientMessageData">
@@ -709,6 +1033,26 @@ authorization from the authors.
     <field type="WINDOW" name="window" />
     <field type="ATOM" name="type" />
     <field type="ClientMessageData" name="data" />
+    <doc>
+      <brief>NOT YET DOCUMENTED</brief>
+      <description><![CDATA[
+This event represents a ClientMessage, sent by another X11 client. An example
+is a client sending the `_NET_WM_STATE` ClientMessage to the root window
+to indicate the fullscreen window state, effectively requesting that the window
+manager puts it into fullscreen mode.
+      ]]></description>
+      <field name="format"><![CDATA[
+Specifies how to interpret `data`. Can be either 8, 16 or 32.
+      ]]></field>
+      <field name="type"><![CDATA[
+An atom which indicates how the data should be interpreted by the receiving
+client.
+      ]]></field>
+      <field name="data"><![CDATA[
+The data itself (20 bytes max).
+      ]]></field>
+      <see type="request" name="SendEvent" />
+    </doc>
   </event>
 
   <enum name="Mapping">
@@ -723,6 +1067,17 @@ authorization from the authors.
     <field type="KEYCODE" name="first_keycode" />
     <field type="CARD8" name="count" />
     <pad bytes="1" />
+    <doc>
+      <brief>keyboard mapping changed</brief>
+      <!-- enum documentation is sufficient -->
+      <field name="request" />
+      <field name="first_keycode"><![CDATA[
+The first number in the range of the altered mapping.
+      ]]></field>
+      <field name="count"><![CDATA[
+The number of keycodes altered.
+      ]]></field>
+    </doc>
   </event>
 
 
@@ -791,6 +1146,106 @@ authorization from the authors.
     <item name="DontPropagate">   <bit>12</bit></item>
     <item name="Colormap">        <bit>13</bit></item>
     <item name="Cursor">          <bit>14</bit></item>
+    <doc>
+      <field name="BackPixmap"><![CDATA[
+Overrides the default background-pixmap. The background pixmap and window must
+have the same root and same depth. Any size pixmap can be used, although some
+sizes may be faster than others.
+
+If `XCB_BACK_PIXMAP_NONE` is specified, the window has no defined background.
+The server may fill the contents with the previous screen contents or with
+contents of its own choosing.
+
+If `XCB_BACK_PIXMAP_PARENT_RELATIVE` is specified, the parent's background is
+used, but the window must have the same depth as the parent (or a Match error
+results).   The parent's background is tracked, and the current version is
+used each time the window background is required.
+      ]]></field>
+      <field name="BackPixel"><![CDATA[
+Overrides `BackPixmap`. A pixmap of undefined size filled with the specified
+background pixel is used for the background. Range-checking is not performed,
+the background pixel is truncated to the appropriate number of bits.
+      ]]></field>
+      <field name="BorderPixmap"><![CDATA[
+Overrides the default border-pixmap. The border pixmap and window must have the
+same root and the same depth. Any size pixmap can be used, although some sizes
+may be faster than others.
+
+The special value `XCB_COPY_FROM_PARENT` means the parent's border pixmap is
+copied (subsequent changes to the parent's border attribute do not affect the
+child), but the window must have the same depth as the parent.
+      ]]></field>
+      <field name="BorderPixel"><![CDATA[
+Overrides `BorderPixmap`. A pixmap of undefined size filled with the specified
+border pixel is used for the border. Range checking is not performed on the
+border-pixel value, it is truncated to the appropriate number of bits.
+      ]]></field>
+      <field name="BitGravity"><![CDATA[
+Defines which region of the window should be retained if the window is resized.
+      ]]></field>
+      <field name="WinGravity"><![CDATA[
+Defines how the window should be repositioned if the parent is resized (see
+`ConfigureWindow`).
+      ]]></field>
+      <field name="BackingStore"><![CDATA[
+A backing-store of `WhenMapped` advises the server that maintaining contents of
+obscured regions when the window is mapped would be beneficial. A backing-store
+of `Always` advises the server that maintaining contents even when the window
+is unmapped would be beneficial. In this case, the server may generate an
+exposure event when the window is created. A value of `NotUseful` advises the
+server that maintaining contents is unnecessary, although a server may still
+choose to maintain contents while the window is mapped. Note that if the server
+maintains contents, then the server should maintain complete contents not just
+the region within the parent boundaries, even if the window is larger than its
+parent. While the server maintains contents, exposure events will not normally
+be generated, but the server may stop maintaining contents at any time.
+      ]]></field>
+      <field name="BackingPlanes"><![CDATA[
+The backing-planes indicates (with bits set to 1) which bit planes of the
+window hold dynamic data that must be preserved in backing-stores and during
+save-unders.
+      ]]></field>
+      <field name="BackingPixel"><![CDATA[
+The backing-pixel specifies what value to use in planes not covered by
+backing-planes. The server is free to save only the specified bit planes in the
+backing-store or save-under and regenerate the remaining planes with the
+specified pixel value. Any bits beyond the specified depth of the window in
+these values are simply ignored.
+      ]]></field>
+      <field name="OverrideRedirect"><![CDATA[
+The override-redirect specifies whether map and configure requests on this
+window should override a SubstructureRedirect on the parent, typically to
+inform a window manager not to tamper with the window.
+      ]]></field>
+      <field name="SaveUnder"><![CDATA[
+If 1, the server is advised that when this window is mapped, saving the
+contents of windows it obscures would be beneficial.
+      ]]></field>
+      <field name="EventMask"><![CDATA[
+The event-mask defines which events the client is interested in for this window
+(or for some event types, inferiors of the window).
+      ]]></field>
+      <field name="DontPropagate"><![CDATA[
+The do-not-propagate-mask defines which events should not be propagated to
+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.
+      ]]></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.
+      ]]></field>
+    </doc>
   </enum>
   
   <enum name="BackPixmap">
@@ -827,6 +1282,79 @@ authorization from the authors.
     <valueparam value-mask-type="CARD32"
                 value-mask-name="value_mask"
                 value-list-name="value_list" />
+    <doc>
+      <brief>Creates a window</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
+stacking order with respect to siblings.
+
+The coordinate system has the X axis horizontal and the Y axis vertical with
+the origin [0, 0] at the upper-left corner. Coordinates are integral, in terms
+of pixels, and coincide with pixel centers. Each window and pixmap has its own
+coordinate system. For a window, the origin is inside the border at the inside,
+upper-left corner.
+
+The created window is not yet displayed (mapped), call `xcb_map_window` to
+display it.
+
+The created window will initially use the same cursor as its parent.
+      ]]></description>
+      <field name="wid"><![CDATA[
+The ID with which you will refer to the new window, created by
+`xcb_generate_id`.
+      ]]></field>
+      <field name="depth"><![CDATA[
+Specifies the new window's depth (TODO: what unit?).
+
+The special value `XCB_COPY_FROM_PARENT` means the depth is taken from the
+`parent` window.
+      ]]></field>
+      <field name="visual"><![CDATA[
+Specifies the id for the new window's visual.
+
+The special value `XCB_COPY_FROM_PARENT` means the visual is taken from the
+`parent` window.
+      ]]></field>
+      <field name="class"></field>
+      <field name="parent"><![CDATA[
+The parent window of the new window.
+      ]]></field>
+      <field name="border_width"><![CDATA[
+      TODO:
+
+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>
+      <error type="Colormap"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Cursor"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Pixmap"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+      ]]></error>
+      <see type="function" name="xcb_generate_id" />
+      <see type="request" name="MapWindow" />
+      <see type="event" name="CreateNotify" />
+    </doc>
+
   </request>
 
   <request name="ChangeWindowAttributes" opcode="2">
@@ -835,6 +1363,43 @@ authorization from the authors.
     <valueparam value-mask-type="CARD32"
                 value-mask-name="value_mask"
                 value-list-name="value_list" />
+    <doc>
+      <brief>change window attributes</brief>
+      <description><![CDATA[
+Changes the attributes specified by `value_mask` for the specified `window`.
+      ]]></description>
+      <field name="window"><![CDATA[
+The window to change.
+      ]]></field>
+      <!-- the enum documentation is good enough. -->
+      <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="Access"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Colormap"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Cursor"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Pixmap"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+    </doc>
   </request>
   
   <enum name="MapState">
@@ -863,12 +1428,79 @@ authorization from the authors.
       <field type="CARD32" name="your_event_mask" mask="EventMask" />
       <field type="CARD16" name="do_not_propagate_mask" mask="EventMask" />
       <pad bytes="2" />
+      <doc>
+        <field name="override_redirect"><![CDATA[
+Window managers should ignore this window if `override_redirect` is 1.
+        ]]></field>
+        <field name="visual"><![CDATA[
+The associated visual structure of `window`.
+        ]]></field>
+        <field name="backing_planes"><![CDATA[
+Planes to be preserved if possible.
+        ]]></field>
+        <field name="backing_pixel"><![CDATA[
+Value to be used when restoring planes.
+        ]]></field>
+        <field name="save_under"><![CDATA[
+Boolean, should bits under be saved?
+        ]]></field>
+        <field name="colormap"><![CDATA[
+Color map to be associated with window.
+        ]]></field>
+        <field name="all_event_masks"><![CDATA[
+Set of events all people have interest in.
+        ]]></field>
+        <field name="your_event_mask"><![CDATA[
+My event mask.
+        ]]></field>
+        <field name="do_not_propagate_mask"><![CDATA[
+Set of events that should not propagate.
+        ]]></field>
+        <!-- enum documentation is sufficient for these fields -->
+        <field name="backing_store" />
+        <field name="class" />
+        <field name="bit_gravity" />
+        <field name="win_gravity" />
+        <field name="map_state" />
+      </doc>
     </reply>
+    <doc>
+      <brief>Gets window attributes</brief>
+      <description><![CDATA[
+Gets the current attributes for the specified `window`.
+      ]]></description>
+      <field name="window"><![CDATA[The window to get the attributes from.]]></field>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+      <error type="Drawable"><![CDATA[
+TODO: reasons?
+      ]]></error>
+    </doc>
+
   </request>
 
   <request name="DestroyWindow" opcode="4">
     <pad bytes="1" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>Destroys a window</brief>
+      <description><![CDATA[
+Destroys the specified window and all of its subwindows. A DestroyNotify event
+is generated for each destroyed window (a DestroyNotify event is first generated
+for any given window's inferiors). If the window was mapped, it will be
+automatically unmapped before destroying.
+
+Calling DestroyWindow on the root window will do nothing.
+      ]]></description>
+      <field name="window"><![CDATA[The window to destroy.]]></field>
+      <error type="Window"><![CDATA[
+The specified window does not exist.
+      ]]></error>
+      <see type="event" name="DestroyNotify" />
+      <see type="request" name="MapWindow" />
+      <see type="request" name="UnmapWindow" />
+    </doc>
   </request>
 
   <request name="DestroySubwindows" opcode="5">
@@ -884,6 +1516,28 @@ authorization from the authors.
   <request name="ChangeSaveSet" opcode="6">
     <field type="BYTE" name="mode" enum="SetMode" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>Changes a client's save set</brief>
+      <description><![CDATA[
+TODO: explain what the save set is for.
+
+This function either adds or removes the specified window to the client's (your
+application's) save set.
+      ]]></description>
+      <field name="mode"><![CDATA[Insert to add the specified window to the save set or Delete to delete it from the save set.]]></field>
+      <field name="window"><![CDATA[The window to add or delete to/from your save set.]]></field>
+      <error type="Match"><![CDATA[
+You created the specified window. This does not make sense, you can only add
+windows created by other clients to your save set.
+      ]]></error>
+      <error type="Value"><![CDATA[
+You specified an invalid mode.
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified window does not exist.
+      ]]></error>
+      <see type="request" name="ReparentWindow" />
+    </doc>
   </request>
 
   <request name="ReparentWindow" opcode="7">
@@ -892,11 +1546,78 @@ authorization from the authors.
     <field type="WINDOW" name="parent" />
     <field type="INT16" name="x" />
     <field type="INT16" name="y" />
+    <doc>
+      <brief>Reparents a window</brief>
+      <description><![CDATA[
+Makes the specified window a child of the specified parent window. If the
+window is mapped, it will automatically be unmapped before reparenting and
+re-mapped after reparenting. The window is placed in the stacking order on top
+with respect to sibling windows.
+
+After reparenting, a ReparentNotify event is generated.
+      ]]></description>
+      <field name="window"><![CDATA[The window to reparent.]]></field>
+      <field name="parent"><![CDATA[The new parent of the window.]]></field>
+      <field name="x"><![CDATA[
+The X position of the window within its new parent.
+      ]]></field>
+      <field name="y"><![CDATA[
+The Y position of the window within its new parent.
+      ]]></field>
+      <error type="Match"><![CDATA[
+The new parent window is not on the same screen as the old parent window.
+
+The new parent window is the specified window or an inferior of the specified window.
+
+The new parent is InputOnly and the window is not.
+
+The specified window has a ParentRelative background and the new parent window is not the same depth as the specified window.
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified window does not exist.
+      ]]></error>
+      <see type="event" name="ReparentNotify" />
+      <see type="request" name="MapWindow" />
+      <see type="request" name="UnmapWindow" />
+    </doc>
   </request>
 
   <request name="MapWindow" opcode="8">
     <pad bytes="1" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>Makes a window visible</brief>
+      <description><![CDATA[
+Maps the specified window. This means making the window visible (as long as its
+parent is visible).
+
+This MapWindow request will be translated to a MapRequest request if a window
+manager is running. The window manager then decides to either map the window or
+not. Set the override-redirect window attribute to true if you want to bypass
+this mechanism.
+
+If the window manager decides to map the window (or if no window manager is
+running), a MapNotify event is generated.
+
+If the window becomes viewable and no earlier contents for it are remembered,
+the X server tiles the window with its background. If the window's background
+is undefined, the existing screen contents are not altered, and the X server
+generates zero or more Expose events.
+
+If the window type is InputOutput, an Expose event will be generated when the
+window becomes visible. The normal response to an Expose event should be to
+repaint the window.
+      ]]></description>
+      <field name="window"><![CDATA[
+The window to make visible.
+]]></field>
+      <error type="Match"><![CDATA[
+The specified window does not exist.
+      ]]></error>
+      <see type="event" name="MapNotify" />
+      <see type="event" name="Expose" />
+      <see type="request" name="UnmapWindow" />
+    </doc>
   </request>
 
   <request name="MapSubwindows" opcode="9">
@@ -907,6 +1628,25 @@ authorization from the authors.
   <request name="UnmapWindow" opcode="10">
     <pad bytes="1" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>Makes a window invisible</brief>
+      <description><![CDATA[
+Unmaps the specified window. This means making the window invisible (and all
+its child windows).
+
+Unmapping a window leads to the `UnmapNotify` event being generated. Also,
+`Expose` events are generated for formerly obscured windows.
+      ]]></description>
+      <field name="window"><![CDATA[
+The window to make invisible.
+]]></field>
+      <error type="Window"><![CDATA[
+The specified window does not exist.
+      ]]></error>
+      <see type="event" name="UnmapNotify" />
+      <see type="event" name="Expose" />
+      <see type="request" name="MapWindow" />
+    </doc>
   </request>
 
   <request name="UnmapSubwindows" opcode="11">
@@ -940,6 +1680,55 @@ authorization from the authors.
     <valueparam value-mask-type="CARD16"
                 value-mask-name="value_mask"
                 value-list-name="value_list" />
+    <doc>
+      <brief>Configures window attributes</brief>
+      <description><![CDATA[
+Configures a window's size, position, border width and stacking order.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Configures the given window to the left upper corner
+ * with a size of 1024x768 pixels.
+ *
+ */
+void my_example(xcb_connection *c, xcb_window_t window) {
+    uint16_t mask = 0;
+
+    mask |= XCB_CONFIG_WINDOW_X;
+    mask |= XCB_CONFIG_WINDOW_Y;
+    mask |= XCB_CONFIG_WINDOW_WIDTH;
+    mask |= XCB_CONFIG_WINDOW_HEIGHT;
+
+    const uint32_t values[] = {
+        0,    /* x */
+        0,    /* y */
+        1024, /* width */
+        768   /* height */
+    };
+
+    xcb_configure_window(c, window, mask, values);
+    xcb_flush(c);
+}
+      ]]></example>
+      <field name="window"><![CDATA[The window to configure.]]></field>
+      <field name="value_mask"><![CDATA[Bitmask of attributes to change.]]></field>
+      <field name="value_list"><![CDATA[
+New values, corresponding to the attributes in value_mask. The order has to
+correspond to the order of possible `value_mask` bits. See the example.
+      ]]></field>
+      <error type="Match"><![CDATA[
+You specified a Sibling without also specifying StackMode or the window is not
+actually a Sibling.
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified window does not exist. TODO: any other reason?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <see type="event" name="MapNotify" />
+      <see type="event" name="Expose" />
+    </doc>
   </request>
 
   <enum name="Circulate">
@@ -950,6 +1739,27 @@ authorization from the authors.
   <request name="CirculateWindow" opcode="13">
     <field type="CARD8" name="direction" enum="Circulate" />
     <field type="WINDOW" name="window" />
+    <doc>
+      <brief>Change window stacking order</brief>
+      <description><![CDATA[
+If `direction` is `XCB_CIRCULATE_RAISE_LOWEST`, the lowest mapped child (if
+any) will be raised to the top of the stack.
+
+If `direction` is `XCB_CIRCULATE_LOWER_HIGHEST`, the highest mapped child will
+be lowered to the bottom of the stack.
+      ]]></description>
+      <!-- The enums are documented, we have nothing to add. -->
+      <field name="direction" />
+      <field name="window"><![CDATA[
+The window to raise/lower (depending on `direction`).
+      ]]></field>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+      <error type="Value"><![CDATA[
+The specified `direction` is invalid.
+      ]]></error>
+    </doc>
   </request>
 
   <request name="GetGeometry" opcode="14">
@@ -964,7 +1774,67 @@ authorization from the authors.
       <field type="CARD16" name="height" />
       <field type="CARD16" name="border_width" />
       <pad bytes="2" />
+      <doc>
+      <field name="root"><![CDATA[
+Root window of the screen containing `drawable`.
+      ]]></field>
+      <field name="x"><![CDATA[
+The X coordinate of `drawable`. If `drawable` is a window, the coordinate
+specifies the upper-left outer corner relative to its parent's origin. If
+`drawable` is a pixmap, the X coordinate is always 0.
+      ]]></field>
+      <field name="y"><![CDATA[
+The Y coordinate of `drawable`. If `drawable` is a window, the coordinate
+specifies the upper-left outer corner relative to its parent's origin. If
+`drawable` is a pixmap, the Y coordinate is always 0.
+      ]]></field>
+      <field name="width"><![CDATA[
+The width of `drawable`.
+      ]]></field>
+      <field name="height"><![CDATA[
+The height of `drawable`.
+      ]]></field>
+      <field name="border_width"><![CDATA[
+The border width (in pixels).
+      ]]></field>
+      <field name="depth"><![CDATA[
+The depth of the drawable (bits per pixel for the object).
+      ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>Get current window geometry</brief>
+      <description><![CDATA[
+Gets the current geometry of the specified drawable (either `Window` or `Pixmap`).
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Displays the x and y position of the given window.
+ *
+ */
+void my_example(xcb_connection *c, xcb_window_t window) {
+    xcb_get_geometry_cookie_t cookie;
+    xcb_get_geometry_reply_t *reply;
+
+    cookie = xcb_get_geometry(c, window);
+    /* ... do other work here if possible ... */
+    if ((reply = xcb_get_geometry_reply(c, cookie, NULL))) {
+        printf("This window is at %d, %d\\n", reply->x, reply->y);
+    }
+    free(reply);
+}
+      ]]></example>
+      <field name="drawable"><![CDATA[
+The drawable (`Window` or `Pixmap`) of which the geometry will be received.
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <see type="program" name="xwininfo" />
+    </doc>
   </request>
 
   <request name="QueryTree" opcode="15">
@@ -979,7 +1849,51 @@ authorization from the authors.
       <list type="WINDOW" name="children">
         <fieldref>children_len</fieldref>
       </list>
+      <doc>
+        <field name="root"><![CDATA[
+The root window of `window`.
+        ]]></field>
+        <field name="parent"><![CDATA[
+The parent window of `window`.
+        ]]></field>
+        <field name="children_len"><![CDATA[
+The number of child windows.
+        ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>query the window tree</brief>
+      <description><![CDATA[
+Gets the root window ID, parent window ID and list of children windows for the
+specified `window`. The children are listed in bottom-to-top stacking order.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Displays the root, parent and children of the specified window.
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+    xcb_query_tree_cookie_t cookie;
+    xcb_query_tree_reply_t *reply;
+
+    cookie = xcb_query_tree(conn, window);
+    if ((reply = xcb_query_tree_reply(conn, cookie, NULL))) {
+        printf("root = 0x%08x\\n", reply->root);
+        printf("parent = 0x%08x\\n", reply->parent);
+
+        xcb_window_t *children = xcb_query_tree_children(reply);
+        for (int i = 0; i < xcb_query_tree_children_length(reply); i++)
+            printf("child window = 0x%08x\\n", children[i]);
+
+        free(reply);
+    }
+}
+      ]]></example>
+      <field name="window"><![CDATA[
+The `window` to query.
+      ]]></field>
+      <see type="program" name="xwininfo" />
+    </doc>
   </request>
 
   <request name="InternAtom" opcode="16">
@@ -993,6 +1907,53 @@ authorization from the authors.
       <pad bytes="1" />
       <field type="ATOM" name="atom" altenum="Atom" />
     </reply>
+    <doc>
+      <brief>Get atom identifier by name</brief>
+      <description><![CDATA[
+Retrieves the identifier (xcb_atom_t TODO) for the atom with the specified
+name. Atoms are used in protocols like EWMH, for example to store window titles
+(`_NET_WM_NAME` atom) as property of a window.
+
+If `only_if_exists` is 0, the atom will be created if it does not already exist.
+If `only_if_exists` is 1, `XCB_ATOM_NONE` will be returned if the atom does
+not yet exist.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Resolves the _NET_WM_NAME atom.
+ *
+ */
+void my_example(xcb_connection *c) {
+    xcb_intern_atom_cookie_t cookie;
+    xcb_intern_atom_reply_t *reply;
+
+    cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
+    /* ... do other work here if possible ... */
+    if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
+        printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
+        free(reply);
+    }
+}
+      ]]></example>
+      <field name="name_len"><![CDATA[
+The length of the following `name`.
+      ]]></field>
+      <field name="name"><![CDATA[
+The name of the atom.
+      ]]></field>
+      <field name="only_if_exists"><![CDATA[
+Return a valid atom id only if the atom already exists.
+      ]]></field>
+      <error type="Alloc"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+A value other than 0 or 1 was specified for `only_if_exists`.
+      ]]></error>
+      <see type="program" name="xlsatoms" />
+      <see type="request" name="GetAtomName" />
+    </doc>
+
   </request>
 
   <request name="GetAtomName" opcode="17">
@@ -1012,6 +1973,21 @@ authorization from the authors.
     <item name="Replace"><value>0</value></item>
     <item name="Prepend"><value>1</value></item>
     <item name="Append"> <value>2</value></item>
+    <doc>
+      <field name="Replace"><![CDATA[
+Discard the previous property value and store the new data.
+      ]]></field>
+      <field name="Prepend"><![CDATA[
+Insert the new data before the beginning of existing data. The `format` must
+match existing property value. If the property is undefined, it is treated as
+defined with the correct type and format with zero-length data.
+      ]]></field>
+      <field name="Append"><![CDATA[
+Insert the new data after the beginning of existing data. The `format` must
+match existing property value. If the property is undefined, it is treated as
+defined with the correct type and format with zero-length data.
+      ]]></field>
+    </doc>
   </enum>
 
   <request name="ChangeProperty" opcode="18">
@@ -1031,6 +2007,71 @@ authorization from the authors.
         <value>8</value>
       </op>
     </list>
+    <doc>
+      <brief>Changes a window property</brief>
+      <description><![CDATA[
+Sets or updates a property on the specified `window`. Properties are for
+example the window title (`WM_NAME`) or its minimum size (`WM_NORMAL_HINTS`).
+Protocols such as EWMH also use properties - for example EWMH defines the
+window title, encoded as UTF-8 string, in the `_NET_WM_NAME` property.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Sets the WM_NAME property of the window to "XCB Example".
+ *
+ */
+void my_example(xcb_connection *conn, xcb_window_t window) {
+    xcb_change_property(conn,
+        XCB_PROP_MODE_REPLACE,
+        window,
+        XCB_ATOM_WM_NAME,
+        XCB_ATOM_STRING,
+        8,
+        strlen("XCB Example"),
+        "XCB Example");
+    xcb_flush(conn);
+}
+      ]]></example>
+      <field name="window"><![CDATA[
+The window whose property you want to change.
+      ]]></field>
+      <!-- the enum doc is sufficient. -->
+      <field name="mode" />
+      <field name="property"><![CDATA[
+The property you want to change (an atom).
+      ]]></field>
+      <field name="type"><![CDATA[
+The type of the property you want to change (an atom).
+      ]]></field>
+      <field name="format"><![CDATA[
+Specifies whether the data should be viewed as a list of 8-bit, 16-bit or
+32-bit quantities. Possible values are 8, 16 and 32. This information allows
+the X server to correctly perform byte-swap operations as necessary.
+      ]]></field>
+      <field name="data_len"><![CDATA[
+Specifies the number of elements (see `format`).
+      ]]></field>
+      <field name="data"><![CDATA[
+The property data.
+      ]]></field>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+      <error type="Atom"><![CDATA[
+`property` or `type` do not refer to a valid atom.
+      ]]></error>
+      <error type="Alloc"><![CDATA[
+The X server could not store the property (no memory?).
+      ]]></error>
+      <see type="request" name="InternAtom" />
+      <see type="program" name="xprop" />
+    </doc>
   </request>
 
   <request name="DeleteProperty" opcode="19">
@@ -1057,15 +2098,110 @@ authorization from the authors.
       <field type="CARD32" name="value_len" />
       <pad bytes="12" />
       <list type="void" name="value">
-	<op op="*">
-	  <fieldref>value_len</fieldref>
-	  <op op="/">
-	    <fieldref>format</fieldref>
-	    <value>8</value>
-	  </op>
-	</op>
+        <op op="*">
+          <fieldref>value_len</fieldref>
+          <op op="/">
+            <fieldref>format</fieldref>
+            <value>8</value>
+          </op>
+        </op>
       </list>
+      <doc>
+      <field name="format"><![CDATA[
+Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or
+32-bit quantities. Possible values are 8, 16, and 32. This information allows
+the X server to correctly perform byte-swap operations as necessary.
+      ]]></field>
+      <field name="type"><![CDATA[
+The actual type of the property (an atom).
+      ]]></field>
+      <field name="bytes_after"><![CDATA[
+The number of bytes remaining to be read in the property if a partial read was
+performed.
+      ]]></field>
+      <field name="value_len"><![CDATA[
+The length of value. You should use the corresponding accessor instead of this
+field.
+      ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>Gets a window property</brief>
+      <description><![CDATA[
+Gets the specified `property` from the specified `window`. Properties are for
+example the window title (`WM_NAME`) or its minimum size (`WM_NORMAL_HINTS`).
+Protocols such as EWMH also use properties - for example EWMH defines the
+window title, encoded as UTF-8 string, in the `_NET_WM_NAME` property.
+
+TODO: talk about `type`
+
+TODO: talk about `delete`
+
+TODO: talk about the offset/length thing. what's a valid use case?
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Prints the WM_NAME property of the window.
+ *
+ */
+void my_example(xcb_connection *c, xcb_window_t window) {
+    xcb_get_property_cookie_t cookie;
+    xcb_get_property_reply_t *reply;
+
+    /* These atoms are predefined in the X11 protocol. */
+    xcb_atom_t property = XCB_ATOM_WM_NAME;
+    xcb_atom_t type = XCB_ATOM_STRING;
+
+    // TODO: a reasonable long_length for WM_NAME?
+    cookie = xcb_get_property(c, 0, window, property, type, 0, 0);
+    if ((reply = xcb_get_property_reply(c, cookie, NULL))) {
+        int len = xcb_get_property_value_length(reply);
+        if (len == 0) {
+            printf("TODO\\n");
+            free(reply);
+            return;
+        }
+        printf("WM_NAME is %.*s\\n", len,
+               (char*)xcb_get_property_value(reply));
+    }
+    free(reply);
+}
+      ]]></example>
+      <field name="window"><![CDATA[
+The window whose property you want to get.
+      ]]></field>
+      <field name="delete"><![CDATA[
+Whether the property should actually be deleted. For deleting a property, the
+specified `type` has to match the actual property type.
+      ]]></field>
+      <field name="property"><![CDATA[
+The property you want to get (an atom).
+      ]]></field>
+      <field name="type"><![CDATA[
+The type of the property you want to get (an atom).
+      ]]></field>
+      <field name="long_offset"><![CDATA[
+Specifies the offset (in 32-bit multiples) in the specified property where the
+data is to be retrieved.
+      ]]></field>
+      <field name="long_length"><![CDATA[
+Specifies how many 32-bit multiples of data should be retrieved (e.g. if you
+set `long_length` to 4, you will receive 16 bytes of data).
+      ]]></field>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+      <error type="Atom"><![CDATA[
+`property` or `type` do not refer to a valid atom.
+      ]]></error>
+      <error type="Value"><![CDATA[
+The specified `long_offset` is beyond the actual property length (e.g. the
+property has a length of 3 bytes and you are setting `long_offset` to 1,
+resulting in a byte offset of 4).
+      ]]></error>
+      <see type="request" name="InternAtom" />
+      <see type="program" name="xprop" />
+    </doc>
   </request>
 
   <request name="ListProperties" opcode="21">
@@ -1086,6 +2222,38 @@ authorization from the authors.
     <field type="WINDOW" name="owner" altenum="Window" />
     <field type="ATOM" name="selection" />
     <field type="TIMESTAMP" name="time" altenum="Time" />
+    <doc>
+      <brief>Sets the owner of a selection</brief>
+      <description><![CDATA[
+Makes `window` the owner of the selection `selection` and updates the
+last-change time of the specified selection.
+
+TODO: briefly explain what a selection is.
+      ]]></description>
+      <field name="selection"><![CDATA[
+The selection.
+      ]]></field>
+      <field name="owner"><![CDATA[
+The new owner of the selection.
+
+The special value `XCB_NONE` means that the selection will have no owner.
+      ]]></field>
+      <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The selection will not be changed if `time` is earlier than the current
+last-change time of the `selection` or is later than the current X server time.
+Otherwise, the last-change time is set to the specified time.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+      ]]></field>
+      <error type="Atom"><![CDATA[
+`selection` does not refer to a valid atom.
+      ]]></error>
+      <see type="request" name="SetSelectionOwner" />
+    </doc>
+
   </request>
 
   <request name="GetSelectionOwner" opcode="23">
@@ -1094,7 +2262,27 @@ authorization from the authors.
     <reply>
       <pad bytes="1" />
       <field type="WINDOW" name="owner" altenum="Window" />
+      <doc>
+        <field name="owner"><![CDATA[
+The current selection owner window.
+        ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>Gets the owner of a selection</brief>
+      <description><![CDATA[
+Gets the owner of the specified selection.
+
+TODO: briefly explain what a selection is.
+      ]]></description>
+      <field name="selection"><![CDATA[
+The selection.
+      ]]></field>
+      <error type="Atom"><![CDATA[
+`selection` does not refer to a valid atom.
+      ]]></error>
+      <see type="request" name="SetSelectionOwner" />
+    </doc>
   </request>
 
   <request name="ConvertSelection" opcode="24">
@@ -1116,11 +2304,97 @@ authorization from the authors.
     <field type="WINDOW" name="destination" altenum="SendEventDest" />
     <field type="CARD32" name="event_mask" mask="EventMask" />
     <list type="char" name="event"><value>32</value></list>
+    <doc>
+      <brief>send an event</brief>
+      <description><![CDATA[
+Identifies the `destination` window, determines which clients should receive
+the specified event and ignores any active grabs.
+
+The `event` must be one of the core events or an event defined by an extension,
+so that the X server can correctly byte-swap the contents as necessary. The
+contents of `event` are otherwise unaltered and unchecked except for the
+`send_event` field which is forced to 'true'.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Tell the given window that it was configured to a size of 800x600 pixels.
+ *
+ */
+void my_example(xcb_connection_t *conn, xcb_window_t window) {
+    /* Every X11 event is 32 bytes long. Therefore, XCB will copy 32 bytes.
+     * In order to properly initialize these bytes, we allocate 32 bytes even
+     * though we only need less for an xcb_configure_notify_event_t */
+    xcb_configure_notify_event_t *event = calloc(32, 1);
+
+    event->event = window;
+    event->window = window;
+    event->response_type = XCB_CONFIGURE_NOTIFY;
+
+    event->x = 0;
+    event->y = 0;
+    event->width = 800;
+    event->height = 600;
+
+    event->border_width = 0;
+    event->above_sibling = XCB_NONE;
+    event->override_redirect = false;
+
+    xcb_send_event(conn, false, window, XCB_EVENT_MASK_STRUCTURE_NOTIFY,
+                   (char*)event);
+    xcb_flush(conn);
+    free(event);
+}
+      ]]></example>
+      <field name="destination"><![CDATA[
+The window to send this event to. Every client which selects any event within
+`event_mask` on `destination` will get the event.
+
+The special value `XCB_SEND_EVENT_DEST_POINTER_WINDOW` refers to the window
+that contains the mouse pointer.
+
+The special value `XCB_SEND_EVENT_DEST_ITEM_FOCUS` refers to the window which
+has the keyboard focus.
+      ]]></field>
+      <field name="event_mask"><![CDATA[
+Event_mask for determining which clients should receive the specified event.
+See `destination` and `propagate`.
+      ]]></field>
+      <field name="propagate"><![CDATA[
+If `propagate` is true and no clients have selected any event on `destination`,
+the destination is replaced with the closest ancestor of `destination` for
+which some client has selected a type in `event_mask` and for which no
+intervening window has that type in its do-not-propagate-mask. If no such
+window exists or if the window is an ancestor of the focus window and
+`InputFocus` was originally specified as the destination, the event is not sent
+to any clients. Otherwise, the event is reported to every client selecting on
+the final destination any of the types specified in `event_mask`.
+      ]]></field>
+      <field name="event"><![CDATA[
+The event to send to the specified `destination`.
+      ]]></field>
+      <error type="Window"><![CDATA[
+The specified `destination` window does not exist.
+      ]]></error>
+      <error type="Value"><![CDATA[
+The given `event` is neither a core event nor an event defined by an extension.
+      ]]></error>
+      <see type="event" name="ConfigureNotify" />
+    </doc>
   </request>
 
   <enum name="GrabMode">
     <item name="Sync"> <value>0</value></item>
     <item name="Async"><value>1</value></item>
+    <doc>
+      <field name="Sync"><![CDATA[
+The state of the keyboard appears to freeze: No further keyboard events are
+generated by the server until the grabbing client issues a releasing
+`AllowEvents` request or until the keyboard grab is released.
+      ]]></field>
+      <field name="Async"><![CDATA[
+Keyboard event processing continues normally.
+      ]]></field>
+    </doc>
   </enum>
 
   <enum name="GrabStatus">
@@ -1147,11 +2421,118 @@ authorization from the authors.
     <reply>
       <field type="BYTE" name="status" enum="GrabStatus" />
     </reply>
+    <doc>
+      <brief>Grab the pointer</brief>
+      <description><![CDATA[
+Actively grabs control of the pointer. Further pointer events are reported only to the grabbing client. Overrides any active pointer grab by this client.
+
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Grabs the pointer actively
+ *
+ */
+void my_example(xcb_connection *conn, xcb_screen_t *screen, xcb_cursor_t cursor) {
+    xcb_grab_pointer_cookie_t cookie;
+    xcb_grab_pointer_reply_t *reply;
+
+    cookie = xcb_grab_pointer(
+        conn,
+        false,               /* get all pointer events specified by the following mask */
+        screen->root,        /* grab the root window */
+        XCB_NONE,            /* which events to let through */
+        XCB_GRAB_MODE_ASYNC, /* pointer events should continue as normal */
+        XCB_GRAB_MODE_ASYNC, /* keyboard mode */
+        XCB_NONE,            /* confine_to = in which window should the cursor stay */
+        cursor,              /* we change the cursor to whatever the user wanted */
+        XCB_CURRENT_TIME
+    );
+
+    if ((reply = xcb_grab_pointer_reply(conn, cookie, NULL))) {
+        if (reply->status == XCB_GRAB_STATUS_SUCCESS)
+            printf("successfully grabbed the pointer\\n");
+        free(preply);
+    }
+}
+      ]]></example>
+      <field name="event_mask"><![CDATA[
+Specifies which pointer events are reported to the client.
+
+TODO: which values?
+      ]]></field>
+      <field name="confine_to"><![CDATA[
+Specifies the window to confine the pointer in (the user will not be able to
+move the pointer out of that window).
+
+The special value `XCB_NONE` means don't confine the pointer.
+      ]]></field>
+      <field name="cursor"><![CDATA[
+Specifies the cursor that should be displayed or `XCB_NONE` to not change the
+cursor.
+      ]]></field>
+      <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+      ]]></field>
+      <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+      ]]></field>
+      <field name="time"><![CDATA[
+The time argument allows you to avoid certain circumstances that come up if
+applications take a long time to respond or if there are long network delays.
+Consider a situation where you have two applications, both of which normally
+grab the pointer when clicked on. If both applications specify the timestamp
+from the event, the second application may wake up faster and successfully grab
+the pointer before the first application. The first application then will get
+an indication that the other application grabbed the pointer before its request
+was processed.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+      ]]></field>
+      <!-- the enum doc is sufficient. -->
+      <field name="pointer_mode" />
+      <field name="keyboard_mode" />
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+
+      <see type="request" name="GrabKeyboard" />
+    </doc>
   </request>
 
   <request name="UngrabPointer" opcode="27">
     <pad bytes="1" />
     <field type="TIMESTAMP" name="time" altenum="Time" />
+    <doc>
+      <brief>release the pointer</brief>
+      <description><![CDATA[
+Releases the pointer and any queued events if you actively grabbed the pointer
+before using `xcb_grab_pointer`, `xcb_grab_button` or within a normal button
+press.
+
+EnterNotify and LeaveNotify events are generated.
+      ]]></description>
+      <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The pointer will not be released if `time` is earlier than the
+last-pointer-grab time or later than the current X server time.
+      ]]></field>
+      <field name="name_len"><![CDATA[
+Length (in bytes) of `name`.
+      ]]></field>
+      <field name="name"><![CDATA[
+A pattern describing an X core font.
+      ]]></field>
+      <see type="request" name="GrabPointer" />
+      <see type="request" name="GrabButton" />
+      <see type="event" name="EnterNotify" />
+      <see type="event" name="LeaveNotify" />
+    </doc>
   </request>
 
   <enum name="ButtonIndex">
@@ -1161,6 +2542,26 @@ authorization from the authors.
      <item name="3">  <value>3</value></item>
      <item name="4">  <value>4</value></item>
      <item name="5">  <value>5</value></item>
+    <doc>
+      <field name="Any"><![CDATA[
+Any of the following (or none):
+      ]]></field>
+      <field name="1"><![CDATA[
+The left mouse button.
+      ]]></field>
+      <field name="2"><![CDATA[
+The right mouse button.
+      ]]></field>
+      <field name="3"><![CDATA[
+The middle mouse button.
+      ]]></field>
+      <field name="4"><![CDATA[
+Scroll wheel. TODO: direction?
+      ]]></field>
+      <field name="5"><![CDATA[
+Scroll wheel. TODO: direction?
+      ]]></field>
+    </doc>
   </enum>
 
   <request name="GrabButton" opcode="28">
@@ -1174,6 +2575,92 @@ authorization from the authors.
     <field type="CARD8" name="button" enum="ButtonIndex" />
     <pad bytes="1" />
     <field type="CARD16" name="modifiers" mask="ModMask" />
+    <doc>
+      <brief>Grab pointer button(s)</brief>
+      <description><![CDATA[
+This request establishes a passive grab. The pointer is actively grabbed as
+described in GrabPointer, the last-pointer-grab time is set to the time at
+which the button was pressed (as transmitted in the ButtonPress event), and the
+ButtonPress event is reported if all of the following conditions are true:
+
+The pointer is not grabbed and the specified button is logically pressed when
+the specified modifier keys are logically down, and no other buttons or
+modifier keys are logically down.
+
+The grab-window contains the pointer.
+
+The confine-to window (if any) is viewable.
+
+A passive grab on the same button/key combination does not exist on any
+ancestor of grab-window.
+
+The interpretation of the remaining arguments is the same as for GrabPointer.
+The active grab is terminated automatically when the logical state of the
+pointer has all buttons released, independent of the logical state of modifier
+keys. Note that the logical state of a device (as seen by means of the
+protocol) may lag the physical state if device event processing is frozen. This
+request overrides all previous passive grabs by the same client on the same
+button/key combinations on the same window. A modifier of AnyModifier is
+equivalent to issuing the request for all possible modifier combinations
+(including the combination of no modifiers). It is not required that all
+specified modifiers have currently assigned keycodes. A button of AnyButton is
+equivalent to issuing the request for all possible buttons. Otherwise, it is
+not required that the button specified currently be assigned to a physical
+button.
+
+An Access error is generated if some other client has already issued a
+GrabButton request with the same button/key combination on the same window.
+When using AnyModifier or AnyButton, the request fails completely (no grabs are
+established), and an Access error is generated if there is a conflicting grab
+for any combination. The request has no effect on an active grab.
+
+      ]]></description>
+      <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+      ]]></field>
+      <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+      ]]></field>
+      <field name="event_mask"><![CDATA[
+Specifies which pointer events are reported to the client.
+
+TODO: which values?
+      ]]></field>
+      <field name="confine_to"><![CDATA[
+Specifies the window to confine the pointer in (the user will not be able to
+move the pointer out of that window).
+
+The special value `XCB_NONE` means don't confine the pointer.
+      ]]></field>
+      <field name="cursor"><![CDATA[
+Specifies the cursor that should be displayed or `XCB_NONE` to not change the
+cursor.
+      ]]></field>
+      <field name="modifiers"><![CDATA[
+The modifiers to grab.
+
+Using the special value `XCB_MOD_MASK_ANY` means grab the pointer with all
+possible modifier combinations.
+      ]]></field>
+      <!-- the enum doc is sufficient. -->
+      <field name="pointer_mode" />
+      <field name="keyboard_mode" />
+      <field name="button" />
+      <error type="Access"><![CDATA[
+Another client has already issued a GrabButton with the same button/key
+combination on the same window.
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Cursor"><![CDATA[
+The specified `cursor` does not exist.
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+    </doc>
   </request>
 
   <request name="UngrabButton" opcode="29">
@@ -1201,6 +2688,70 @@ authorization from the authors.
     <reply>
       <field type="BYTE" name="status" enum="GrabStatus" />
     </reply>
+    <doc>
+      <brief>Grab the keyboard</brief>
+      <description><![CDATA[
+Actively grabs control of the keyboard and generates FocusIn and FocusOut
+events. Further key events are reported only to the grabbing client.
+
+Any active keyboard grab by this client is overridden. If the keyboard is
+actively grabbed by some other client, `AlreadyGrabbed` is returned. If
+`grab_window` is not viewable, `GrabNotViewable` is returned. If the keyboard
+is frozen by an active grab of another client, `GrabFrozen` is returned. If the
+specified `time` is earlier than the last-keyboard-grab time or later than the
+current X server time, `GrabInvalidTime` is returned. Otherwise, the
+last-keyboard-grab time is set to the specified time.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Grabs the keyboard actively
+ *
+ */
+void my_example(xcb_connection *conn, xcb_screen_t *screen) {
+    xcb_grab_keyboard_cookie_t cookie;
+    xcb_grab_keyboard_reply_t *reply;
+
+    cookie = xcb_grab_keyboard(
+        conn,
+        true,                /* report events */
+        screen->root,        /* grab the root window */
+        XCB_CURRENT_TIME,
+        XCB_GRAB_MODE_ASYNC, /* process events as normal, do not require sync */
+        XCB_GRAB_MODE_ASYNC
+    );
+
+    if ((reply = xcb_grab_keyboard_reply(conn, cookie, NULL))) {
+        if (reply->status == XCB_GRAB_STATUS_SUCCESS)
+            printf("successfully grabbed the keyboard\\n");
+
+        free(reply);
+    }
+}
+      ]]></example>
+      <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+      ]]></field>
+      <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+      ]]></field>
+      <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+      ]]></field>
+      <!-- the enum doc is sufficient. -->
+      <field name="pointer_mode" />
+      <field name="keyboard_mode" />
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+      <see type="request" name="GrabPointer" />
+    </doc>
   </request>
 
   <request name="UngrabKeyboard" opcode="32">
@@ -1221,6 +2772,78 @@ authorization from the authors.
     <field type="CARD8" name="pointer_mode" enum="GrabMode" />
     <field type="CARD8" name="keyboard_mode" enum="GrabMode" />
     <pad bytes="3" />
+    <doc>
+      <brief>Grab keyboard key(s)</brief>
+      <description><![CDATA[
+Establishes a passive grab on the keyboard. In the future, the keyboard is
+actively grabbed (as for `GrabKeyboard`), the last-keyboard-grab time is set to
+the time at which the key was pressed (as transmitted in the KeyPress event),
+and the KeyPress event is reported if all of the following conditions are true:
+
+The keyboard is not grabbed and the specified key (which can itself be a
+modifier key) is logically pressed when the specified modifier keys are
+logically down, and no other modifier keys are logically down.
+
+Either the grab_window is an ancestor of (or is) the focus window, or the
+grab_window is a descendant of the focus window and contains the pointer.
+
+A passive grab on the same key combination does not exist on any ancestor of
+grab_window.
+
+The interpretation of the remaining arguments is as for XGrabKeyboard.  The active grab is terminated
+automatically when the logical state of the keyboard has the specified key released (independent of the
+logical state of the modifier keys), at which point a KeyRelease event is reported to the grabbing window.
+
+Note that the logical state of a device (as seen by client applications) may lag the physical state if
+device event processing is frozen.
+
+A modifiers argument of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers).  It is not required that all modifiers specified
+have currently assigned KeyCodes.  A keycode argument of AnyKey is equivalent to issuing the request for
+all possible KeyCodes.  Otherwise, the specified keycode must be in the range specified by min_keycode
+and max_keycode in the connection setup, or a BadValue error results.
+
+If some other client has issued a XGrabKey with the same key combination on the same window, a BadAccess
+error results.  When using AnyModifier or AnyKey, the request fails completely, and a BadAccess error
+results (no grabs are established) if there is a conflicting grab for any combination.
+
+      ]]></description>
+      <field name="owner_events"><![CDATA[
+If 1, the `grab_window` will still get the pointer events. If 0, events are not
+reported to the `grab_window`.
+      ]]></field>
+      <field name="grab_window"><![CDATA[
+Specifies the window on which the pointer should be grabbed.
+      ]]></field>
+      <field name="key"><![CDATA[
+The keycode of the key to grab.
+
+The special value `XCB_GRAB_ANY` means grab any key.
+      ]]></field>
+      <field name="cursor"><![CDATA[
+Specifies the cursor that should be displayed or `XCB_NONE` to not change the
+cursor.
+      ]]></field>
+      <field name="modifiers"><![CDATA[
+The modifiers to grab.
+
+Using the special value `XCB_MOD_MASK_ANY` means grab the pointer with all
+possible modifier combinations.
+      ]]></field>
+      <!-- the enum doc is sufficient. -->
+      <field name="pointer_mode" />
+      <field name="keyboard_mode" />
+      <error type="Access"><![CDATA[
+Another client has already issued a GrabKey with the same button/key
+combination on the same window.
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+      <see type="request" name="GrabKeyboard" />
+    </doc>
   </request>
 
   <request name="UngrabKey" opcode="34">
@@ -1228,6 +2851,35 @@ authorization from the authors.
     <field type="WINDOW" name="grab_window" />
     <field type="CARD16" name="modifiers" mask="ModMask" />
     <pad bytes="2" />
+    <doc>
+      <brief>release a key combination</brief>
+      <description><![CDATA[
+Releases the key combination on `grab_window` if you grabbed it using
+`xcb_grab_key` before.
+      ]]></description>
+      <field name="key"><![CDATA[
+The keycode of the specified key combination.
+
+Using the special value `XCB_GRAB_ANY` means releasing all possible key codes.
+      ]]></field>
+      <field name="grab_window"><![CDATA[
+The window on which the grabbed key combination will be released.
+      ]]></field>
+      <field name="modifiers"><![CDATA[
+The modifiers of the specified key combination.
+
+Using the special value `XCB_MOD_MASK_ANY` means releasing the key combination
+with every possible modifier combination.
+      ]]></field>
+      <error type="Window"><![CDATA[
+The specified `grab_window` does not exist.
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <see type="request" name="GrabKey" />
+      <see type="program" name="xev" />
+    </doc>
   </request>
 
   <enum name="Allow">
@@ -1239,11 +2891,106 @@ authorization from the authors.
     <item name="ReplayKeyboard"><value>5</value></item>
     <item name="AsyncBoth">     <value>6</value></item>
     <item name="SyncBoth">      <value>7</value></item>
+    <doc>
+      <field name="AsyncPointer"><![CDATA[
+For AsyncPointer, if the pointer is frozen by the client, pointer event
+processing continues normally. If the pointer is frozen twice by the client on
+behalf of two separate grabs, AsyncPointer thaws for both. AsyncPointer has no
+effect if the pointer is not frozen by the client, but the pointer need not be
+grabbed by the client.
+
+TODO: rewrite this in more understandable terms.
+      ]]></field>
+      <field name="SyncPointer"><![CDATA[
+For SyncPointer, if the pointer is frozen and actively grabbed by the client,
+pointer event processing continues normally until the next ButtonPress or
+ButtonRelease event is reported to the client, at which time the pointer again
+appears to freeze. However, if the reported event causes the pointer grab to be
+released, then the pointer does not freeze. SyncPointer has no effect if the
+pointer is not frozen by the client or if the pointer is not grabbed by the
+client.
+      ]]></field>
+      <field name="ReplayPointer"><![CDATA[
+For ReplayPointer, if the pointer is actively grabbed by the client and is
+frozen as the result of an event having been sent to the client (either from
+the activation of a GrabButton or from a previous AllowEvents with mode
+SyncPointer but not from a GrabPointer), then the pointer grab is released and
+that event is completely reprocessed, this time ignoring any passive grabs at
+or above (towards the root) the grab-window of the grab just released. The
+request has no effect if the pointer is not grabbed by the client or if the
+pointer is not frozen as the result of an event.
+      ]]></field>
+      <field name="AsyncKeyboard"><![CDATA[
+For AsyncKeyboard, if the keyboard is frozen by the client, keyboard event
+processing continues normally. If the keyboard is frozen twice by the client on
+behalf of two separate grabs, AsyncKeyboard thaws for both. AsyncKeyboard has
+no effect if the keyboard is not frozen by the client, but the keyboard need
+not be grabbed by the client.
+      ]]></field>
+      <field name="SyncKeyboard"><![CDATA[
+For SyncKeyboard, if the keyboard is frozen and actively grabbed by the client,
+keyboard event processing continues normally until the next KeyPress or
+KeyRelease event is reported to the client, at which time the keyboard again
+appears to freeze. However, if the reported event causes the keyboard grab to
+be released, then the keyboard does not freeze. SyncKeyboard has no effect if
+the keyboard is not frozen by the client or if the keyboard is not grabbed by
+the client.
+      ]]></field>
+      <field name="ReplayKeyboard"><![CDATA[
+For ReplayKeyboard, if the keyboard is actively grabbed by the client and is
+frozen as the result of an event having been sent to the client (either from
+the activation of a GrabKey or from a previous AllowEvents with mode
+SyncKeyboard but not from a GrabKeyboard), then the keyboard grab is released
+and that event is completely reprocessed, this time ignoring any passive grabs
+at or above (towards the root) the grab-window of the grab just released. The
+request has no effect if the keyboard is not grabbed by the client or if the
+keyboard is not frozen as the result of an event.
+      ]]></field>
+      <field name="SyncBoth"><![CDATA[
+For SyncBoth, if both pointer and keyboard are frozen by the client, event
+processing (for both devices) continues normally until the next ButtonPress,
+ButtonRelease, KeyPress, or KeyRelease event is reported to the client for a
+grabbed device (button event for the pointer, key event for the keyboard), at
+which time the devices again appear to freeze. However, if the reported event
+causes the grab to be released, then the devices do not freeze (but if the
+other device is still grabbed, then a subsequent event for it will still cause
+both devices to freeze). SyncBoth has no effect unless both pointer and
+keyboard are frozen by the client. If the pointer or keyboard is frozen twice
+by the client on behalf of two separate grabs, SyncBoth thaws for both (but a
+subsequent freeze for SyncBoth will only freeze each device once).
+      ]]></field>
+      <field name="AsyncBoth"><![CDATA[
+For AsyncBoth, if the pointer and the keyboard are frozen by the client, event
+processing for both devices continues normally. If a device is frozen twice by
+the client on behalf of two separate grabs, AsyncBoth thaws for both. AsyncBoth
+has no effect unless both pointer and keyboard are frozen by the client.
+      ]]></field>
+    </doc>
   </enum>
 
   <request name="AllowEvents" opcode="35">
     <field type="CARD8" name="mode" enum="Allow" />
     <field type="TIMESTAMP" name="time" altenum="Time" />
+    <doc>
+      <brief>release queued events</brief>
+      <description><![CDATA[
+Releases queued events if the client has caused a device (pointer/keyboard) to
+freeze due to grabbing it actively. This request has no effect if `time` is
+earlier than the last-grab time of the most recent active grab for this client
+or if `time` is later than the current X server time.
+      ]]></description>
+      <!-- the enum doc is sufficient. -->
+      <field name="mode" />
+      <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+      ]]></field>
+      <error type="Value"><![CDATA[
+You specified an invalid `mode`.
+      ]]></error>
+    </doc>
   </request>
 
   <request name="GrabServer" opcode="36" />
@@ -1263,7 +3010,56 @@ authorization from the authors.
       <field type="INT16" name="win_y" />
       <field type="CARD16" name="mask" mask="KeyButMask" />
       <pad bytes="2" />
+      <doc>
+        <field name="same_screen"><![CDATA[
+If `same_screen` is False, then the pointer is not on the same screen as the
+argument window, `child` is None, and `win_x` and `win_y` are zero. If
+`same_screen` is True, then `win_x` and `win_y` are the pointer coordinates
+relative to the argument window's origin, and child is the child containing the
+pointer, if any.
+        ]]></field>
+        <field name="root"><![CDATA[
+The root window the pointer is logically on.
+        ]]></field>
+        <field name="child"><![CDATA[
+The child window containing the pointer, if any, if `same_screen` is true. If
+`same_screen` is false, `XCB_NONE` is returned.
+        ]]></field>
+        <field name="root_x"><![CDATA[
+The pointer X position, relative to `root`.
+        ]]></field>
+        <field name="root_y"><![CDATA[
+The pointer Y position, relative to `root`.
+        ]]></field>
+        <field name="win_x"><![CDATA[
+The pointer X coordinate, relative to `child`, if `same_screen` is true. Zero
+otherwise.
+        ]]></field>
+        <field name="win_y"><![CDATA[
+The pointer Y coordinate, relative to `child`, if `same_screen` is true. Zero
+otherwise.
+        ]]></field>
+        <field name="mask"><![CDATA[
+The current logical state of the modifier keys and the buttons. Note that the
+logical state of a device (as seen by means of the protocol) may lag the
+physical state if device event processing is frozen.
+        ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>get pointer coordinates</brief>
+      <description><![CDATA[
+Gets the root window the pointer is logically on and the pointer coordinates
+relative to the root window's origin.
+      ]]></description>
+      <field name="window"><![CDATA[
+A window to check if the pointer is on the same screen as `window` (see the
+`same_screen` field in the reply).
+      ]]></field>
+      <error type="Window"><![CDATA[
+The specified `window` does not exist.
+      ]]></error>
+    </doc>
   </request>
 
   <struct name="TIMECOORD">
@@ -1311,6 +3107,38 @@ authorization from the authors.
     <field type="CARD16" name="src_height" />
     <field type="INT16" name="dst_x" />
     <field type="INT16" name="dst_y" />
+    <doc>
+      <brief>move mouse pointer</brief>
+      <description><![CDATA[
+Moves the mouse pointer to the specified position.
+
+If `src_window` is not `XCB_NONE` (TODO), the move will only take place if the
+pointer is inside `src_window` and within the rectangle specified by (`src_x`,
+`src_y`, `src_width`, `src_height`). The rectangle coordinates are relative to
+`src_window`.
+
+If `dst_window` is not `XCB_NONE` (TODO), the pointer will be moved to the
+offsets (`dst_x`, `dst_y`) relative to `dst_window`. If `dst_window` is
+`XCB_NONE` (TODO), the pointer will be moved by the offsets (`dst_x`, `dst_y`)
+relative to the current position of the pointer.
+      ]]></description>
+      <field name="src_window"><![CDATA[
+If `src_window` is not `XCB_NONE` (TODO), the move will only take place if the
+pointer is inside `src_window` and within the rectangle specified by (`src_x`,
+`src_y`, `src_width`, `src_height`). The rectangle coordinates are relative to
+`src_window`.
+      ]]></field>
+      <field name="dst_window"><![CDATA[
+If `dst_window` is not `XCB_NONE` (TODO), the pointer will be moved to the
+offsets (`dst_x`, `dst_y`) relative to `dst_window`. If `dst_window` is
+`XCB_NONE` (TODO), the pointer will be moved by the offsets (`dst_x`, `dst_y`)
+relative to the current position of the pointer.
+      ]]></field>
+      <error type="Window"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <see type="request" name="SetInputFocus" />
+    </doc>
   </request>
 
   <!-- used for revert_to and focus -->
@@ -1319,12 +3147,71 @@ authorization from the authors.
     <item name="PointerRoot"><value>1</value></item>
     <item name="Parent">     <value>2</value></item>  <!-- revert_to only -->
     <item name="FollowKeyboard"><value>3</value></item>  <!-- xinput extension only -->
+    <doc>
+      <field name="None"><![CDATA[
+The focus reverts to `XCB_NONE`, so no window will have the input focus.
+      ]]></field>
+      <field name="PointerRoot"><![CDATA[
+The focus reverts to `XCB_POINTER_ROOT` respectively. When the focus reverts,
+FocusIn and FocusOut events are generated, but the last-focus-change time is
+not changed.
+      ]]></field>
+      <field name="Parent"><![CDATA[
+The focus reverts to the parent (or closest viewable ancestor) and the new
+revert_to value is `XCB_INPUT_FOCUS_NONE`.
+      ]]></field>
+      <field name="FollowKeyboard"><![CDATA[
+NOT YET DOCUMENTED. Only relevant for the xinput extension.
+      ]]></field>
+    </doc>
   </enum>
 
   <request name="SetInputFocus" opcode="42">
     <field type="CARD8" name="revert_to" enum="InputFocus" />
     <field type="WINDOW" name="focus" altenum="InputFocus" />
     <field type="TIMESTAMP" name="time" altenum="Time" />
+    <doc>
+      <brief>Sets input focus</brief>
+      <description><![CDATA[
+Changes the input focus and the last-focus-change time. If the specified `time`
+is earlier than the current last-focus-change time, the request is ignored (to
+avoid race conditions when running X over the network).
+
+A FocusIn and FocusOut event is generated when focus is changed.
+      ]]></description>
+      <field name="focus"><![CDATA[
+The window to focus. All keyboard events will be reported to this window. The
+window must be viewable (TODO), or a `xcb_match_error_t` occurs (TODO).
+
+If `focus` is `XCB_NONE` (TODO), all keyboard events are
+discarded until a new focus window is set.
+
+If `focus` is `XCB_POINTER_ROOT` (TODO), focus is on the root window of the
+screen on which the pointer is on currently.
+      ]]></field>
+      <field name="time"><![CDATA[
+Timestamp to avoid race conditions when running X over the network.
+
+The special value `XCB_CURRENT_TIME` will be replaced with the current server
+time.
+      ]]></field>
+      <field name="revert_to"><![CDATA[
+Specifies what happens when the `focus` window becomes unviewable (if `focus`
+is neither `XCB_NONE` nor `XCB_POINTER_ROOT`).
+      ]]></field>
+      <error type="Window"><![CDATA[
+The specified `focus` window does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+The specified `focus` window is not viewable.
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: Reasons?
+      ]]></error>
+      <see type="event" name="FocusIn" />
+      <see type="event" name="FocusOut" />
+    </doc>
+
   </request>
 
   <request name="GetInputFocus" opcode="43">
@@ -1349,6 +3236,28 @@ authorization from the authors.
     <list type="char" name="name">
       <fieldref>name_len</fieldref>
     </list>
+    <doc>
+      <brief>opens a font</brief>
+      <description><![CDATA[
+Opens any X core font matching the given `name` (for example "-misc-fixed-*").
+
+Note that X core fonts are deprecated (but still supported) in favor of
+client-side rendering using Xft.
+      ]]></description>
+      <field name="fid"><![CDATA[
+The ID with which you will refer to the font, created by `xcb_generate_id`.
+      ]]></field>
+      <field name="name_len"><![CDATA[
+Length (in bytes) of `name`.
+      ]]></field>
+      <field name="name"><![CDATA[
+A pattern describing an X core font.
+      ]]></field>
+      <error type="Name"><![CDATA[
+No font matches the given `name`.
+      ]]></error>
+      <see type="function" name="xcb_generate_id" />
+    </doc>
   </request>
 
   <request name="CloseFont" opcode="46">
@@ -1401,7 +3310,48 @@ authorization from the authors.
       <list type="CHARINFO" name="char_infos">
         <fieldref>char_infos_len</fieldref>
       </list>
+      <doc>
+        <field name="min_bounds"><![CDATA[
+minimum bounds over all existing char
+        ]]></field>
+        <field name="max_bounds"><![CDATA[
+maximum bounds over all existing char
+        ]]></field>
+        <field name="min_char_or_byte2"><![CDATA[
+first character
+        ]]></field>
+        <field name="max_char_or_byte2"><![CDATA[
+last character
+        ]]></field>
+        <field name="default_char"><![CDATA[
+char to print for undefined character
+        ]]></field>
+        <field name="properties_len"><![CDATA[
+how many properties there are
+        ]]></field>
+        <field name="all_chars_exist"><![CDATA[
+flag if all characters have nonzero size
+        ]]></field>
+        <field name="font_ascent"><![CDATA[
+baseline to top edge of raster
+        ]]></field>
+        <field name="font_descent"><![CDATA[
+baseline to bottom edge of raster
+        ]]></field>
+        <!-- enum doc is sufficient -->
+        <field name="draw_direction" />
+      </doc>
     </reply>
+    <doc>
+      <brief>query font metrics</brief>
+      <description><![CDATA[
+Queries information associated with the font.
+      ]]></description>
+      <field name="font"><![CDATA[
+The fontable (Font or Graphics Context) to query.
+      ]]></field>
+      <!-- TODO: example -->
+    </doc>
   </request>
 
   <request name="QueryTextExtents" opcode="48">
@@ -1420,6 +3370,47 @@ authorization from the authors.
       <field type="INT32" name="overall_left" />
       <field type="INT32" name="overall_right" />
     </reply>
+    <doc>
+      <brief>get text extents</brief>
+      <description><![CDATA[
+Query text extents from the X11 server. This request returns the bounding box
+of the specified 16-bit character string in the specified `font` or the font
+contained in the specified graphics context.
+
+`font_ascent` is set to the maximum of the ascent metrics of all characters in
+the string. `font_descent` is set to the maximum of the descent metrics.
+`overall_width` is set to the sum of the character-width metrics of all
+characters in the string. For each character in the string, let W be the sum of
+the character-width metrics of all characters preceding it in the string. Let L
+be the left-side-bearing metric of the character plus W. Let R be the
+right-side-bearing metric of the character plus W. The lbearing member is set
+to the minimum L of all characters in the string. The rbearing member is set to
+the maximum R.
+
+For fonts defined with linear indexing rather than 2-byte matrix indexing, each
+`xcb_char2b_t` structure is interpreted as a 16-bit number with byte1 as the
+most significant byte. If the font has no defined default character, undefined
+characters in the string are taken to have all zero metrics.
+
+Characters with all zero metrics are ignored. If the font has no defined
+default_char, the undefined characters in the string are also ignored.
+      ]]></description>
+      <field name="font"><![CDATA[
+The `font` to calculate text extents in. You can also pass a graphics context.
+      ]]></field>
+      <field name="string_len"><![CDATA[
+The number of characters in `string`.
+      ]]></field>
+      <field name="string"><![CDATA[
+The text to get text extents for.
+      ]]></field>
+      <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+      ]]></error>
+      <error type="Font"><![CDATA[
+The specified `font` does not exist.
+      ]]></error>
+    </doc>
   </request>
 
   <struct name="STR">
@@ -1443,7 +3434,31 @@ authorization from the authors.
       <list type="STR" name="names">
         <fieldref>names_len</fieldref>
       </list>
+      <doc>
+        <field name="names_len"><![CDATA[
+The number of font names.
+        ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>get matching font names</brief>
+      <description><![CDATA[
+Gets a list of available font names which match the given `pattern`.
+      ]]></description>
+      <field name="pattern_len"><![CDATA[
+The length (in bytes) of `pattern`.
+      ]]></field>
+      <field name="pattern"><![CDATA[
+A font pattern, for example "-misc-fixed-*".
+
+The asterisk (*) is a wildcard for any number of characters. The question mark
+(?) is a wildcard for a single character. Use of uppercase or lowercase does
+not matter.
+      ]]></field>
+      <field name="max_names"><![CDATA[
+The maximum number of fonts to be returned.
+      ]]></field>
+    </doc>
   </request>
 
   <request name="ListFontsWithInfo" opcode="50">
@@ -1476,7 +3491,66 @@ authorization from the authors.
       <list type="char" name="name">
         <fieldref>name_len</fieldref>
       </list>
+      <doc>
+        <field name="name_len"><![CDATA[
+The number of matched font names.
+        ]]></field>
+        <field name="min_bounds"><![CDATA[
+minimum bounds over all existing char
+        ]]></field>
+        <field name="max_bounds"><![CDATA[
+maximum bounds over all existing char
+        ]]></field>
+        <field name="min_char_or_byte2"><![CDATA[
+first character
+        ]]></field>
+        <field name="max_char_or_byte2"><![CDATA[
+last character
+        ]]></field>
+        <field name="default_char"><![CDATA[
+char to print for undefined character
+        ]]></field>
+        <field name="properties_len"><![CDATA[
+how many properties there are
+        ]]></field>
+        <field name="all_chars_exist"><![CDATA[
+flag if all characters have nonzero size
+        ]]></field>
+        <field name="font_ascent"><![CDATA[
+baseline to top edge of raster
+        ]]></field>
+        <field name="font_descent"><![CDATA[
+baseline to bottom edge of raster
+        ]]></field>
+        <field name="replies_hint"><![CDATA[
+An indication of how many more fonts will be returned. This is only a hint and
+may be larger or smaller than the number of fonts actually returned. A zero
+value does not guarantee that no more fonts will be returned.
+        ]]></field>
+        <!-- enum doc is sufficient -->
+        <field name="draw_direction" />
+      </doc>
     </reply>
+    <doc>
+      <brief>get matching font names and information</brief>
+      <description><![CDATA[
+Gets a list of available font names which match the given `pattern`.
+      ]]></description>
+      <field name="pattern_len"><![CDATA[
+The length (in bytes) of `pattern`.
+      ]]></field>
+      <field name="pattern"><![CDATA[
+A font pattern, for example "-misc-fixed-*".
+
+The asterisk (*) is a wildcard for any number of characters. The question mark
+(?) is a wildcard for a single character. Use of uppercase or lowercase does
+not matter.
+      ]]></field>
+      <field name="max_names"><![CDATA[
+The maximum number of fonts to be returned.
+      ]]></field>
+    </doc>
+
   </request>
 
   <request name="SetFontPath" opcode="51">
@@ -1505,11 +3579,55 @@ authorization from the authors.
     <field type="DRAWABLE" name="drawable" />
     <field type="CARD16" name="width" />
     <field type="CARD16" name="height" />
+    <doc>
+      <brief>Creates a pixmap</brief>
+      <description><![CDATA[
+Creates a pixmap. The pixmap can only be used on the same screen as `drawable`
+is on and only with drawables of the same `depth`.
+      ]]></description>
+      <field name="depth"><![CDATA[
+TODO
+      ]]></field>
+      <field name="pid"><![CDATA[
+The ID with which you will refer to the new pixmap, created by
+`xcb_generate_id`.
+      ]]></field>
+      <field name="drawable"><![CDATA[
+Drawable to get the screen from.
+      ]]></field>
+      <field name="width"><![CDATA[
+The width of the new pixmap.
+      ]]></field>
+      <field name="height"><![CDATA[
+The height of the new pixmap.
+      ]]></field>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+      ]]></error>
+      <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+      ]]></error>
+      <see type="function" name="xcb_generate_id" />
+    </doc>
   </request>
 
   <request name="FreePixmap" opcode="54">
     <pad bytes="1" />
     <field type="PIXMAP" name="pixmap" />
+    <doc>
+      <brief>Destroys a pixmap</brief>
+      <description><![CDATA[
+Deletes the association between the pixmap ID and the pixmap. The pixmap
+storage will be freed when there are no more references to it.
+      ]]></description>
+      <field name="pixmap"><![CDATA[The pixmap to destroy.]]></field>
+      <error type="Pixmap"><![CDATA[
+The specified pixmap does not exist.
+      ]]></error>
+    </doc>
   </request>
   
   <enum name="GC">
@@ -1536,6 +3654,154 @@ authorization from the authors.
     <item name="DashOffset">        <bit>20</bit></item>
     <item name="DashList">          <bit>21</bit></item>
     <item name="ArcMode">           <bit>22</bit></item>
+    <doc>
+      <field name="Function"><![CDATA[
+TODO: Refer to GX
+      ]]></field>
+      <field name="PlaneMask"><![CDATA[
+In graphics operations, given a source and destination pixel, the result is
+computed bitwise on corresponding bits of the pixels; that is, a Boolean
+operation is performed in each bit plane. The plane-mask restricts the
+operation to a subset of planes, so the result is:
+
+        ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
+      ]]></field>
+      <field name="Foreground"><![CDATA[
+Foreground colorpixel.
+      ]]></field>
+      <field name="Background"><![CDATA[
+Background colorpixel.
+      ]]></field>
+      <field name="LineWidth"><![CDATA[
+The line-width is measured in pixels and can be greater than or equal to one, a wide line, or the
+special value zero, a thin line.
+      ]]></field>
+      <field name="LineStyle"><![CDATA[
+The line-style defines which sections of a line are drawn:
+Solid                The full path of the line is drawn.
+DoubleDash           The full path of the line is drawn, but the even dashes are filled differently
+                     than the odd dashes (see fill-style), with Butt cap-style used where even and
+                     odd dashes meet.
+OnOffDash            Only the even dashes are drawn, and cap-style applies to all internal ends of
+                     the individual dashes (except NotLast is treated as Butt).
+      ]]></field>
+      <field name="CapStyle"><![CDATA[
+The cap-style defines how the endpoints of a path are drawn:
+NotLast    The result is equivalent to Butt, except that for a line-width of zero the final
+           endpoint is not drawn.
+Butt       The result is square at the endpoint (perpendicular to the slope of the line)
+           with no projection beyond.
+Round      The result is a circular arc with its diameter equal to the line-width, centered
+           on the endpoint; it is equivalent to Butt for line-width zero.
+Projecting The result is square at the end, but the path continues beyond the endpoint for
+           a distance equal to half the line-width; it is equivalent to Butt for line-width
+           zero.
+      ]]></field>
+      <field name="JoinStyle"><![CDATA[
+The join-style defines how corners are drawn for wide lines:
+Miter               The outer edges of the two lines extend to meet at an angle. However, if the
+                    angle is less than 11 degrees, a Bevel join-style is used instead.
+Round               The result is a circular arc with a diameter equal to the line-width, centered
+                    on the joinpoint.
+Bevel               The result is Butt endpoint styles, and then the triangular notch is filled.
+      ]]></field>
+      <field name="FillStyle"><![CDATA[
+The fill-style defines the contents of the source for line, text, and fill requests. For all text and fill
+requests (for example, PolyText8, PolyText16, PolyFillRectangle, FillPoly, and PolyFillArc)
+as well as for line requests with line-style Solid, (for example, PolyLine, PolySegment,
+PolyRectangle, PolyArc) and for the even dashes for line requests with line-style OnOffDash
+or DoubleDash:
+Solid                     Foreground
+Tiled                     Tile
+OpaqueStippled            A tile with the same width and height as stipple but with background
+                          everywhere stipple has a zero and with foreground everywhere stipple
+                          has a one
+Stippled                  Foreground masked by stipple
+For the odd dashes for line requests with line-style DoubleDash:
+Solid                     Background
+Tiled                     Same as for even dashes
+OpaqueStippled            Same as for even dashes
+Stippled                  Background masked by stipple
+      ]]></field>
+      <field name="FillRule"><![CDATA[
+      ]]></field>
+      <field name="Tile"><![CDATA[
+The tile/stipple represents an infinite two-dimensional plane with the tile/stipple replicated in all
+dimensions. When that plane is superimposed on the drawable for use in a graphics operation,
+the upper-left corner of some instance of the tile/stipple is at the coordinates within the drawable
+specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics request.
+The tile pixmap must have the same root and depth as the gcontext (or a Match error results).
+The stipple pixmap must have depth one and must have the same root as the gcontext (or a
+Match error results). For fill-style Stippled (but not fill-style
+OpaqueStippled), the stipple pattern is tiled in a single plane and acts as an
+additional clip mask to be ANDed with the clip-mask.
+Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than
+others.
+      ]]></field>
+      <field name="Stipple"><![CDATA[
+The tile/stipple represents an infinite two-dimensional plane with the tile/stipple replicated in all
+dimensions. When that plane is superimposed on the drawable for use in a graphics operation,
+the upper-left corner of some instance of the tile/stipple is at the coordinates within the drawable
+specified by the tile/stipple origin. The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics request.
+The tile pixmap must have the same root and depth as the gcontext (or a Match error results).
+The stipple pixmap must have depth one and must have the same root as the gcontext (or a
+Match error results). For fill-style Stippled (but not fill-style
+OpaqueStippled), the stipple pattern is tiled in a single plane and acts as an
+additional clip mask to be ANDed with the clip-mask.
+Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than
+others.
+      ]]></field>
+      <field name="TileStippleOriginX"><![CDATA[
+TODO
+      ]]></field>
+      <field name="TileStippleOriginY"><![CDATA[
+TODO
+      ]]></field>
+      <field name="Font"><![CDATA[
+Which font to use for the `ImageText8` and `ImageText16` requests.
+      ]]></field>
+      <field name="SubwindowMode"><![CDATA[
+For ClipByChildren, both source and destination windows are additionally
+clipped by all viewable InputOutput children. For IncludeInferiors, neither
+source nor destination window is
+clipped by inferiors. This will result in including subwindow contents in the source and drawing
+through subwindow boundaries of the destination. The use of IncludeInferiors with a source or
+destination window of one depth with mapped inferiors of differing depth is not illegal, but the
+semantics is undefined by the core protocol.
+      ]]></field>
+      <field name="GraphicsExposures"><![CDATA[
+Whether ExposureEvents should be generated (1) or not (0).
+
+The default is 1.
+      ]]></field>
+      <field name="ClipOriginX"><![CDATA[
+TODO
+      ]]></field>
+      <field name="ClipOriginY"><![CDATA[
+TODO
+      ]]></field>
+      <field name="ClipMask"><![CDATA[
+The clip-mask restricts writes to the destination drawable. Only pixels where the clip-mask has
+bits set to 1 are drawn. Pixels are not drawn outside the area covered by the clip-mask or where
+the clip-mask has bits set to 0. The clip-mask affects all graphics requests, but it does not clip
+sources. The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. If a pixmap is specified as the clip-mask, it must have
+depth 1 and have the same root as the gcontext (or a Match error results). If clip-mask is None,
+then pixels are always drawn, regardless of the clip origin. The clip-mask can also be set with the
+SetClipRectangles request.
+      ]]></field>
+      <field name="DashOffset"><![CDATA[
+TODO
+      ]]></field>
+      <field name="DashList"><![CDATA[
+TODO
+      ]]></field>
+      <field name="ArcMode"><![CDATA[
+TODO
+      ]]></field>
+    </doc>
+
   </enum>
 
   <!-- GC Function values -->
@@ -1606,6 +3872,39 @@ authorization from the authors.
     <valueparam value-mask-type="CARD32"
                 value-mask-name="value_mask"
                 value-list-name="value_list" />
+    <doc>
+      <brief>Creates a graphics context</brief>
+      <description><![CDATA[
+Creates a graphics context. The graphics context can be used with any drawable
+that has the same root and depth as the specified drawable.
+      ]]></description>
+      <field name="cid"><![CDATA[
+The ID with which you will refer to the graphics context, created by
+`xcb_generate_id`.
+      ]]></field>
+      <field name="drawable"><![CDATA[
+Drawable to get the root/depth from.
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Font"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Pixmap"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+      ]]></error>
+      <see type="function" name="xcb_generate_id" />
+    </doc>
   </request>
 
   <request name="ChangeGC" opcode="56">
@@ -1614,6 +3913,62 @@ authorization from the authors.
     <valueparam value-mask-type="CARD32"
                 value-mask-name="value_mask"
                 value-list-name="value_list" />
+    <doc>
+      <brief>change graphics context components</brief>
+      <description><![CDATA[
+Changes the components specified by `value_mask` for the specified graphics context.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Changes the foreground color component of the specified graphics context.
+ *
+ */
+void my_example(xcb_connection *conn, xcb_gcontext_t gc, uint32_t fg, uint32_t bg) {
+    /* C99 allows us to use a compact way of changing a single component: */
+    xcb_change_gc(conn, gc, XCB_GC_FOREGROUND, (uint32_t[]){ fg });
+
+    /* The more explicit way. Beware that the order of values is important! */
+    uint32_t mask = 0;
+    mask |= XCB_GC_FOREGROUND;
+    mask |= XCB_GC_BACKGROUND;
+
+    uint32_t values[] = {
+        fg,
+        bg
+    };
+    xcb_change_gc(conn, gc, mask, values);
+    xcb_flush(conn);
+}
+      ]]></example>
+      <field name="gc"><![CDATA[
+The graphics context to change.
+      ]]></field>
+      <!-- the enum documentation is good enough. -->
+      <field name="value_mask" />
+      <field name="value_list"><![CDATA[
+Values for each of the components 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="Font"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="GC"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Pixmap"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+      ]]></error>
+    </doc>
   </request>
 
   <request name="CopyGC" opcode="57">
@@ -1651,6 +4006,16 @@ authorization from the authors.
   <request name="FreeGC" opcode="60">
     <pad bytes="1" />
     <field type="GCONTEXT" name="gc" />
+    <doc>
+      <brief>Destroys a graphics context</brief>
+      <description><![CDATA[
+Destroys the specified `gc` and all associated storage.
+      ]]></description>
+      <field name="gc"><![CDATA[The graphics context to destroy.]]></field>
+      <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+      ]]></error>
+    </doc>
   </request>
 
   <request name="ClearArea" opcode="61">
@@ -1673,6 +4038,48 @@ authorization from the authors.
     <field type="INT16" name="dst_y" />
     <field type="CARD16" name="width" />
     <field type="CARD16" name="height" />
+    <doc>
+      <brief>copy areas</brief>
+      <description><![CDATA[
+Copies the specified rectangle from `src_drawable` to `dst_drawable`.
+      ]]></description>
+      <field name="dst_drawable"><![CDATA[
+The destination drawable (Window or Pixmap).
+      ]]></field>
+      <field name="src_drawable"><![CDATA[
+The source drawable (Window or Pixmap).
+      ]]></field>
+      <field name="gc"><![CDATA[
+The graphics context to use.
+      ]]></field>
+      <field name="src_x"><![CDATA[
+The source X coordinate.
+      ]]></field>
+      <field name="src_y"><![CDATA[
+The source Y coordinate.
+      ]]></field>
+      <field name="dst_x"><![CDATA[
+The destination X coordinate.
+      ]]></field>
+      <field name="dst_y"><![CDATA[
+The destination Y coordinate.
+      ]]></field>
+      <field name="width"><![CDATA[
+The width of the area to copy (in pixels).
+      ]]></field>
+      <field name="height"><![CDATA[
+The height of the area to copy (in pixels).
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+      ]]></error>
+      <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+`src_drawable` has a different root or depth than `dst_drawable`.
+      ]]></error>
+    </doc>
   </request>
 
   <request name="CopyPlane" opcode="63">
@@ -1692,6 +4099,14 @@ authorization from the authors.
   <enum name="CoordMode">
     <item name="Origin">  <value>0</value></item>
     <item name="Previous"><value>1</value></item>
+    <doc>
+      <field name="Origin"><![CDATA[
+Treats all coordinates as relative to the origin.
+      ]]></field>
+      <field name="Previous"><![CDATA[
+Treats all coordinates after the first as relative to the previous coordinate.
+      ]]></field>
+    </doc>
   </enum>
 
   <!-- combine-adjacent doesn't work for mode==Relative -->
@@ -1707,6 +4122,56 @@ authorization from the authors.
     <field type="DRAWABLE" name="drawable" />
     <field type="GCONTEXT" name="gc" />
     <list type="POINT" name="points" />
+    <doc>
+      <brief>draw lines</brief>
+      <description><![CDATA[
+Draws `points_len`-1 lines between each pair of points (point[i], point[i+1])
+in the `points` array. The lines are drawn in the order listed in the array.
+They join correctly at all intermediate points, and if the first and last
+points coincide, the first and last lines also join correctly. For any given
+line, a pixel is not drawn more than once. If thin (zero line-width) lines
+intersect, the intersecting pixels are drawn multiple times. If wide lines
+intersect, the intersecting pixels are drawn only once, as though the entire
+request were a single, filled shape.
+      ]]></description>
+      <example><![CDATA[
+/*
+ * Draw a straight line.
+ *
+ */
+void my_example(xcb_connection *conn, xcb_drawable_t drawable, xcb_gcontext_t gc) {
+    xcb_poly_line(conn, XCB_COORD_MODE_ORIGIN, drawable, gc, 2,
+                  (xcb_point_t[]) { {10, 10}, {100, 10} });
+    xcb_flush(conn);
+}
+      ]]></example>
+      <field name="drawable"><![CDATA[
+The drawable to draw the line(s) on.
+      ]]></field>
+      <field name="gc"><![CDATA[
+The graphics context to use.
+      ]]></field>
+      <field name="points_len"><![CDATA[
+The number of `xcb_point_t` structures in `points`.
+      ]]></field>
+      <field name="points"><![CDATA[
+An array of points.
+      ]]></field>
+      <!-- the enum doc is sufficient. -->
+      <field name="coordinate_mode" />
+      <error type="Drawable"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="GC"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <error type="Value"><![CDATA[
+TODO: reasons?
+      ]]></error>
+    </doc>
   </request>
 
   <struct name="SEGMENT">
@@ -1721,6 +4186,43 @@ authorization from the authors.
     <field type="DRAWABLE" name="drawable" />
     <field type="GCONTEXT" name="gc" />
     <list type="SEGMENT" name="segments" />
+    <doc>
+      <brief>draw lines</brief>
+      <description><![CDATA[
+Draws multiple, unconnected lines. For each segment, a line is drawn between
+(x1, y1) and (x2, y2). The lines are drawn in the order listed in the array of
+`xcb_segment_t` structures and does not perform joining at coincident
+endpoints. For any given line, a pixel is not drawn more than once. If lines
+intersect, the intersecting pixels are drawn multiple times.
+
+TODO: include the xcb_segment_t data structure
+
+TODO: an example
+      ]]></description>
+      <field name="drawable"><![CDATA[
+A drawable (Window or Pixmap) to draw on.
+      ]]></field>
+      <field name="gc"><![CDATA[
+The graphics context to use.
+
+TODO: document which attributes of a gc are used
+      ]]></field>
+      <field name="segments_len"><![CDATA[
+The number of `xcb_segment_t` structures in `segments`.
+      ]]></field>
+      <field name="segments"><![CDATA[
+An array of `xcb_segment_t` structures.
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` does not exist.
+      ]]></error>
+      <error type="GC"><![CDATA[
+The specified `gc` does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+    </doc>
   </request>
 
   <request name="PolyRectangle" opcode="67" combine-adjacent="true">
@@ -1763,6 +4265,42 @@ authorization from the authors.
     <field type="DRAWABLE" name="drawable" />
     <field type="GCONTEXT" name="gc" />
     <list type="RECTANGLE" name="rectangles" />
+    <doc>
+      <brief>Fills rectangles</brief>
+      <description><![CDATA[
+Fills the specified rectangle(s) in the order listed in the array. For any
+given rectangle, each pixel is not drawn more than once. If rectangles
+intersect, the intersecting pixels are drawn multiple times.
+      ]]></description>
+      <field name="drawable"><![CDATA[
+The drawable (Window or Pixmap) to draw on.
+      ]]></field>
+      <field name="gc"><![CDATA[
+The graphics context to use.
+
+The following graphics context components are used: function, plane-mask,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+
+The following graphics context mode-dependent components are used:
+foreground, background, tile, stipple, tile-stipple-x-origin, and
+tile-stipple-y-origin.
+      ]]></field>
+      <field name="rectangles_len"><![CDATA[
+The number of `xcb_rectangle_t` structures in `rectangles`.
+      ]]></field>
+      <field name="rectangles"><![CDATA[
+The rectangles to fill.
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+      ]]></error>
+      <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+    </doc>
   </request>
 
   <request name="PolyFillArc" opcode="71" combine-adjacent="true">
@@ -1841,6 +4379,52 @@ authorization from the authors.
     <list type="char" name="string">
       <fieldref>string_len</fieldref>
     </list>
+    <doc>
+      <brief>Draws text</brief>
+      <description><![CDATA[
+Fills the destination rectangle with the background pixel from `gc`, then
+paints the text with the foreground pixel from `gc`. The upper-left corner of
+the filled rectangle is at [x, y - font-ascent]. The width is overall-width,
+the height is font-ascent + font-descent. The overall-width, font-ascent and
+font-descent are as returned by `xcb_query_text_extents` (TODO).
+
+Note that using X core fonts is deprecated (but still supported) in favor of
+client-side rendering using Xft.
+      ]]></description>
+      <field name="drawable"><![CDATA[
+The drawable (Window or Pixmap) to draw text on.
+      ]]></field>
+      <field name="string_len"><![CDATA[
+The length of the `string`. Note that this parameter limited by 255 due to
+using 8 bits!
+      ]]></field>
+      <field name="string"><![CDATA[
+The string to draw. Only the first 255 characters are relevant due to the data
+type of `string_len`.
+      ]]></field>
+      <field name="x"><![CDATA[
+The x coordinate of the first character, relative to the origin of `drawable`.
+      ]]></field>
+      <field name="y"><![CDATA[
+The y coordinate of the first character, relative to the origin of `drawable`.
+      ]]></field>
+      <field name="gc"><![CDATA[
+The graphics context to use.
+
+The following graphics context components are used: plane-mask, foreground,
+background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+      ]]></error>
+      <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <see type="request" name="ImageText16" />
+    </doc>
   </request>
 
   <request name="ImageText16" opcode="77">
@@ -1852,6 +4436,53 @@ authorization from the authors.
     <list type="CHAR2B" name="string">
       <fieldref>string_len</fieldref>
     </list>
+    <doc>
+      <brief>Draws text</brief>
+      <description><![CDATA[
+Fills the destination rectangle with the background pixel from `gc`, then
+paints the text with the foreground pixel from `gc`. The upper-left corner of
+the filled rectangle is at [x, y - font-ascent]. The width is overall-width,
+the height is font-ascent + font-descent. The overall-width, font-ascent and
+font-descent are as returned by `xcb_query_text_extents` (TODO).
+
+Note that using X core fonts is deprecated (but still supported) in favor of
+client-side rendering using Xft.
+      ]]></description>
+      <field name="drawable"><![CDATA[
+The drawable (Window or Pixmap) to draw text on.
+      ]]></field>
+      <field name="string_len"><![CDATA[
+The length of the `string` in characters. Note that this parameter limited by
+255 due to using 8 bits!
+      ]]></field>
+      <field name="string"><![CDATA[
+The string to draw. Only the first 255 characters are relevant due to the data
+type of `string_len`. Every character uses 2 bytes (hence the 16 in this
+request's name).
+      ]]></field>
+      <field name="x"><![CDATA[
+The x coordinate of the first character, relative to the origin of `drawable`.
+      ]]></field>
+      <field name="y"><![CDATA[
+The y coordinate of the first character, relative to the origin of `drawable`.
+      ]]></field>
+      <field name="gc"><![CDATA[
+The graphics context to use.
+
+The following graphics context components are used: plane-mask, foreground,
+background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+      ]]></field>
+      <error type="Drawable"><![CDATA[
+The specified `drawable` (Window or Pixmap) does not exist.
+      ]]></error>
+      <error type="GC"><![CDATA[
+The specified graphics context does not exist.
+      ]]></error>
+      <error type="Match"><![CDATA[
+TODO: reasons?
+      ]]></error>
+      <see type="request" name="ImageText8" />
+    </doc>
   </request>
 
   <enum name= "ColormapAlloc">
@@ -1915,6 +4546,31 @@ authorization from the authors.
       <pad bytes="2" />
       <field type="CARD32" name="pixel" />
     </reply>
+    <doc>
+      <brief>Allocate a color</brief>
+      <description><![CDATA[
+Allocates a read-only colormap entry corresponding to the closest RGB value
+supported by the hardware. If you are using TrueColor, you can take a shortcut
+and directly calculate the color pixel value to avoid the round trip. But, for
+example, on 16-bit color setups (VNC), you can easily get the closest supported
+RGB value to the RGB value you are specifying.
+      ]]></description>
+      <field name="cmap"><![CDATA[
+TODO
+      ]]></field>
+      <field name="red"><![CDATA[
+The red value of your color.
+      ]]></field>
+      <field name="green"><![CDATA[
+The green value of your color.
+      ]]></field>
+      <field name="blue"><![CDATA[
+The blue value of your color.
+      ]]></field>
+      <error type="Colormap"><![CDATA[
+The specified colormap `cmap` does not exist.
+      ]]></error>
+    </doc>
   </request>
 
   <request name="AllocNamedColor" opcode="85">
@@ -2092,11 +4748,82 @@ authorization from the authors.
     <field type="CARD16" name="back_red" />
     <field type="CARD16" name="back_green" />
     <field type="CARD16" name="back_blue" />
+    <doc>
+      <brief>create cursor</brief>
+      <description><![CDATA[
+Creates a cursor from a font glyph. X provides a set of standard cursor shapes
+in a special font named cursor. Applications are encouraged to use this
+interface for their cursors because the font can be customized for the
+individual display type.
+
+All pixels which are set to 1 in the source will use the foreground color (as
+specified by `fore_red`, `fore_green` and `fore_blue`). All pixels set to 0
+will use the background color (as specified by `back_red`, `back_green` and
+`back_blue`).
+      ]]></description>
+      <field name="cid"><![CDATA[
+The ID with which you will refer to the cursor, created by `xcb_generate_id`.
+      ]]></field>
+      <field name="source_font"><![CDATA[
+In which font to look for the cursor glyph.
+      ]]></field>
+      <field name="mask_font"><![CDATA[
+In which font to look for the mask glyph.
+      ]]></field>
+      <field name="source_char"><![CDATA[
+The glyph of `source_font` to use.
+      ]]></field>
+      <field name="mask_char"><![CDATA[
+The glyph of `mask_font` to use as a mask: Pixels which are set to 1 define
+which source pixels are displayed. All pixels which are set to 0 are not
+displayed.
+      ]]></field>
+      <field name="fore_red"><![CDATA[
+The red value of the foreground color.
+      ]]></field>
+      <field name="fore_green"><![CDATA[
+The green value of the foreground color.
+      ]]></field>
+      <field name="fore_blue"><![CDATA[
+The blue value of the foreground color.
+      ]]></field>
+      <field name="back_red"><![CDATA[
+The red value of the background color.
+      ]]></field>
+      <field name="back_green"><![CDATA[
+The green value of the background color.
+      ]]></field>
+      <field name="back_blue"><![CDATA[
+The blue value of the background color.
+      ]]></field>
+      <error type="Alloc"><![CDATA[
+The X server could not allocate the requested resources (no memory?).
+      ]]></error>
+      <error type="Font"><![CDATA[
+The specified `source_font` or `mask_font` does not exist.
+      ]]></error>
+      <error type="Value"><![CDATA[
+Either `source_char` or `mask_char` are not defined in `source_font` or `mask_font`, respectively.
+      ]]></error>
+      <!-- TODO: example -->
+    </doc>
   </request>
 
   <request name="FreeCursor" opcode="95">
     <pad bytes="1" />
     <field type="CURSOR" name="cursor" />
+    <doc>
+      <brief>Deletes a cursor</brief>
+      <description><![CDATA[
+Deletes the association between the cursor resource ID and the specified
+cursor. The cursor is freed when no other resource references it.
+      ]]></description>
+      <field name="cursor"><![CDATA[The cursor to destroy.]]></field>
+      <error type="Cursor"><![CDATA[
+The specified cursor does not exist.
+      ]]></error>
+    </doc>
+
   </request>
 
   <request name="RecolorCursor" opcode="96">
@@ -2141,7 +4868,44 @@ authorization from the authors.
       <field type="CARD8" name="major_opcode" />
       <field type="CARD8" name="first_event" />
       <field type="CARD8" name="first_error" />
+      <doc>
+        <field name="present"><![CDATA[
+Whether the extension is present on this X11 server.
+        ]]></field>
+        <field name="major_opcode"><![CDATA[
+The major opcode for requests.
+        ]]></field>
+        <field name="first_event"><![CDATA[
+The first event code, if any.
+        ]]></field>
+        <field name="first_error"><![CDATA[
+The first error code, if any.
+        ]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>check if extension is present</brief>
+      <description><![CDATA[
+Determines if the specified extension is present on this X11 server.
+
+Every extension has a unique `major_opcode` to identify requests, the minor
+opcodes and request formats are extension-specific. If the extension provides
+events and errors, the `first_event` and `first_error` fields in the reply are
+set accordingly.
+
+There should rarely be a need to use this request directly, XCB provides the
+`xcb_get_extension_data` function instead.
+      ]]></description>
+      <field name="name_len"><![CDATA[
+The length of `name` in bytes.
+      ]]></field>
+      <field name="name"><![CDATA[
+The name of the extension to query, for example "RANDR". This is case
+sensitive!
+      ]]></field>
+      <see type="program" name="xdpyinfo" />
+      <see type="function" name="xcb_get_extension_data" />
+    </doc>
   </request>
 
   <request name="ListExtensions" opcode="99">
@@ -2349,6 +5113,24 @@ authorization from the authors.
   <request name="KillClient" opcode="113">
     <pad bytes="1" />
     <field type="CARD32" name="resource" altenum="Kill" />
+    <doc>
+      <brief>kills a client</brief>
+      <description><![CDATA[
+Forces a close down of the client that created the specified `resource`.
+      ]]></description>
+      <field name="resource"><![CDATA[
+Any resource belonging to the client (for example a Window), used to identify
+the client connection.
+
+The special value of `XCB_KILL_ALL_TEMPORARY`, the resources of all clients
+that have terminated in `RetainTemporary` (TODO) are destroyed.
+      ]]></field>
+      <error type="Value"><![CDATA[
+The specified `resource` does not exist.
+      ]]></error>
+      <see type="program" name="xkill" />
+    </doc>
+
   </request>
 
   <request name="RotateProperties" opcode="114">
diff --git a/libxcb/xcb-proto/xcbgen/expr.py b/libxcb/xcb-proto/xcbgen/expr.py
index bbc5a3fd7..4f8af6f83 100644
--- a/libxcb/xcb-proto/xcbgen/expr.py
+++ b/libxcb/xcb-proto/xcbgen/expr.py
@@ -1,127 +1,129 @@
-'''

-This module contains helper classes for structure fields and length expressions.

-'''

-class Field(object):

-    '''

-    Represents a field of a structure.

-

-    type is the datatype object for the field.

-    field_type is the name of the type (string tuple)

-    field_name is the name of the structure field.

-    visible is true iff the field should be in the request API.

-    wire is true iff the field should be in the request structure.

-    auto is true iff the field is on the wire but not in the request API (e.g. opcode)

-    '''

-    def __init__(self, type, field_type, field_name, visible, wire, auto):

-        self.type = type

-        self.field_type = field_type

-        self.field_name = field_name

-        self.visible = visible

-        self.wire = wire

-        self.auto = auto

-

-

-class Expression(object):

-    '''

-    Represents a mathematical expression for a list length or exprfield.

-

-    Public fields:

-    op is the operation (text +,*,/,<<,~) or None.

-    lhs and rhs are the sub-Expressions if op is set.

-    lenfield_name is the name of the length field, or None for request lists.

-    lenfield is the Field object for the length field, or None.

-    bitfield is True if the length field is a bitmask instead of a number.

-    nmemb is the fixed size (value)of the expression, or None

-    '''

-    def __init__(self, elt, parent):

-        self.parent = parent

-

-        self.nmemb = None

-

-        self.lenfield_name = None

-        self.lenfield_type = None

-        self.lenfield_parent = None

-        self.lenfield = None

-        self.lenwire = False

-        self.bitfield = False

-

-        self.op = None

-        self.lhs = None

-        self.rhs = None

-

-        if elt.tag == 'list':

-            # List going into a request, which has no length field (inferred by server)

-            self.lenfield_name = elt.get('name') + '_len'

-            self.lenfield_type = 'CARD32'

-

-        elif elt.tag == 'fieldref':

-            # Standard list with a fieldref

-            self.lenfield_name = elt.text

-

-        elif elt.tag == 'valueparam':

-            # Value-mask.  The length bitmask is described by attributes.

-            self.lenfield_name = elt.get('value-mask-name')

-            self.lenfield_type = elt.get('value-mask-type')

-            self.lenwire = True

-            self.bitfield = True

-

-        elif elt.tag == 'op':

-            # Op field.  Need to recurse.

-            self.op = elt.get('op')

-            self.lhs = Expression(list(elt)[0], parent)

-            self.rhs = Expression(list(elt)[1], parent)

-

-            # Hopefully we don't have two separate length fields...

-            self.lenfield_name = self.lhs.lenfield_name

-            if self.lenfield_name == None:

-                self.lenfield_name = self.rhs.lenfield_name

-

-        elif elt.tag == 'unop':

-            # Op field.  Need to recurse.

-            self.op = elt.get('op')

-            self.rhs = Expression(list(elt)[0], parent)

-

-            self.lenfield_name = self.rhs.lenfield_name

-            

-        elif elt.tag == 'value':

-            # Constant expression

-            self.nmemb = int(elt.text, 0)

-

-        elif elt.tag == 'popcount':

-            self.op = 'popcount'

-            self.rhs = Expression(list(elt)[0], parent)

-            self.lenfield_name = self.rhs.lenfield_name

-            # xcb_popcount returns 'int' - handle the type in the language-specific part

-

-        elif elt.tag == 'enumref':

-            self.op = 'enumref'

-            self.lenfield_name = (elt.get('ref'), elt.text)

-            

-        elif elt.tag == 'sumof':

-            self.op = 'sumof'

-            self.lenfield_name = elt.get('ref')

-

-        else:

-            # Notreached

-            raise Exception("undefined tag '%s'" % elt.tag)

-

-    def fixed_size(self):

-        return self.nmemb != None

-

-    def resolve(self, module, parents):

-        if self.op == 'enumref':

-            self.lenfield_type = module.get_type(self.lenfield_name[0])

-            self.lenfield_name = self.lenfield_name[1]

-        elif self.op == 'sumof':

-            # need to find the field with lenfield_name

-            for p in reversed(parents): 

-                fields = dict([(f.field_name, f) for f in p.fields])

-                if self.lenfield_name in fields.keys():

-                    if p.is_bitcase:

-                        # switch is the anchestor 

-                        self.lenfield_parent = p.parents[-1]

-                    else:

-                        self.lenfield_parent = p

-                    self.lenfield_type = fields[self.lenfield_name].field_type

-                    break

-                    

+'''
+This module contains helper classes for structure fields and length expressions.
+'''
+class Field(object):
+    '''
+    Represents a field of a structure.
+
+    type is the datatype object for the field.
+    field_type is the name of the type (string tuple)
+    field_name is the name of the structure field.
+    visible is true iff the field should be in the request API.
+    wire is true iff the field should be in the request structure.
+    auto is true iff the field is on the wire but not in the request API (e.g. opcode)
+    enum is the enum name this field refers to, if any.
+    '''
+    def __init__(self, type, field_type, field_name, visible, wire, auto, enum=None):
+        self.type = type
+        self.field_type = field_type
+        self.field_name = field_name
+        self.enum = enum
+        self.visible = visible
+        self.wire = wire
+        self.auto = auto
+
+
+class Expression(object):
+    '''
+    Represents a mathematical expression for a list length or exprfield.
+
+    Public fields:
+    op is the operation (text +,*,/,<<,~) or None.
+    lhs and rhs are the sub-Expressions if op is set.
+    lenfield_name is the name of the length field, or None for request lists.
+    lenfield is the Field object for the length field, or None.
+    bitfield is True if the length field is a bitmask instead of a number.
+    nmemb is the fixed size (value)of the expression, or None
+    '''
+    def __init__(self, elt, parent):
+        self.parent = parent
+
+        self.nmemb = None
+
+        self.lenfield_name = None
+        self.lenfield_type = None
+        self.lenfield_parent = None
+        self.lenfield = None
+        self.lenwire = False
+        self.bitfield = False
+
+        self.op = None
+        self.lhs = None
+        self.rhs = None
+
+        if elt.tag == 'list':
+            # List going into a request, which has no length field (inferred by server)
+            self.lenfield_name = elt.get('name') + '_len'
+            self.lenfield_type = 'CARD32'
+
+        elif elt.tag == 'fieldref':
+            # Standard list with a fieldref
+            self.lenfield_name = elt.text
+
+        elif elt.tag == 'valueparam':
+            # Value-mask.  The length bitmask is described by attributes.
+            self.lenfield_name = elt.get('value-mask-name')
+            self.lenfield_type = elt.get('value-mask-type')
+            self.lenwire = True
+            self.bitfield = True
+
+        elif elt.tag == 'op':
+            # Op field.  Need to recurse.
+            self.op = elt.get('op')
+            self.lhs = Expression(list(elt)[0], parent)
+            self.rhs = Expression(list(elt)[1], parent)
+
+            # Hopefully we don't have two separate length fields...
+            self.lenfield_name = self.lhs.lenfield_name
+            if self.lenfield_name == None:
+                self.lenfield_name = self.rhs.lenfield_name
+
+        elif elt.tag == 'unop':
+            # Op field.  Need to recurse.
+            self.op = elt.get('op')
+            self.rhs = Expression(list(elt)[0], parent)
+
+            self.lenfield_name = self.rhs.lenfield_name
+            
+        elif elt.tag == 'value':
+            # Constant expression
+            self.nmemb = int(elt.text, 0)
+
+        elif elt.tag == 'popcount':
+            self.op = 'popcount'
+            self.rhs = Expression(list(elt)[0], parent)
+            self.lenfield_name = self.rhs.lenfield_name
+            # xcb_popcount returns 'int' - handle the type in the language-specific part
+
+        elif elt.tag == 'enumref':
+            self.op = 'enumref'
+            self.lenfield_name = (elt.get('ref'), elt.text)
+            
+        elif elt.tag == 'sumof':
+            self.op = 'sumof'
+            self.lenfield_name = elt.get('ref')
+
+        else:
+            # Notreached
+            raise Exception("undefined tag '%s'" % elt.tag)
+
+    def fixed_size(self):
+        return self.nmemb != None
+
+    def resolve(self, module, parents):
+        if self.op == 'enumref':
+            self.lenfield_type = module.get_type(self.lenfield_name[0])
+            self.lenfield_name = self.lenfield_name[1]
+        elif self.op == 'sumof':
+            # need to find the field with lenfield_name
+            for p in reversed(parents): 
+                fields = dict([(f.field_name, f) for f in p.fields])
+                if self.lenfield_name in fields.keys():
+                    if p.is_bitcase:
+                        # switch is the anchestor 
+                        self.lenfield_parent = p.parents[-1]
+                    else:
+                        self.lenfield_parent = p
+                    self.lenfield_type = fields[self.lenfield_name].field_type
+                    break
+                    
diff --git a/libxcb/xcb-proto/xcbgen/xtypes.py b/libxcb/xcb-proto/xcbgen/xtypes.py
index c78915846..f6d463445 100644
--- a/libxcb/xcb-proto/xcbgen/xtypes.py
+++ b/libxcb/xcb-proto/xcbgen/xtypes.py
@@ -56,7 +56,7 @@ class Type(object):
         '''
         raise Exception('abstract fixed_size method not overridden!')
 
-    def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto):
+    def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None):
         '''
         Default method for making a data type a member of a structure.
         Extend this if the data type needs to add an additional length field or something.
@@ -65,7 +65,7 @@ class Type(object):
         complex_type is the structure object.
         see Field for the meaning of the other parameters.
         '''
-        new_field = Field(self, field_type, field_name, visible, wire, auto)
+        new_field = Field(self, field_type, field_name, visible, wire, auto, enum)
 
         # We dump the _placeholder_byte if any fields are added.
         for (idx, field) in enumerate(complex_type.fields):
@@ -123,7 +123,11 @@ class Enum(SimpleType):
         SimpleType.__init__(self, name, 4)
         self.values = []
         self.bits = []
+        self.doc = None
         for item in list(elt):
+            if item.tag == 'doc':
+                self.doc = Doc(name, item)
+
             # First check if we're using a default value
             if len(list(item)) == 0:
                 self.values.append((item.get('name'), ''))
@@ -170,7 +174,7 @@ class ListType(Type):
         self.size = member.size if member.fixed_size() else None
         self.nmemb = self.expr.nmemb if self.expr.fixed_size() else None
 
-    def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto):
+    def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None):
         if not self.fixed_size():
             # We need a length field.
             # Ask our Expression object for it's name, type, and whether it's on the wire.
@@ -189,10 +193,10 @@ class ListType(Type):
             if needlen:
                 type = module.get_type(lenfid)
                 lenfield_type = module.get_type_name(lenfid)
-                type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False)
+                type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False, enum)
 
         # Add ourself to the structure by calling our original method.
-        Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto)
+        Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum)
 
     def resolve(self, module):
         if self.resolved:
@@ -278,6 +282,7 @@ class ComplexType(Type):
         if self.resolved:
             return
         pads = 0
+        enum = None
 
         # Resolve all of our field datatypes.
         for child in list(self.elt):
@@ -289,6 +294,7 @@ class ComplexType(Type):
                 visible = False
             elif child.tag == 'field':
                 field_name = child.get('name')
+                enum = child.get('enum')
                 fkey = child.get('type')
                 type = module.get_type(fkey)
                 visible = True
@@ -323,7 +329,7 @@ class ComplexType(Type):
             # Get the full type name for the field
             field_type = module.get_type_name(fkey)
             # Add the field to ourself
-            type.make_member_of(module, self, field_type, field_name, visible, True, False)
+            type.make_member_of(module, self, field_type, field_name, visible, True, False, enum)
             # Recursively resolve the type (could be another structure, list)
             type.resolve(module)
 
@@ -413,7 +419,7 @@ class SwitchType(ComplexType):
         self.calc_size() # Figure out how big we are
         self.resolved = True
 
-    def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto):
+    def make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum=None):
         if not self.fixed_size():
             # We need a length field.
             # Ask our Expression object for it's name, type, and whether it's on the wire.
@@ -432,10 +438,10 @@ class SwitchType(ComplexType):
             if needlen:
                 type = module.get_type(lenfid)
                 lenfield_type = module.get_type_name(lenfid)
-                type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False)
+                type.make_member_of(module, complex_type, lenfield_type, lenfield_name, True, lenwire, False, enum)
 
         # Add ourself to the structure by calling our original method.
-        Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto)
+        Type.make_member_of(self, module, complex_type, field_type, field_name, visible, wire, auto, enum)
 
     # size for switch can only be calculated at runtime
     def calc_size(self):
@@ -483,7 +489,7 @@ class BitcaseType(ComplexType):
         self.parents = list(parent)
         self.is_bitcase = True
 
-    def make_member_of(self, module, switch_type, field_type, field_name, visible, wire, auto):
+    def make_member_of(self, module, switch_type, field_type, field_name, visible, wire, auto, enum=None):
         '''
         register BitcaseType with the corresponding SwitchType
 
@@ -491,7 +497,7 @@ class BitcaseType(ComplexType):
         complex_type is the structure object.
         see Field for the meaning of the other parameters.
         '''
-        new_field = Field(self, field_type, field_name, visible, wire, auto)
+        new_field = Field(self, field_type, field_name, visible, wire, auto, enum)
 
         # We dump the _placeholder_byte if any bitcases are added.
         for (idx, field) in enumerate(switch_type.bitcases):
@@ -518,6 +524,11 @@ class Reply(ComplexType):
     def __init__(self, name, elt):
         ComplexType.__init__(self, name, elt)
         self.is_reply = True
+        self.doc = None
+
+        for child in list(elt):
+            if child.tag == 'doc':
+                self.doc = Doc(name, child)
 
     def resolve(self, module):
         if self.resolved:
@@ -541,11 +552,14 @@ class Request(ComplexType):
     def __init__(self, name, elt):
         ComplexType.__init__(self, name, elt)
         self.reply = None
+        self.doc = None
         self.opcode = elt.get('opcode')
 
         for child in list(elt):
             if child.tag == 'reply':
                 self.reply = Reply(name, child)
+            if child.tag == 'doc':
+                self.doc = Doc(name, child)
 
     def resolve(self, module):
         if self.resolved:
@@ -581,6 +595,11 @@ class Event(ComplexType):
 
         tmp = elt.get('no-sequence-number')
         self.has_seq = (tmp == None or tmp.lower() == 'false' or tmp == '0')
+
+        self.doc = None
+        for item in list(elt):
+            if item.tag == 'doc':
+                self.doc = Doc(name, item)
             
     def add_opcode(self, opcode, name, main):
         self.opcodes[name] = opcode
@@ -629,4 +648,35 @@ class Error(ComplexType):
 
     out = __main__.output['error']
 
+
+class Doc(object):
+    '''
+    Class representing a <doc> tag.
+    '''
+    def __init__(self, name, elt):
+        self.name = name
+        self.description = None
+        self.brief = 'BRIEF DESCRIPTION MISSING'
+        self.fields = {}
+        self.errors = {}
+        self.see = {}
+        self.example = None
+
+        for child in list(elt):
+            text = child.text if child.text else ''
+            if child.tag == 'description':
+                self.description = text.strip()
+            if child.tag == 'brief':
+                self.brief = text.strip()
+            if child.tag == 'field':
+                self.fields[child.get('name')] = text.strip()
+            if child.tag == 'error':
+                self.errors[child.get('type')] = text.strip()
+            if child.tag == 'see':
+                self.see[child.get('name')] = child.get('type')
+            if child.tag == 'example':
+                self.example = text.strip()
+
+
+
 _placeholder_byte = Field(PadType(None), tcard8.name, 'pad0', False, True, False)