[gtk+/treeview-refactor: 250/257] docs: Move documentation to inline comments: event_structs

[Tristan Van Berkom <tvb src gnome org>]

commit ccd740f1b6f35cbd083a18dba05510c0379c33d4
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Nov 15 20:41:44 2010 +0100

    docs: Move documentation to inline comments: event_structs
    
    All the GDK documentation is now moved to inline comments

 docs/reference/gdk/tmpl/.gitignore         |    1 +
 docs/reference/gdk/tmpl/event_structs.sgml |  548 ----------------------------
 gdk/gdkevents.h                            |  536 ++++++++++++++++++++++++++-
 gdk/gdktypes.h                             |    6 +
 4 files changed, 527 insertions(+), 564 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index cca0643..4f1e66c 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -4,6 +4,7 @@ cursors.sgml
 dnd.sgml
 drawing.sgml
 events.sgml
+event_structs.sgml
 gdkapplaunchcontext.sgml
 gdkdisplay.sgml
 gdkdisplaymanager.sgml
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 9dd7e52..caecd97 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -38,6 +38,23 @@
 
 G_BEGIN_DECLS
 
+
+/**
+ * SECTION:event_structs
+ * @Short_description: Data structures specific to each type of event
+ * @Title: Event Structures
+ *
+ * The event structs contain data specific to each type of event in GDK.
+ *
+ * <note>
+ * <para>
+ * A common mistake is to forget to set the event mask of a widget so that
+ * the required events are received. See gtk_widget_set_events().
+ * </para>
+ * </note>
+ */
+
+
 #define GDK_TYPE_EVENT          (gdk_event_get_type ())
 
 /**
@@ -251,6 +268,14 @@ typedef enum
   GDK_EVENT_LAST        /* helper variable for decls */
 } GdkEventType;
 
+/**
+ * GdkVisibilityState:
+ * @GDK_VISIBILITY_UNOBSCURED: the window is completely visible.
+ * @GDK_VISIBILITY_PARTIAL: the window is partially visible.
+ * @GDK_VISIBILITY_FULLY_OBSCURED: the window is not visible at all.
+ *
+ * Specifies the visiblity status of a window for a #GdkEventVisibility.
+ */
 typedef enum
 {
   GDK_VISIBILITY_UNOBSCURED,
@@ -258,6 +283,15 @@ typedef enum
   GDK_VISIBILITY_FULLY_OBSCURED
 } GdkVisibilityState;
 
+/**
+ * GdkScrollDirection:
+ * @GDK_SCROLL_UP: the window is scrolled up.
+ * @GDK_SCROLL_DOWN: the window is scrolled down.
+ * @GDK_SCROLL_LEFT: the window is scrolled to the left.
+ * @GDK_SCROLL_RIGHT: the window is scrolled to the right.
+ *
+ * Specifies the direction for #GdkEventScroll.
+ */
 typedef enum
 {
   GDK_SCROLL_UP,
@@ -266,13 +300,26 @@ typedef enum
   GDK_SCROLL_RIGHT
 } GdkScrollDirection;
 
-/* Types of enter/leave notifications.
- *   Ancestor:
- *   Virtual:
- *   Inferior:
- *   Nonlinear:
- *   NonlinearVirtual:
- *   Unknown: An unknown type of enter/leave event occurred.
+/**
+ * GdkNotifyType:
+ * @GDK_NOTIFY_ANCESTOR: the window is entered from an ancestor or
+ *   left towards an ancestor.
+ * @GDK_NOTIFY_VIRTUAL: the pointer moves between an ancestor and an
+ *   inferior of the window.
+ * @GDK_NOTIFY_INFERIOR: the window is entered from an inferior or
+ *   left towards an inferior.
+ * @GDK_NOTIFY_NONLINEAR: the window is entered from or left towards
+ *   a window which is neither an ancestor nor an inferior.
+ * @GDK_NOTIFY_NONLINEAR_VIRTUAL: the pointer moves between two windows
+ *   which are not ancestors of each other and the window is part of
+ *   the ancestor chain between one of these windows and their least
+ *   common ancestor.
+ * @GDK_NOTIFY_UNKNOWN: an unknown type of enter/leave event occurred.
+ *
+ * Specifies the kind of crossing for #GdkEventCrossing.
+ *
+ * See the X11 protocol specification of <type>LeaveNotify</type> for
+ * full details of crossing event generation.
  */
 typedef enum
 {
@@ -284,10 +331,17 @@ typedef enum
   GDK_NOTIFY_UNKNOWN		= 5
 } GdkNotifyType;
 
-/* Enter/leave event modes.
- *   NotifyNormal
- *   NotifyGrab
- *   NotifyUngrab
+/**
+ * GdkCrossingMode:
+ * @GDK_CROSSING_NORMAL: crossing because of pointer motion.
+ * @GDK_CROSSING_GRAB: crossing because a grab is activated.
+ * @GDK_CROSSING_UNGRAB: crossing because a grab is deactivated.
+ * @GDK_CROSSING_GTK_GRAB: crossing because a GTK+ grab is activated.
+ * @GDK_CROSSING_GTK_UNGRAB: crossing because a GTK+ grab is deactivated.
+ * @GDK_CROSSING_STATE_CHANGED: crossing because a GTK+ widget changed
+ *   state (e.g. sensitivity).
+ *
+ * Specifies the crossing mode for #GdkEventCrossing.
  */
 typedef enum
 {
@@ -299,12 +353,32 @@ typedef enum
   GDK_CROSSING_STATE_CHANGED
 } GdkCrossingMode;
 
+/**
+ * GdkPropertyState:
+ * @GDK_PROPERTY_NEW_VALUE: the property value was changed.
+ * @GDK_PROPERTY_DELETE: the property was deleted.
+ *
+ * Specifies the type of a property change for a #GdkEventProperty.
+ */
 typedef enum
 {
   GDK_PROPERTY_NEW_VALUE,
   GDK_PROPERTY_DELETE
 } GdkPropertyState;
 
+/**
+ * GdkWindowState:
+ * @GDK_WINDOW_STATE_WITHDRAWN: the window is not shown.
+ * @GDK_WINDOW_STATE_ICONIFIED: the window is minimized.
+ * @GDK_WINDOW_STATE_MAXIMIZED: the window is maximized.
+ * @GDK_WINDOW_STATE_STICKY: the window is sticky.
+ * @GDK_WINDOW_STATE_FULLSCREEN: the window is maximized without
+ *   decorations.
+ * @GDK_WINDOW_STATE_ABOVE: the window is kept above other windows.
+ * @GDK_WINDOW_STATE_BELOW: the window is kept below other windows.
+ *
+ * Specifies the state of a toplevel window.
+ */
 typedef enum
 {
   GDK_WINDOW_STATE_WITHDRAWN  = 1 << 0,
@@ -316,6 +390,15 @@ typedef enum
   GDK_WINDOW_STATE_BELOW      = 1 << 6
 } GdkWindowState;
 
+/**
+ * GdkSettingAction:
+ * @GDK_SETTING_ACTION_NEW: a setting was added.
+ * @GDK_SETTING_ACTION_CHANGED: a setting was changed.
+ * @GDK_SETTING_ACTION_DELETED: a setting was deleted.
+ *
+ * Specifies the kind of modification applied to a setting in a
+ * #GdkEventSetting.
+ */
 typedef enum
 {
   GDK_SETTING_ACTION_NEW,
@@ -323,6 +406,14 @@ typedef enum
   GDK_SETTING_ACTION_DELETED
 } GdkSettingAction;
 
+/**
+ * GdkOwnerChange:
+ * @GDK_OWNER_CHANGE_NEW_OWNER: some other app claimed the ownership
+ * @GDK_OWNER_CHANGE_DESTROY: the window was destroyed
+ * @GDK_OWNER_CHANGE_CLOSE: the client was closed
+ *
+ * Specifies why a selection ownership was changed.
+ */
 typedef enum
 {
   GDK_OWNER_CHANGE_NEW_OWNER,
@@ -330,6 +421,17 @@ typedef enum
   GDK_OWNER_CHANGE_CLOSE
 } GdkOwnerChange;
 
+/**
+ * GdkEventAny:
+ * @type: the type of the event.
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ *
+ * Contains the fields which are common to all event structs.
+ * Any event pointer can safely be cast to a pointer to a #GdkEventAny to
+ * access these fields.
+ */
 struct _GdkEventAny
 {
   GdkEventType type;
@@ -337,6 +439,22 @@ struct _GdkEventAny
   gint8 send_event;
 };
 
+/**
+ * GdkEventExpose:
+ * @type: the type of the event (%GDK_EXPOSE or %GDK_DAMAGE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @area: bounding box of @region.
+ * @region: the region that needs to be redrawn.
+ * @count: the number of contiguous %GDK_EXPOSE events following this one.
+ *   The only use for this is "exposure compression", i.e. handling all
+ *   contiguous %GDK_EXPOSE events in one go, though GDK performs some
+ *   exposure compression so this is not normally needed.
+ *
+ * Generated when all or part of a window becomes visible and needs to be
+ * redrawn.
+ */
 struct _GdkEventExpose
 {
   GdkEventType type;
@@ -347,6 +465,16 @@ struct _GdkEventExpose
   gint count; /* If non-zero, how many more events follow. */
 };
 
+/**
+ * GdkEventNoExpose:
+ * @type: the type of the event (%GDK_NO_EXPOSE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ *
+ * Generated when the area of a #GdkDrawable being copied was completely
+ * available.
+ */
 struct _GdkEventNoExpose
 {
   GdkEventType type;
@@ -354,6 +482,17 @@ struct _GdkEventNoExpose
   gint8 send_event;
 };
 
+/**
+ * GdkEventVisibility:
+ * @type: the type of the event (%GDK_VISIBILITY_NOTIFY).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @state: the new visibility state (%GDK_VISIBILITY_FULLY_OBSCURED,
+ *   %GDK_VISIBILITY_PARTIAL or %GDK_VISIBILITY_UNOBSCURED).
+ *
+ * Generated when the window visibility status has changed.
+ */
 struct _GdkEventVisibility
 {
   GdkEventType type;
@@ -362,6 +501,29 @@ struct _GdkEventVisibility
   GdkVisibilityState state;
 };
 
+/**
+ * GdkEventMotion:
+ * @type: the type of the event.
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @time: the time of the event in milliseconds.
+ * @x: the x coordinate of the pointer relative to the window.
+ * @y: the y coordinate of the pointer relative to the window.
+ * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
+ *   the mouse.
+ * @state: a bit-mask representing the state of the modifier keys (e.g.
+ *   Control, Shift and Alt) and the pointer buttons. See #GdkModifierType.
+ * @is_hint: set to 1 if this event is just a hint, see the
+ *   %GDK_POINTER_MOTION_HINT_MASK value of #GdkEventMask.
+ * @device: the device where the event originated.
+ * @x_root: the x coordinate of the pointer relative to the root of the
+ *   screen.
+ * @y_root: the y coordinate of the pointer relative to the root of the
+ *   screen.
+ *
+ * Generated when the pointer moves.
+ */
 struct _GdkEventMotion
 {
   GdkEventType type;
@@ -377,6 +539,65 @@ struct _GdkEventMotion
   gdouble x_root, y_root;
 };
 
+/**
+ * GdkEventButton:
+ * @type: the type of the event (%GDK_BUTTON_PRESS, %GDK_2BUTTON_PRESS,
+ *   %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @time: the time of the event in milliseconds.
+ * @x: the x coordinate of the pointer relative to the window.
+ * @y: the y coordinate of the pointer relative to the window.
+ * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
+ *   the mouse.
+ * @state: a bit-mask representing the state of the modifier keys (e.g.
+ *   Control, Shift and Alt) and the pointer buttons. See #GdkModifierType.
+ * @button: the button which was pressed or released, numbered from 1 to 5.
+ *   Normally button 1 is the left mouse button, 2 is the middle button,
+ *   and 3 is the right button. On 2-button mice, the middle button can
+ *   often be simulated by pressing both mouse buttons together.
+ * @device: the device where the event originated.
+ * @x_root: the x coordinate of the pointer relative to the root of the
+ *   screen.
+ * @y_root: the y coordinate of the pointer relative to the root of the
+ *   screen.
+ *
+ * Used for button press and button release events. The
+ * @type field will be one of %GDK_BUTTON_PRESS,
+ * %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, and %GDK_BUTTON_RELEASE.
+ *
+ * Double and triple-clicks result in a sequence of events being received.
+ * For double-clicks the order of events will be:
+ * <orderedlist>
+ * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+ * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+ * </orderedlist>
+ * Note that the first click is received just like a normal
+ * button press, while the second click results in a %GDK_2BUTTON_PRESS
+ * being received just after the %GDK_BUTTON_PRESS.
+ *
+ * Triple-clicks are very similar to double-clicks, except that
+ * %GDK_3BUTTON_PRESS is inserted after the third click. The order of the
+ * events is:
+ * <orderedlist>
+ * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+ * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+ * <listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
+ * <listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+ * </orderedlist>
+ *
+ * For a double click to occur, the second button press must occur within
+ * 1/4 of a second of the first. For a triple click to occur, the third
+ * button press must also occur within 1/2 second of the first button press.
+ */
 struct _GdkEventButton
 {
   GdkEventType type;
@@ -392,6 +613,29 @@ struct _GdkEventButton
   gdouble x_root, y_root;
 };
 
+/**
+ * GdkEventScroll:
+ * @type: the type of the event (%GDK_SCROLL).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @time: the time of the event in milliseconds.
+ * @x: the x coordinate of the pointer relative to the window.
+ * @y: the y coordinate of the pointer relative to the window.
+ * @state: a bit-mask representing the state of the modifier keys (e.g.
+ *   Control, Shift and Alt) and the pointer buttons. See #GdkModifierType.
+ * @direction: the direction to scroll to (one of %GDK_SCROLL_UP,
+ *   %GDK_SCROLL_DOWN, %GDK_SCROLL_LEFT and %GDK_SCROLL_RIGHT).
+ * @device: the device where the event originated.
+ * @x_root: the x coordinate of the pointer relative to the root of the
+ *   screen.
+ * @y_root: the y coordinate of the pointer relative to the root of the
+ *   screen.
+ *
+ * Generated from button presses for the buttons 4 to 7. Wheel mice are
+ * usually configured to generate button press events for buttons 4 and 5
+ * when the wheel is turned.
+ */
 struct _GdkEventScroll
 {
   GdkEventType type;
@@ -406,6 +650,37 @@ struct _GdkEventScroll
   gdouble x_root, y_root;
 };
 
+/**
+ * GdkEventKey:
+ * @type: the type of the event (%GDK_KEY_PRESS or %GDK_KEY_RELEASE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @time: the time of the event in milliseconds.
+ * @state: a bit-mask representing the state of the modifier keys (e.g.
+ *   Control, Shift and Alt) and the pointer buttons. See #GdkModifierType.
+ * @keyval: the key that was pressed or released. See the
+ *   <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file for a
+ *   complete list of GDK key codes.
+ * @length: the length of @string.
+ * @string: a string containing the an approximation of the text that
+ *   would result from this keypress. The only correct way to handle text
+ *   input of text is using input methods (see #GtkIMContext), so this
+ *   field is deprecated and should never be used.
+ *   (gdk_unicode_to_keyval() provides a non-deprecated way of getting
+ *   an approximate translation for a key.) The string is encoded in the
+ *   encoding of the current locale (Note: this for backwards compatibility:
+ *   strings in GTK+ and GDK are typically in UTF-8.) and NUL-terminated.
+ *   In some cases, the translation of the key code will be a single
+ *   NUL byte, in which case looking at @length is necessary to distinguish
+ *   it from the an empty translation.
+ * @hardware_keycode: the raw code of the key that was pressed or released.
+ * @group: the keyboard group.
+ * @is_modifier: a flag that indicates if @hardware_keycode is mapped to a
+ *   modifier. Since 2.10
+ *
+ * Describes a key press or key release event.
+ */
 struct _GdkEventKey
 {
   GdkEventType type;
@@ -421,6 +696,32 @@ struct _GdkEventKey
   guint is_modifier : 1;
 };
 
+/**
+ * GdkEventCrossing:
+ * @type: the type of the event (%GDK_ENTER_NOTIFY or %GDK_LEAVE_NOTIFY).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *  <function>XSendEvent</function>).
+ * @subwindow: the window that was entered or left.
+ * @time: the time of the event in milliseconds.
+ * @x: the x coordinate of the pointer relative to the window.
+ * @y: the y coordinate of the pointer relative to the window.
+ * @x_root: the x coordinate of the pointer relative to the root of the screen.
+ * @y_root: the y coordinate of the pointer relative to the root of the screen.
+ * @mode: the crossing mode (%GDK_CROSSING_NORMAL, %GDK_CROSSING_GRAB,
+ *  %GDK_CROSSING_UNGRAB, %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB or
+ *  %GDK_CROSSING_STATE_CHANGED).  %GDK_CROSSING_GTK_GRAB, %GDK_CROSSING_GTK_UNGRAB,
+ *  and %GDK_CROSSING_STATE_CHANGED were added in 2.14 and are always synthesized,
+ *  never native.
+ * @detail: the kind of crossing that happened (%GDK_NOTIFY_INFERIOR,
+ *  %GDK_NOTIFY_ANCESTOR, %GDK_NOTIFY_VIRTUAL, %GDK_NOTIFY_NONLINEAR or
+ *  %GDK_NOTIFY_NONLINEAR_VIRTUAL).
+ * @focus: %TRUE if @window is the focus window or an inferior.
+ * @state: a bit-mask representing the state of the modifier keys (e.g. Control,
+ *  Shift and Alt) and the pointer buttons. See #GdkModifierType.
+ *
+ * Generated when the pointer enters or leaves a window.
+ */
 struct _GdkEventCrossing
 {
   GdkEventType type;
@@ -438,6 +739,17 @@ struct _GdkEventCrossing
   guint state;
 };
 
+/**
+ * GdkEventFocus:
+ * @type: the type of the event (%GDK_FOCUS_CHANGE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @in: %TRUE if the window has gained the keyboard focus, %FALSE if
+ *   it has lost the focus.
+ *
+ * Describes a change of keyboard focus.
+ */
 struct _GdkEventFocus
 {
   GdkEventType type;
@@ -446,6 +758,19 @@ struct _GdkEventFocus
   gint16 in;
 };
 
+/**
+ * GdkEventConfigure:
+ * @type: the type of the event (%GDK_CONFIGURE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @x: the new x coordinate of the window, relative to its parent.
+ * @y: the new y coordinate of the window, relative to its parent.
+ * @width: the new width of the window.
+ * @height: the new height of the window.
+ *
+ * Generated when a window size or position has changed.
+ */
 struct _GdkEventConfigure
 {
   GdkEventType type;
@@ -456,6 +781,19 @@ struct _GdkEventConfigure
   gint height;
 };
 
+/**
+ * GdkEventProperty:
+ * @type: the type of the event (%GDK_PROPERTY_NOTIFY).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @atom: the property that was changed.
+ * @time: the time of the event in milliseconds.
+ * @state: whether the property was changed (%GDK_PROPERTY_NEW_VALUE) or
+ *   deleted (%GDK_PROPERTY_DELETE).
+ *
+ * Describes a property change on a window.
+ */
 struct _GdkEventProperty
 {
   GdkEventType type;
@@ -466,6 +804,22 @@ struct _GdkEventProperty
   guint state;
 };
 
+/**
+ * GdkEventSelection:
+ * @type: the type of the event (%GDK_SELECTION_CLEAR,
+ *   %GDK_SELECTION_NOTIFY or %GDK_SELECTION_REQUEST).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @selection: the selection.
+ * @target: the target to which the selection should be converted.
+ * @property: the property in which to place the result of the conversion.
+ * @time: the time of the event in milliseconds.
+ * @requestor: the native window on which to place @property.
+ *
+ * Generated when a selection is requested or ownership of a selection
+ * is taken over by another client application.
+ */
 struct _GdkEventSelection
 {
   GdkEventType type;
@@ -478,6 +832,25 @@ struct _GdkEventSelection
   GdkNativeWindow requestor;
 };
 
+/**
+ * GdkEventOwnerChange:
+ * @type: the type of the event (%GDK_OWNER_CHANGE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @owner: the new owner of the selection.
+ * @reason: the reason for the ownership change as a #GdkOwnerChange value.
+ * @selection: the atom identifying the selection.
+ * @time: the timestamp of the event.
+ * @selection_time: the time at which the selection ownership was taken
+ *   over.
+ *
+ * Generated when the owner of a selection changes. On X11, this
+ * information is only available if the X server supports the XFIXES
+ * extension.
+ *
+ * Since: 2.6
+ */
 struct _GdkEventOwnerChange
 {
   GdkEventType type;
@@ -490,9 +863,24 @@ struct _GdkEventOwnerChange
   guint32 selection_time;
 };
 
-/* This event type will be used pretty rarely. It only is important
-   for XInput aware programs that are drawing their own cursor */
-
+/**
+ * GdkEventProximity:
+ * @type: the type of the event (%GDK_PROXIMITY_IN or %GDK_PROXIMITY_OUT).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using <function>XSendEvent</function>).
+ * @time: the time of the event in milliseconds.
+ * @device: the device where the event originated.
+ *
+ * Proximity events are generated when using GDK's wrapper for the
+ * XInput extension. The XInput extension is an add-on for standard X
+ * that allows you to use nonstandard devices such as graphics tablets.
+ * A proximity event indicates that the stylus has moved in or out of
+ * contact with the tablet, or perhaps that the user's finger has moved
+ * in or out of contact with a touch screen.
+ *
+ * This event type will be used pretty rarely. It only is important for
+ * XInput aware programs that are drawing their own cursor.
+ */
 struct _GdkEventProximity
 {
   GdkEventType type;
@@ -502,6 +890,21 @@ struct _GdkEventProximity
   GdkDevice *device;
 };
 
+/**
+ * GdkEventClient:
+ * @type: the type of the event (%GDK_CLIENT_EVENT).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @message_type: the type of the message, which can be defined by the
+ *   application.
+ * @data_format: the format of the data, given as the number of bits in each
+ *   data element, i.e. 8, 16, or 32. 8-bit data uses the b array of the
+ *   data union, 16-bit data uses the s array, and 32-bit data uses the l
+ *   array.
+ *
+ * An event sent by another client application.
+ */
 struct _GdkEventClient
 {
   GdkEventType type;
@@ -516,6 +919,18 @@ struct _GdkEventClient
   } data;
 };
 
+/**
+ * GdkEventSetting:
+ * @type: the type of the event (%GDK_SETTING).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @action: what happened to the setting (%GDK_SETTING_ACTION_NEW,
+ *   %GDK_SETTING_ACTION_CHANGED or %GDK_SETTING_ACTION_DELETED).
+ * @name: the name of the setting.
+ *
+ * Generated when a setting is modified.
+ */
 struct _GdkEventSetting
 {
   GdkEventType type;
@@ -525,6 +940,18 @@ struct _GdkEventSetting
   char *name;
 };
 
+/**
+ * GdkEventWindowState:
+ * @type: the type of the event (%GDK_WINDOW_STATE).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @changed_mask: mask specifying what flags have changed.
+ * @new_window_state: the new window state, a combination of
+ *   #GdkWindowState bits.
+ *
+ * Generated when the state of a toplevel window changes.
+ */
 struct _GdkEventWindowState
 {
   GdkEventType type;
@@ -534,6 +961,28 @@ struct _GdkEventWindowState
   GdkWindowState new_window_state;
 };
 
+/**
+ * GdkEventGrabBroken:
+ * @type: the type of the event (%GDK_GRAB_BROKEN)
+ * @window: the window which received the event, i.e. the window
+ *   that previously owned the grab
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @keyboard: %TRUE if a keyboard grab was broken, %FALSE if a pointer
+ *   grab was broken
+ * @implicit: %TRUE if the broken grab was implicit
+ * @grab_window: If this event is caused by another grab in the same
+ *   application, @grab_window contains the new grab window. Otherwise
+ *   @grab_window is %NULL.
+ *
+ * Generated when a pointer or keyboard grab is broken. On X11, this happens
+ * when the grab window becomes unviewable (i.e. it or one of its ancestors
+ * is unmapped), or if the same application grabs the pointer or keyboard
+ * again. Note that implicit grabs (which are initiated by button presses)
+ * can also cause #GdkEventGrabBroken events.
+ *
+ * Since: 2.8
+ */
 struct _GdkEventGrabBroken {
   GdkEventType type;
   GdkWindow *window;
@@ -543,8 +992,23 @@ struct _GdkEventGrabBroken {
   GdkWindow *grab_window;
 };
 
-/* Event types for DND */
-
+/**
+ * GdkEventDND:
+ * @type: the type of the event (%GDK_DRAG_ENTER, %GDK_DRAG_LEAVE,
+ *   %GDK_DRAG_MOTION, %GDK_DRAG_STATUS, %GDK_DROP_START or
+ *   %GDK_DROP_FINISHED).
+ * @window: the window which received the event.
+ * @send_event: %TRUE if the event was sent explicitly (e.g. using
+ *   <function>XSendEvent</function>).
+ * @context: the #GdkDragContext for the current DND operation.
+ * @time: the time of the event in milliseconds.
+ * @x_root: the x coordinate of the pointer relative to the root of the
+ *   screen, only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
+ * @y_root: the y coordinate of the pointer relative to the root of the
+ *   screen, only set for %GDK_DRAG_MOTION and %GDK_DROP_START.
+ *
+ * Generated during DND operations.
+ */
 struct _GdkEventDND {
   GdkEventType type;
   GdkWindow *window;
@@ -555,6 +1019,46 @@ struct _GdkEventDND {
   gshort x_root, y_root;
 };
 
+/**
+ * GdkEvent:
+ *
+ * The #GdkEvent struct contains a union of all of the event structs,
+ * and allows access to the data fields in a number of ways.
+ *
+ * The event type is always the first field in all of the event structs, and
+ * can always be accessed with the following code, no matter what type of
+ * event it is:
+ * <informalexample>
+ * <programlisting>
+ *   GdkEvent *event;
+ *   GdkEventType type;
+ *
+ *   type = event->type;
+ * </programlisting>
+ * </informalexample>
+ *
+ * To access other fields of the event structs, the pointer to the event
+ * can be cast to the appropriate event struct pointer, or the union member
+ * name can be used. For example if the event type is %GDK_BUTTON_PRESS
+ * then the x coordinate of the button press can be accessed with:
+ * <informalexample>
+ * <programlisting>
+ *   GdkEvent *event;
+ *   gdouble x;
+ *
+ *   x = ((GdkEventButton*)event)->x;
+ * </programlisting>
+ * </informalexample>
+ * or:
+ * <informalexample>
+ * <programlisting>
+ *   GdkEvent *event;
+ *   gdouble x;
+ *
+ *   x = event->button.x;
+ * </programlisting>
+ * </informalexample>
+ */
 union _GdkEvent
 {
   GdkEventType		    type;
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index a7c1e57..417aec2 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -120,6 +120,12 @@ typedef struct _GdkAtom            *GdkAtom;
  */
 #define GDK_NONE            _GDK_MAKE_ATOM (0)
 
+/**
+ * GdkNativeWindow:
+ *
+ * Used to represent native windows (<type>Window</type>s for the X11
+ * backend, <type>HWND</type>s for Win32).
+ */
 #ifdef GDK_NATIVE_WINDOW_POINTER
 typedef gpointer GdkNativeWindow;
 #else