XI2proto.h: doxygen-ify

1 files changed, 292 insertions, 260 deletions

diff --git a/XI2proto.h b/XI2proto.h
index c90ada0..e3a5101 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -23,9 +23,12 @@
  */
 
 /**
+ * @mainpage
+ * @include XI2proto.txt
+ */
+/**
  * @file XI2proto.h
  * Protocol definitions for the XI2 protocol.
- *
  * This file should not be included by clients that merely use XI2, but do not
  * need the wire protocol. Such clients should include XI2.h, or the matching
  * header from the library.
@@ -43,7 +46,11 @@
 #define Time    CARD32
 #define Atom    CARD32
 
-/* Request opcodes */
+/**
+ * XI2 Request opcodes
+ * @addtogroup XI2Requests
+ * @{
+ */
 #define X_XIQueryDevicePointer          40
 #define X_XIWarpDevicePointer           41
 #define X_XIChangeDeviceCursor          42
@@ -64,8 +71,11 @@
 #define X_XIChangeProperty              57
 #define X_XIDeleteProperty              58
 #define X_XIGetProperty                 59
+/*@}*/
 
+/** Number of XI requests */
 #define XI2REQUESTS (X_XIGetProperty - X_XIQueryDevicePointer + 1)
+/** Number of XI2 events */
 #define XI2EVENTS   (XI_LASTEVENT + 1)
 
 /*************************************************************************************
@@ -73,27 +83,32 @@
  *                               COMMON STRUCTS                                      *
  *                                                                                   *
  *************************************************************************************/
-/* Fixed point 16.16 */
+/** Fixed point 16.16 */
 typedef int32_t FP1616;
 
-/* Fixed point 32.32 */
+/** Fixed point 32.32 */
 typedef struct {
     int32_t     integral;
     uint32_t    frac;
 } FP3232;
 
 /**
+ * \struct xXIDeviceInfo
  * Struct to describe a device.
  *
- * For a MasterPointer or a MasterKeyboard, 'attachment' desviced
+ * For a MasterPointer or a MasterKeyboard, 'attachment' specifies the
+ * paired master device.
+ * For a SlaveKeyboard or SlavePointer, 'attachment' specifies the master
+ * device this device is attached to.
+ * For a FloatingSlave, 'attachment' is undefined.
  *
- * @see XIQueryDevices
+ * @see xXIQueryDeviceReq
  */
 typedef struct {
     uint16_t    deviceid;
-    uint16_t    use;            /**< ::MasterPointer, ::MasterKeyboard,
-                                  ::SlavePointer, ::SlaveKeyboard,
-                                  ::FloatingSlave */
+    uint16_t    use;            /**< ::XIMasterPointer, ::XIMasterKeyboard,
+                                     ::XISlavePointer, ::XISlaveKeyboard,
+                                     ::XIFloatingSlave */
     uint16_t    attachment;     /**< Current attachment or pairing.*/
     uint16_t    num_classes;    /**< Number of classes following this struct. */
     uint16_t    name_len;       /**< Length of name in bytes. */
@@ -102,12 +117,13 @@ typedef struct {
 } xXIDeviceInfo;
 
 /**
+ * \struct xXIAnyInfo
  * Default template for a device class.
  * A device class is equivalent to a device's capabilities. Multiple classes
  * are supported per device.
  *
- * @see XIQueryDevices
- * @see XIDeviceChangedEvent
+ * @see xXIQueryDeviceReq
+ * @see xXIDeviceChangedEvent
  */
 typedef struct {
     uint16_t    type;           /**< One of *class */
@@ -119,8 +135,8 @@ typedef struct {
  * Struct is followed by num_buttons * Atom that names the buttons in the
  * device-native setup (i.e. ignoring button mappings).
  *
- * @see XIQueryDevices
- * @see XIDeviceChangedEvent
+ * @see xXIQueryDeviceReq
+ * @see xXIDeviceChangedEvent
  */
 typedef struct {
     uint16_t    type;           /**< Always ButtonClass */
@@ -134,8 +150,8 @@ typedef struct {
  * Struct is followed by num_keys * CARD32 that lists the keycodes available
  * on the device.
  *
- * @see XIQueryDevices
- * @see XIDeviceChangedEvent
+ * @see xXIQueryDeviceReq
+ * @see xXIDeviceChangedEvent
  */
 typedef struct {
     uint16_t    type;           /**< Always KeyClass */
@@ -148,12 +164,12 @@ typedef struct {
  * Denotes an valuator capability on a device.
  * One XIValuatorInfo describes exactly one valuator (axis) on the device.
  *
- * @see XIQueryDevices
- * @see XIDeviceChangedEvent
+ * @see xXIQueryDevice
+ * @see xXIDeviceChangedEvent
  */
 typedef struct {
     uint16_t    type;           /**< Always ValuatorClass       */
-    uint16_t    length;         /**< Length in 4 byte units     */
+    uint16_t    length;         /**< Length in 4 byte units */
     Atom        name;           /**< Valuator name              */
     FP3232      min;            /**< Min value                  */
     FP3232      max;            /**< Max value                  */
@@ -179,37 +195,29 @@ typedef struct {
 
 
 
-typedef struct {
-    uint32_t    modifiers;
-    uint8_t     status;
-    uint8_t     pad0;
-    uint16_t    pad1;
-} xXIGrabModifierInfo;
-
 /*************************************************************************************
  *                                                                                   *
  *                                   REQUESTS                                        *
  *                                                                                   *
  *************************************************************************************/
 
-/**********************************************************
- * XIQueryVersion.
- * Query the server for the supported X Input Extension version.
- *
+/**
+ * @struct xXIQueryVersionReq
+ * Query the server for the supported X Input extension version.
  */
 
 typedef struct {
-    uint8_t     reqType;                /* input extension major code   */
-    uint8_t     ReqType;                /* always X_XIQueryVersion      */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XIQueryVersion */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    major_version;
     uint16_t    minor_version;
 } xXIQueryVersionReq;
 #define sz_xXIQueryVersionReq                     8
 
 typedef struct {
-    uint8_t     repType;                /* X_Reply */
-    uint8_t     RepType;                /* always X_XIQueryVersion      */
+    uint8_t     repType;                /**< ::X_Reply */
+    uint8_t     RepType;                /**< Always ::X_XIQueryVersion */
     uint16_t    sequenceNumber;
     uint32_t    length;
     uint16_t    major_version;
@@ -222,26 +230,25 @@ typedef struct {
 } xXIQueryVersionReply;
 #define sz_xXIQueryVersionReply             32
 
-/**********************************************************
- *
- * XIQueryDevice
+/**
+ * @struct xXIQueryDeviceReq
  * Query the server for information about a specific device or all input
  * devices.
  *
  */
 
 typedef struct {
-    uint8_t     reqType;                /* input extension major code   */
-    uint8_t     ReqType;                /* always X_XIQueryDevice       */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XIQueryDevice */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    deviceid;
     uint16_t    pad;
 } xXIQueryDeviceReq;
 #define sz_xXIQueryDeviceReq                    8
 
 typedef struct {
-    uint8_t     repType;                /* X_Reply */
-    uint8_t     RepType;                /* always X_XIQueryDevice       */
+    uint8_t     repType;                /**< ::X_Reply */
+    uint8_t     RepType;                /**< Always ::X_XIQueryDevice */
     uint16_t    sequenceNumber;
     uint32_t    length;
     uint16_t    num_devices;
@@ -254,15 +261,14 @@ typedef struct {
 } xXIQueryDeviceReply;
 #define sz_xXIQueryDeviceReply                  32
 
-/**********************************************************
- *
- * XISelectEvents
- *
+/**
+ * @struct xXISelectEventsReq
+ * Select for events on a given window.
  */
 typedef struct {
-    uint8_t     reqType;                /* input extension major code   */
-    uint8_t     ReqType;                /* always X_XISelectEvents      */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XISelectEvents */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      window;
     uint16_t    num_masks;
     uint16_t    pad;
@@ -270,16 +276,15 @@ typedef struct {
 #define sz_xXISelectEventsReq                  12
 
 
-/**********************************************************
- *
- * QueryDevicePointer.
- *
+/**
+ * @struct xXIQueryDevicePointerReq
+ * Query the given device's screen/window coordinates.
  */
 
 typedef struct {
-    uint8_t     reqType;                /* input extension major code   */
-    uint8_t     ReqType;                /* always X_QueryDevicePointer  */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XIQueryDevicePointer */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      win;
     uint16_t    deviceid;
     uint16_t    pad1;
@@ -288,8 +293,8 @@ typedef struct {
 
 
 typedef struct {
-    uint8_t     repType;                /* X_Reply */
-    uint8_t     RepType;                /* always X_QueryDevicePointer */
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always ::X_XIQueryDevicePointer */
     uint16_t    sequenceNumber;
     uint32_t    length;
     Window      root;
@@ -306,16 +311,15 @@ typedef struct {
 } xXIQueryDevicePointerReply;
 #define sz_xXIQueryDevicePointerReply             40
 
-/**********************************************************
- *
- * WarpDevicePointer.
- *
+/**
+ * @struct xXIWarpDevicePointerReq
+ * Warp the given device's pointer to the specified position.
  */
 
 typedef struct {
-    uint8_t     reqType;        /* input extension major code   */
-    uint8_t     ReqType;        /* always X_WarpDevicePointer   */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XIWarpDevicePointer   */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      src_win;
     Window      dst_win;
     INT16       src_x;
@@ -329,16 +333,15 @@ typedef struct {
 } xXIWarpDevicePointerReq;
 #define sz_xXIWarpDevicePointerReq                28
 
-/**********************************************************
- *
- * ChangeDeviceCursor.
- *
+/**
+ * @struct xXIChangeDeviceCursorReq
+ * Change the given device's sprite to the given cursor.
  */
 
 typedef struct {
-    uint8_t     reqType;          /* input extension major code   */
-    uint8_t     ReqType;          /* always X_ChangeDeviceCursor  */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XIChangeDeviceCursor  */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      win;
     Cursor      cursor;
     uint16_t    deviceid;
@@ -346,25 +349,27 @@ typedef struct {
 } xXIChangeDeviceCursorReq;
 #define sz_xXIChangeDeviceCursorReq               16
 
-/**********************************************************
- *
- * ChangeDeviceHierarchy
- *
+/**
+ * @struct xXIChangeDeviceHierarchyReq
+ * Modify the device hierarchy.
  */
 
 typedef struct {
-    uint8_t     reqType;         /* input extension major code   */
-    uint8_t     ReqType;         /* always X_ChangeDeviceHierarchy */
-    uint16_t    length;
+    uint8_t     reqType;                /**< Input extension major code */
+    uint8_t     ReqType;                /**< Always ::X_XIChangeDeviceHierarchy */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint8_t     num_changes;
     uint8_t     pad0;
     uint16_t    pad1;
 } xXIChangeDeviceHierarchyReq;
 #define sz_xXIChangeDeviceHierarchyReq            8
 
+/**
+ * Generic header for any hierarchy change.
+ */
 typedef struct {
     uint16_t    type;
-    uint16_t    length;         /* in 4 byte units */
+    uint16_t    length;                 /**< Length in 4 byte units */
 } xXIAnyHierarchyChangeInfo;
 
 /**
@@ -372,8 +377,8 @@ typedef struct {
  * Name of new master follows struct (4-byte padded)
  */
 typedef struct {
-    uint16_t    type;           /* Always CH_CreateMasterDevice */
-    uint16_t    length;         /* 2 + (namelen + padding)/4 */
+    uint16_t    type;                   /**< Always ::XICreateMasterDevice */
+    uint16_t    length;                 /**< 2 + (namelen + padding)/4 */
     uint16_t    name_len;
     uint8_t     send_core;
     uint8_t     enable;
@@ -384,70 +389,69 @@ typedef struct {
  * with the given master device.
  */
 typedef struct {
-    uint16_t    type;            /* Always CH_RemoveMasterDevice */
-    uint16_t    length;          /* 3 */
+    uint16_t    type;            /**< Always ::XIRemoveMasterDevice */
+    uint16_t    length;          /**< 3 */
     uint16_t    deviceid;
-    uint8_t     return_mode;     /* AttachToMaster, Floating */
+    uint8_t     return_mode;     /**< ::XIAttachToMaster, ::XIFloating */
     uint8_t     pad;
-    uint16_t    return_pointer;  /* Pointer to attach slave ptr devices to */
-    uint16_t    return_keyboard; /* keyboard to attach slave keybd devices to*/
+    uint16_t    return_pointer;  /**< Pointer to attach slave ptr devices to */
+    uint16_t    return_keyboard; /**< keyboard to attach slave keybd devices to*/
 } xXIRemoveMasterInfo;
 
-/* Attach an SD to a new device.
+/**
+ * Attach an SD to a new device.
  * NewMaster has to be of same type (pointer->pointer, keyboard->keyboard);
  */
 typedef struct {
-    uint16_t    type;           /* Always CH_AttachSlave */
-    uint16_t    length;         /* 2 */
+    uint16_t    type;           /**< Always ::XIAttachSlave */
+    uint16_t    length;         /**< 2 */
     uint16_t    deviceid;
-    uint16_t    new_master;     /* id of new master device */
+    uint16_t    new_master;     /**< id of new master device */
 } xXIAttachSlaveInfo;
 
-/* Detach an SD from its current master device.
+/**
+ * Detach an SD from its current master device.
  */
 typedef struct {
-    uint16_t    type;           /* Always CH_DetachSlave */
-    uint16_t    length;         /* 2 */
+    uint16_t    type;           /**< Always ::XIDetachSlave */
+    uint16_t    length;         /**< 2 */
     uint16_t    deviceid;
     uint16_t    pad;
 } xXIDetachSlaveInfo;
 
 
-/**********************************************************
- *
- * SetClientPointer.
- *
+/**
+ * @struct xXISetClientPointerReq
+ * Set the window/client's ClientPointer.
  */
-
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_SetClientPointer */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XISetClientPointer */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      win;
     uint16_t    deviceid;
     uint16_t    pad1;
 } xXISetClientPointerReq;
 #define sz_xXISetClientPointerReq                 12
 
-/**********************************************************
- *
- * GetClientPointer.
- *
+/**
+ * @struct xXIGetClientPointerReq
+ * Query the given window/client's ClientPointer setting.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_GetClientPointer */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_GetClientPointer */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      win;
 } xXIGetClientPointerReq;
 #define sz_xXIGetClientPointerReq                 8
 
 typedef struct {
-    uint8_t     repType;                /* input extension major opcode */
-    uint8_t     RepType;                /* Always X_GetClientPointer */
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always ::X_GetClientPointer */
     uint16_t    sequenceNumber;
     uint32_t    length;
-    BOOL        set;                    /* client pointer is set */
+    BOOL        set;                    /**< client pointer is set? */
     uint8_t     pad0;
     uint16_t    deviceid;
     uint32_t    pad1;
@@ -458,15 +462,14 @@ typedef struct {
 } xXIGetClientPointerReply;
 #define sz_xXIGetClientPointerReply               32
 
-/**********************************************************
- *
- * SetDeviceFocus.
- *
+/**
+ * @struct xXISetDeviceFocusReq
+ * Set the input focus to the specified window.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XISetDeviceFocus */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XISetDeviceFocus */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      focus;
     Time        time;
     uint16_t    deviceid;
@@ -474,23 +477,22 @@ typedef struct {
 } xXISetDeviceFocusReq;
 #define sz_xXISetDeviceFocusReq                 16
 
-/**********************************************************
- *
- * GetDeviceFocus.
- *
+/**
+ * @struct xXIGetDeviceFocusReq
+ * Query the current input focus.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIGetDeviceFocus */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIGetDeviceFocus */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    deviceid;
     uint16_t    pad0;
 } xXIGetDeviceFocusReq;
 #define sz_xXIGetDeviceFocusReq                 8
 
 typedef struct {
-    uint8_t     repType;                /* input extension major opcode */
-    uint8_t     RepType;                /* Always X_XIGetDeviceFocus */
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always ::X_XIGetDeviceFocus */
     uint16_t    sequenceNumber;
     uint32_t    length;
     Window      focus;
@@ -503,15 +505,14 @@ typedef struct {
 #define sz_xXIGetDeviceFocusReply               32
 
 
-/**********************************************************
- *
- * GrabDevice
- *
+/**
+ * @struct xXIGrabDeviceReq
+ * Grab the given device.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIGrabDevice */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIGrabDevice */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      grab_window;
     Time        time;
     Cursor      cursor;
@@ -524,9 +525,19 @@ typedef struct {
 } xXIGrabDeviceReq;
 #define sz_xXIGrabDeviceReq                     24
 
+/**
+ * Return codes from a XIPassiveGrabDevice request.
+ */
 typedef struct {
-    uint8_t     repType;                /* input extension major opcode */
-    uint8_t     RepType;                /* Always X_XIGrabDevice */
+    uint32_t    modifiers;              /**< Modifier state */
+    uint8_t     status;                 /**< Grab status code */
+    uint8_t     pad0;
+    uint16_t    pad1;
+} xXIGrabModifierInfo;
+
+typedef struct {
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always ::X_XIGrabDevice */
     uint16_t    sequenceNumber;
     uint32_t    length;
     uint8_t     status;
@@ -540,15 +551,15 @@ typedef struct {
 } xXIGrabDeviceReply;
 #define sz_xXIGrabDeviceReply                  32
 
-/**********************************************************
- *
- * UngrabDevice
+/**
+ * @struct xXIUngrabDeviceReq
+ * Ungrab the specified device.
  *
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIUngrabDevice */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIUngrabDevice */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Time        time;
     uint16_t    deviceid;
     uint16_t    pad;
@@ -556,15 +567,14 @@ typedef struct {
 #define sz_xXIUngrabDeviceReq                   12
 
 
-/**********************************************************
- *
- * AllowEvents
- *
+/**
+ * @struct xXIAllowEventsReq
+ * Allow or replay events on the specified grabbed device.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIAllowEvents */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIAllowEvents */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Time        time;
     uint16_t    deviceid;
     uint8_t     mode;
@@ -573,15 +583,14 @@ typedef struct {
 #define sz_xXIAllowEventsReq                   12
 
 
-/**********************************************************
- *
- * PassiveGrabDevice
- *
+/**
+ * @struct xXIPassiveGrabDeviceReq
+ * Passively grab the device.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIPassiveGrabDevice */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIPassiveGrabDevice */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Time        time;
     Window      grab_window;
     Cursor      cursor;
@@ -598,8 +607,8 @@ typedef struct {
 #define sz_xXIPassiveGrabDeviceReq              32
 
 typedef struct {
-    uint8_t     repType;                /* input extension major opcode */
-    uint8_t     RepType;                /* Always X_XIPassiveGrabDevice */
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always ::X_XIPassiveGrabDevice */
     uint16_t    sequenceNumber;
     uint32_t    length;
     uint16_t    num_modifiers;
@@ -612,10 +621,14 @@ typedef struct {
 } xXIPassiveGrabDeviceReply;
 #define sz_xXIPassiveGrabDeviceReply            32
 
+/**
+ * @struct xXIPassiveUngrabDeviceReq
+ * Delete a passive grab for the given device.
+ */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIPassiveUngrabDevice */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIPassiveUngrabDevice */
+    uint16_t    length;                 /**< Length in 4 byte units */
     Window      grab_window;
     uint32_t    detail;
     uint16_t    deviceid;
@@ -626,23 +639,22 @@ typedef struct {
 } xXIPassiveUngrabDeviceReq;
 #define sz_xXIPassiveUngrabDeviceReq            20
 
-/**********************************************************
- *
- * XIListProperties
- *
+/**
+ * @struct xXIListPropertiesReq
+ * List all device properties on the specified device.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIListProperties */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIListProperties */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    deviceid;
     uint16_t    pad;
 } xXIListPropertiesReq;
 #define sz_xXIListPropertiesReq                 8
 
 typedef struct {
-    uint8_t     repType;                /* input extension major opcode */
-    uint8_t     RepType;                /* Always X_XIListProperties */
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always ::X_XIListProperties */
     uint16_t    sequenceNumber;
     uint32_t    length;
     uint16_t    num_properties;
@@ -655,15 +667,14 @@ typedef struct {
 } xXIListPropertiesReply;
 #define sz_xXIListPropertiesReply               32
 
-/**********************************************************
- *
- * XIChangeDeviceProperty
- *
+/**
+ * @struct xXIChangePropertyReq
+ * Change a property on the specified device.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIChangeProperty */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always ::X_XIChangeProperty */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    deviceid;
     uint8_t     mode;
     uint8_t     format;
@@ -673,30 +684,28 @@ typedef struct {
 } xXIChangePropertyReq;
 #define sz_xXIChangePropertyReq                 20
 
-/**********************************************************
- *
- * XIDeleteProperty
- *
+/**
+ * @struct xXIDeletePropertyReq
+ * Delete the specified property.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIDeleteProperty */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always X_XIDeleteProperty */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    deviceid;
     uint16_t    pad0;
     Atom        property;
 } xXIDeletePropertyReq;
 #define sz_xXIDeletePropertyReq                 12
 
-/**********************************************************
- *
- * XIGetProperty
- *
+/**
+ * @struct xXIGetPropertyReq
+ * Query the specified property's values.
  */
 typedef struct {
     uint8_t     reqType;
-    uint8_t     ReqType;                /* Always X_XIGetProperty */
-    uint16_t    length;
+    uint8_t     ReqType;                /**< Always X_XIGetProperty */
+    uint16_t    length;                 /**< Length in 4 byte units */
     uint16_t    deviceid;
 #if defined(__cplusplus) || defined(c_plusplus)
     uint8_t     c_delete;
@@ -712,8 +721,8 @@ typedef struct {
 #define sz_xXIGetPropertyReq                    24
 
 typedef struct {
-    uint8_t     repType;                /* input extension major opcode */
-    uint8_t     RepType;                /* Always X_XIGetProperty */
+    uint8_t     repType;                /**< Input extension major opcode */
+    uint8_t     RepType;                /**< Always X_XIGetProperty */
     uint16_t    sequenceNumber;
     uint32_t    length;
     Atom        type;
@@ -733,10 +742,14 @@ typedef struct {
  *                                                                                   *
  *************************************************************************************/
 
+/**
+ * @struct xXIGenericDeviceEvent
+ * Generic XI2 event header. All XI2 events use the same header.
+ */
 typedef struct
 {
     uint8_t     type;
-    uint8_t     extension;              /* XI extension offset */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
     uint32_t    length;
     uint16_t    evtype;
@@ -744,147 +757,163 @@ typedef struct
     Time        time;
 } xXIGenericDeviceEvent;
 
-/***********************************************************
- *  DeviceHierarchyEvent
- *
+/**
+ * @struct xXIDeviceHierarchyEvent
+ * The device hierarchy has been modified. This event includes the device
+ * hierarchy after the modification has been applied.
+ */
+
+/**
+ * Device hierarch information.
  */
 typedef struct
 {
     uint16_t    deviceid;
-    uint16_t    attachment;
-    uint8_t     use;
-    BOOL        enabled;
+    uint16_t    attachment;             /**< ID of master or paired device */
+    uint8_t     use;                    /**< ::XIMasterKeyboard,
+                                             ::XIMasterPointer,
+                                             ::XISlaveKeyboard,
+                                             ::XISlavePointer,
+                                             ::XIFloatingSlave */
+    BOOL        enabled;                /**< TRUE if the device is enabled */
     uint16_t    pad;
 } xXIHierarchyInfo;
 
 typedef struct
 {
-    uint8_t     type;                   /* always GenericEvent */
-    uint8_t     extension;              /* XI extension offset */
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
-    uint32_t    length;
-    uint16_t    evtype;                 /* XI_Hierarchy */
+    uint32_t    length;                 /**< Length in 4 byte units */
+    uint16_t    evtype;                 /**< ::XI_Hierarchy */
     uint16_t    deviceid;
     Time        time;
-    uint32_t    flags;                  /* MasterAdded, MasterDeleted,
-                                           SlaveAttached, SlaveDetached,
-                                           SlaveAdded, SlaveRemoved,
-                                           DeviceEnabled, DeviceDisabled */
+    uint32_t    flags;                  /* ::XIMasterAdded, ::XIMasterDeleted,
+                                           ::XISlaveAttached, ::XISlaveDetached,
+                                           ::XISlaveAdded, ::XISlaveRemoved,
+                                           ::XIDeviceEnabled, ::XIDeviceDisabled */
     uint16_t    num_devices;
     uint16_t    pad0;
     uint32_t    pad1;
     uint32_t    pad2;
 } xXIDeviceHierarchyEvent;
 
-/***********************************************************
- *  DeviceChangedEvent
- *
+/**
+ * @struct xXIDeviceChangedEvent
+ * A device has changed capabilities.
  */
-
 typedef struct
 {
-    uint8_t     type;                /* always GenericEvent */
-    uint8_t     extension;           /* XI extension offset */
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
-    uint32_t    length;
-    uint16_t    evtype;              /* XI_DeviceChanged */
-    uint16_t    deviceid;            /* id of master */
+    uint32_t    length;                 /**< Length in 4 byte units */
+    uint16_t    evtype;                 /**< XI_DeviceChanged */
+    uint16_t    deviceid;               /**< Device that has changed */
     Time        time;
-    uint16_t    num_classes;         /* classes that have changed */
-    uint16_t    sourceid;            /* Source for the new classes*/
-    uint8_t     reason;              /* SlaveSwitch, DeviceChange */
+    uint16_t    num_classes;            /**< Number of classes that have changed */
+    uint16_t    sourceid;               /**< Source of the new classes */
+    uint8_t     reason;                 /**< ::XISlaveSwitch, ::XIDeviceChange */
     uint8_t     pad0;
     uint16_t    pad1;
     uint32_t    pad2;
     uint32_t    pad3;
 } xXIDeviceChangedEvent;
 
-/***********************************************************
- *  DeviceEvent
- *
+/**
+ * @struct xXIDeviceEvent
+ * Default input event for pointer or keyboard input.
  */
 
+/**
+ * XKB modifier information.
+ * The effective modifier is a binary mask of base, latched, and locked
+ * modifiers.
+ */
 typedef struct
 {
-    uint32_t    base_mods;
-    uint32_t    latched_mods;
-    uint32_t    locked_mods;
+    uint32_t    base_mods;              /**< Logically pressed modifiers */
+    uint32_t    latched_mods;           /**< Logically latched modifiers */
+    uint32_t    locked_mods;            /**< Logically locked modifiers */
 } xXIModifierInfo;
 
+/**
+ * XKB group information.
+ * The effective group is the mathematical sum of base, latched, and locked
+ * group after group wrapping is taken into account.
+ */
 typedef struct
 {
-    uint8_t     base_group;
-    uint8_t     latched_group;
-    uint8_t     locked_group;
+    uint8_t     base_group;             /**< Logically "pressed" group */
+    uint8_t     latched_group;          /**< Logically latched group */
+    uint8_t     locked_group;           /**< Logically locked group */
     uint8_t     pad0;
 } xXIGroupInfo;
 
 typedef struct
 {
-    uint8_t     type;                   /* always GenericEvent */
-    uint8_t     extension;              /* XI extension offset */
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
-    uint32_t    length;
+    uint32_t    length;                 /**< Length in 4 byte uints */
     uint16_t    evtype;
     uint16_t    deviceid;
     Time        time;
-    uint32_t    detail;                 /* keycode or button */
+    uint32_t    detail;                 /**< Keycode or button */
     Window      root;
     Window      event;
     Window      child;
 /* └──────── 32 byte boundary ────────┘ */
-    FP1616      root_x;                 /* always screen coords, 16.16 fixed point */
+    FP1616      root_x;                 /**< Always screen coords, 16.16 fixed point */
     FP1616      root_y;
-    FP1616      event_x;                /* always screen coords, 16.16 fixed point */
+    FP1616      event_x;                /**< Always screen coords, 16.16 fixed point */
     FP1616      event_y;
-    uint16_t    buttons_len;            /* len of button flags in 4 b units */
-    uint16_t    valuators_len;          /* len of val. flags in 4 b units */
-    uint16_t    sourceid;               /* the source device */
+    uint16_t    buttons_len;            /**< Len of button flags in 4 b units */
+    uint16_t    valuators_len;          /**< Len of val. flags in 4 b units */
+    uint16_t    sourceid;               /**< The source device */
     uint16_t    pad0;
     xXIModifierInfo     mods;
     xXIGroupInfo        group;
 } xXIDeviceEvent;
 
 
-
-/***********************************************************
- *  RawEvent
- *
+/**
+ * @struct xXIRawDeviceEvent
+ * Sent when an input event is generated. RawEvents include valuator
+ * information in both device-specific data (i.e. unaccelerated) and
+ * processed data (i.e. accelerated, if applicable).
  */
-
 typedef struct
 {
-    uint8_t     type;                   /* always GenericEvent */
-    uint8_t     extension;              /* XI extension offset */
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
-    uint32_t    length;
-    uint16_t    evtype;                 /* XI_RawEvent */
+    uint32_t    length;                 /**< Length in 4 byte uints */
+    uint16_t    evtype;                 /**< ::XI_RawEvent */
     uint16_t    deviceid;
     Time        time;
     uint32_t    detail;
-    uint16_t    eventtype;              /* XI_Motion, XI_ButtonPress,
-                                           XI_ButtonRelease, XI_KeyPress,
-                                           XI_KeyRelease */
-    uint16_t    valuators_len;
+    uint16_t    eventtype;              /**< ::XI_Motion, ::XI_ButtonPress,
+                                             ::XI_ButtonRelease, ::XI_KeyPress,
+                                             ::XI_KeyRelease */
+    uint16_t    valuators_len;          /**< Length of trailing valuator
+                                             mask in 4 byte units */
     uint32_t    pad1;
     uint32_t    pad2;
 } xXIRawDeviceEvent;
 
-/***********************************************************
- *  Enter/LeaveEvents
- *
- *  Note that the layout of root, event, child, root_x, root_y, event_x,
- *  event_y must be identical to the xXIDeviceEvent.
- *
+/**
+ * @struct xXIEnterEvent
+ * Note that the layout of root, event, child, root_x, root_y, event_x,
+ * event_y must be identical to the xXIDeviceEvent.
  */
-
 typedef struct
 {
-    uint8_t     type;                   /* always GenericEvent */
-    uint8_t     extension;              /* XI extension offset */
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
-    uint32_t    length;
-    uint16_t    evtype;                 /* XI_Enter */
+    uint32_t    length;                 /**< Length in 4 byte uints */
+    uint16_t    evtype;                 /**< ::XI_Enter */
     uint16_t    deviceid;
     Time        time;
     uint16_t    sourceid;
@@ -900,7 +929,8 @@ typedef struct
     FP1616      event_y;
     BOOL        same_screen;
     BOOL        focus;
-    uint16_t    buttons_len;
+    uint16_t    buttons_len;            /**< Length of trailing button mask
+                                             in 4 byte units */
     xXIModifierInfo     mods;
     xXIGroupInfo        group;
 } xXIEnterEvent;
@@ -909,22 +939,24 @@ typedef xXIEnterEvent xXILeaveEvent;
 typedef xXIEnterEvent xXIFocusInEvent;
 typedef xXIEnterEvent xXIFocusOutEvent;
 
-/***********************************************************
- *  PropertyEvents
- *
+/**
+ * @struct xXIPropertyEvent
+ * Sent when a device property is created, modified or deleted. Does not
+ * include property data, the client is required to query the data.
  */
-
 typedef struct
 {
-    uint8_t     type;                   /* always GenericEvent */
-    uint8_t     extension;              /* XI extension offset */
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
     uint16_t    sequenceNumber;
-    uint32_t    length;
-    uint16_t    evtype;                 /* XI_PropertyEvent */
+    uint32_t    length;                 /**< Length in 4 byte uints */
+    uint16_t    evtype;                 /**< ::XI_PropertyEvent */
     uint16_t    deviceid;
     Time        time;
     Atom        property;
-    uint8_t     what;
+    uint8_t     what;                   /**< ::XIPropertyDeleted,
+                                             ::XIPropertyCreated,
+                                             ::XIPropertyMotified */
     uint8_t     pad0;
     uint16_t    pad1;
     uint32_t    pad2;