Move documentation to inline comments: GdkWindow

Use examples/gdk to store documentation code examples.

Fixes https://bugzilla.gnome.org/show_bug.cgi?id=618498

Signed-off-by: Javier Jardón <jjardon@gnome.org>

6 files changed, 429 insertions, 39 deletions

diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 72b9e4246a..2f7a09b8d5 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -72,10 +72,25 @@ typedef void (*GdkEventFunc) (GdkEvent *event,
 
 /* Event filtering */
 
+/**
+ * GdkXEvent:
+ *
+ * Used to represent native events (<type>XEvent</type>s for the X11
+ * backend, <type>MSG</type>s for Win32).
+ */
 typedef void GdkXEvent;	  /* Can be cast to window system specific
 			   * even type, XEvent on X11, MSG on Win32.
 			   */
 
+/**
+ * GdkFilterReturn:
+ * @GDK_FILTER_CONTINUE: event not handled, continue processing.
+ * @GDK_FILTER_TRANSLATE: native event translated into a GDK event and stored
+ *  in the <literal>event</literal> structure that was passed in.
+ * @GDK_FILTER_REMOVE: event handled, terminate processing.
+ *
+ * Specifies the result of applying a #GdkFilterFunc to a native event.
+ */
 typedef enum {
   GDK_FILTER_CONTINUE,	  /* Event not handled, continue processesing */
   GDK_FILTER_TRANSLATE,	  /* Native event translated into a GDK event and
@@ -84,6 +99,23 @@ typedef enum {
   GDK_FILTER_REMOVE	  /* Terminate processing, removing event */
 } GdkFilterReturn;
 
+/**
+ * GdkFilterFunc:
+ * @xevent: the native event to filter.
+ * @event: the GDK event to which the X event will be translated.
+ * @data: user data set when the filter was installed.
+ *
+ * Specifies the type of function used to filter native events before they are
+ * converted to GDK events.
+ *
+ * When a filter is called, @event is unpopulated, except for
+ * <literal>event->window</literal>. The filter may translate the native
+ * event to a GDK event and store the result in @event, or handle it without
+ * translation. If the filter translates the event and processing should
+ * continue, it should return %GDK_FILTER_TRANSLATE.
+ *
+ * Returns: a #GdkFilterReturn value.
+ */
 typedef GdkFilterReturn (*GdkFilterFunc) (GdkXEvent *xevent,
 					  GdkEvent *event,
 					  gpointer  data);
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index ae9362f70f..78748dc3d3 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -56,6 +56,13 @@
 
 /* some common magic values */
 #define GDK_CURRENT_TIME     0L
+
+/**
+ * GDK_PARENT_RELATIVE:
+ *
+ * A special value for #GdkPixmap variables, indicating that the background
+ * pixmap for a window should be inherited from the parent window.
+ */
 #define GDK_PARENT_RELATIVE  1L
 
 
@@ -111,6 +118,15 @@ typedef struct _GdkVisual             GdkVisual;
 typedef struct _GdkDrawable           GdkDrawable;
 typedef struct _GdkDrawable           GdkBitmap;
 typedef struct _GdkDrawable           GdkPixmap;
+
+/**
+ * GdkWindow:
+ *
+ * An opaque structure representing an onscreen drawable. Pointers to structures
+ * of type #GdkPixmap, #GdkBitmap, and #GdkWindow can often be used
+ * interchangeably. The type #GdkDrawable refers generically to any of these
+ * types.
+ */
 typedef struct _GdkDrawable           GdkWindow;
 typedef struct _GdkDisplay	      GdkDisplay;
 typedef struct _GdkScreen	      GdkScreen;
@@ -123,6 +139,45 @@ typedef enum
 
 /* Types of modifiers.
  */
+/**
+ * GdkModifierType:
+ * @GDK_SHIFT_MASK: the Shift key.
+ * @GDK_LOCK_MASK: a Lock key (depending on the modifier mapping of the
+ *  X server this may either be CapsLock or ShiftLock).
+ * @GDK_CONTROL_MASK: the Control key.
+ * @GDK_MOD1_MASK: the fourth modifier key (it depends on the modifier
+ *  mapping of the X server which key is interpreted as this modifier, but
+ *  normally it is the Alt key).
+ * @GDK_MOD2_MASK: the fifth modifier key (it depends on the modifier
+ *  mapping of the X server which key is interpreted as this modifier).
+ * @GDK_MOD3_MASK: the sixth modifier key (it depends on the modifier
+ *  mapping of the X server which key is interpreted as this modifier).
+ * @GDK_MOD4_MASK: the seventh modifier key (it depends on the modifier
+ *  mapping of the X server which key is interpreted as this modifier).
+ * @GDK_MOD5_MASK: the eighth modifier key (it depends on the modifier
+ *  mapping of the X server which key is interpreted as this modifier).
+ * @GDK_BUTTON1_MASK: the first mouse button.
+ * @GDK_BUTTON2_MASK: the second mouse button.
+ * @GDK_BUTTON3_MASK: the third mouse button.
+ * @GDK_BUTTON4_MASK: the fourth mouse button.
+ * @GDK_BUTTON5_MASK: the fifth mouse button.
+ * @GDK_SUPER_MASK: the Super modifier. Since 2.10
+ * @GDK_HYPER_MASK: the Hyper modifier. Since 2.10
+ * @GDK_META_MASK: the Meta modifier. Since 2.10
+ * @GDK_RELEASE_MASK: not used in GDK itself. GTK+ uses it to differentiate
+ *  between (keyval, modifiers) pairs from key press and release events.
+ * @GDK_MODIFIER_MASK: a mask covering all modifier types.
+ *
+ * A set of bit-flags to indicate the state of modifier keys and mouse buttons
+ * in various event types. Typical modifier keys are Shift, Control, Meta,
+ * Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock.
+ *
+ * Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons.
+ *
+ * Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped
+ * to Mod2 - Mod5, and indicates this by setting %GDK_SUPER_MASK,
+ * %GDK_HYPER_MASK or %GDK_META_MASK in the state field of key events.
+ */
 typedef enum
 {
   GDK_SHIFT_MASK    = 1 << 0,
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index e264feb86c..d4895ebfe0 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -25,6 +25,69 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
+/**
+ * SECTION:windows
+ * @Short_description: Onscreen display areas in the target window system
+ * @Title: Windows
+ *
+ * A #GdkWindow is a rectangular region on the screen. It's a low-level object,
+ * used to implement high-level objects such as #GtkWidget and #GtkWindow on the
+ * GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think
+ * of as a "window" with a titlebar and so on; a #GtkWindow may contain many
+ * #GdkWindow<!-- -->s. For example, each #GtkButton has a #GdkWindow associated
+ * with it.
+ *
+ * <refsect2 id="COMPOSITED-WINDOWS">
+ * <title>Composited Windows</title>
+ * <para>
+ * Normally, the windowing system takes care of rendering the contents of a
+ * child window onto its parent window. This mechanism can be intercepted by
+ * calling gdk_window_set_composited() on the child window. For a
+ * <firstterm>composited</firstterm> window it is the responsibility of the
+ * application to render the window contents at the right spot.
+ * </para>
+ * <example id="composited-window-example">
+ * <title>Composited windows</title>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../examples/gdk/composited-window-example.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>
+ * </programlisting></example>
+ * <para>
+ * In the example <xref linkend="composited-window-example"/>, a button is
+ * placed inside of an event box inside of a window. The event box is set as
+ * composited and therefore is no longer automatically drawn to the screen.
+ *
+ * When the contents of the event box change, an expose event is generated on
+ * it's parent window (which, in this case, belongs to the toplevel #GtkWindow).
+ * The expose handler for this widget is responsible for merging the changes
+ * back on the screen in the way that it wishes.
+ *
+ * In our case, we merge the contents with a 50% transparency. We also set the
+ * background colour of the window to red. The effect is that the background
+ * shows through the button.
+ * </para>
+ * </refsect2>
+ * <refsect2 id="OFFSCREEN-WINDOWS">
+ * <title>Offscreen Windows</title>
+ * <para>
+ * Offscreen windows are more general than composited windows, since they allow
+ * not only to modify the rendering of the child window onto its parent, but
+ * also to apply coordinate transformations.
+ *
+ * To integrate an offscreen window into a window hierarchy, one has to call
+ * gdk_offscreen_window_set_embedder() and handle a number of signals. The
+ * #GdkWindow::pick-embedded-child signal on the embedder window is used to
+ * select an offscreen child at given coordinates, and the
+ * #GdkWindow::to-embedder and #GdkWindow::from-embedder signals on the
+ * offscreen window are used to translate coordinates between the embedder and
+ * the offscreen window.
+ *
+ * For rendering an offscreen window onto its embedder, the contents of the
+ * offscreen window are available as a pixmap, via
+ * gdk_offscreen_window_get_pixmap().
+ * </para>
+ * </refsect2>
+ */
+
 #include "config.h"
 #include "gdkwindow.h"
 #include "gdkwindowimpl.h"
diff --git a/gdk/gdkwindow.h b/gdk/gdkwindow.h
index 5d2ade8168..ee3c89ee20 100644
--- a/gdk/gdkwindow.h
+++ b/gdk/gdkwindow.h
@@ -42,14 +42,16 @@ typedef struct _GdkWindowAttr        GdkWindowAttr;
 typedef struct _GdkPointerHooks      GdkPointerHooks;
 typedef struct _GdkWindowRedirect    GdkWindowRedirect;
 
-/* Classes of windows.
- *   InputOutput: Almost every window should be of this type. Such windows
- *		  receive events and are also displayed on screen.
- *   InputOnly: Used only in special circumstances when events need to be
- *		stolen from another window or windows. Input only windows
- *		have no visible output, so they are handy for placing over
- *		top of a group of windows in order to grab the events (or
- *		filter the events) from those windows.
+/**
+ * GdkWindowClass:
+ * @GDK_INPUT_OUTPUT: window for graphics and events
+ * @GDK_INPUT_ONLY: window for events only
+ *
+ * @GDK_INPUT_OUTPUT windows are the standard kind of window you might expect.
+ * Such windows receive events and are also displayed on screen.
+ * @GDK_INPUT_ONLY windows are invisible; they are usually placed above other
+ * windows in order to trap or filter the events. You can't draw on
+ * @GDK_INPUT_ONLY windows.
  */
 typedef enum
 {
@@ -57,18 +59,20 @@ typedef enum
   GDK_INPUT_ONLY
 } GdkWindowClass;
 
-/* Types of windows.
- *   Root: There is only 1 root window and it is initialized
- *	   at startup. Creating a window of type GDK_WINDOW_ROOT
- *	   is an error.
- *   Toplevel: Windows which interact with the window manager.
- *   Child: Windows which are children of some other type of window.
- *	    (Any other type of window). Most windows are child windows.
- *   Dialog: A special kind of toplevel window which interacts with
- *	     the window manager slightly differently than a regular
- *	     toplevel window. Dialog windows should be used for any
- *	     transient window.
- *   Foreign: A window that actually belongs to another application
+/**
+ * GdkWindowType:
+ * @GDK_WINDOW_ROOT: root window; this window has no parent, covers the entire
+ *  screen, and is created by the window system
+ * @GDK_WINDOW_TOPLEVEL: toplevel window (used to implement #GtkWindow)
+ * @GDK_WINDOW_CHILD: child window (used to implement e.g. #GtkEntry)
+ * @GDK_WINDOW_DIALOG: useless/deprecated compatibility type
+ * @GDK_WINDOW_TEMP: override redirect temporary window (used to implement
+ *  #GtkMenu)
+ * @GDK_WINDOW_FOREIGN: foreign window (see gdk_window_foreign_new())
+ * @GDK_WINDOW_OFFSCREEN: offscreen window (see
+ *  <xref linkend="OFFSCREEN-WINDOWS"/>). Since 2.18
+ *
+ * Describes the kind of window.
  */
 typedef enum
 {
@@ -81,13 +85,24 @@ typedef enum
   GDK_WINDOW_OFFSCREEN
 } GdkWindowType;
 
-/* Window attribute mask values.
- *   GDK_WA_TITLE: The "title" field is valid.
- *   GDK_WA_X: The "x" field is valid.
- *   GDK_WA_Y: The "y" field is valid.
- *   GDK_WA_CURSOR: The "cursor" field is valid.
- *   GDK_WA_COLORMAP: The "colormap" field is valid.
- *   GDK_WA_VISUAL: The "visual" field is valid.
+/**
+ * GdkWindowAttributesType:
+ * @GDK_WA_TITLE: Honor the title field
+ * @GDK_WA_X: Honor the X coordinate field
+ * @GDK_WA_Y: Honor the Y coordinate field
+ * @GDK_WA_CURSOR: Honor the cursor field
+ * @GDK_WA_COLORMAP: Honor the colormap field
+ * @GDK_WA_VISUAL: Honor the visual field
+ * @GDK_WA_WMCLASS: Honor the wmclass_class and wmclass_name fields
+ * @GDK_WA_NOREDIR: Honor the override_redirect field
+ * @GDK_WA_TYPE_HINT: Honor the type_hint field
+ *
+ * Used to indicate which fields in the #GdkWindowAttr struct should be honored.
+ * For example, if you filled in the "cursor" and "x" fields of #GdkWindowAttr,
+ * pass "@GDK_WA_X | @GDK_WA_CURSOR" to gdk_window_new(). Fields in
+ * #GdkWindowAttr not covered by a bit in this enum are required; for example,
+ * the @width/@height, @wclass, and @window_type fields are required, they have
+ * no corresponding flag in #GdkWindowAttributesType.
  */
 typedef enum
 {
@@ -104,6 +119,29 @@ typedef enum
 
 /* Size restriction enumeration.
  */
+/**
+ * GdkWindowHints:
+ * @GDK_HINT_POS: indicates that the program has positioned the window
+ * @GDK_HINT_MIN_SIZE: min size fields are set
+ * @GDK_HINT_MAX_SIZE: max size fields are set
+ * @GDK_HINT_BASE_SIZE: base size fields are set
+ * @GDK_HINT_ASPECT: aspect ratio fields are set
+ * @GDK_HINT_RESIZE_INC: resize increment fields are set
+ * @GDK_HINT_WIN_GRAVITY: window gravity field is set
+ * @GDK_HINT_USER_POS: indicates that the window's position was explicitly set
+ *  by the user
+ * @GDK_HINT_USER_SIZE: indicates that the window's size was explicitly set by
+ *  the user
+ *
+ * Used to indicate which fields of a #GdkGeometry struct should be paid
+ * attention to. Also, the presence/absence of @GDK_HINT_POS,
+ * @GDK_HINT_USER_POS, and @GDK_HINT_USER_SIZE is significant, though they don't
+ * directly refer to #GdkGeometry fields. @GDK_HINT_USER_POS will be set
+ * automatically by #GtkWindow if you call gtk_window_move().
+ * @GDK_HINT_USER_POS and @GDK_HINT_USER_SIZE should be set if the user
+ * specified a size/position using a --geometry command-line argument;
+ * gtk_window_parse_geometry() automatically sets these flags.
+ */
 typedef enum
 {
   GDK_HINT_POS	       = 1 << 0,
@@ -118,17 +156,37 @@ typedef enum
 } GdkWindowHints;
 
 
-/* Window type hints.
- * These are hints for the window manager that indicate
- * what type of function the window has. The window manager
- * can use this when determining decoration and behaviour
- * of the window. The hint must be set before mapping the
- * window.
+/**
+ * GdkWindowTypeHint:
+ * @GDK_WINDOW_TYPE_HINT_NORMAL: Normal toplevel window.
+ * @GDK_WINDOW_TYPE_HINT_DIALOG: Dialog window.
+ * @GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu; GTK+ uses
+ *  this hint only for torn-off menus, see #GtkTearoffMenuItem.
+ * @GDK_WINDOW_TYPE_HINT_TOOLBAR: Window used to implement toolbars.
+ * @GDK_WINDOW_TYPE_HINT_SPLASHSCREEN: Window used to display a splash
+ *  screen during application startup.
+ * @GDK_WINDOW_TYPE_HINT_UTILITY: Utility windows which are not detached
+ *  toolbars or dialogs.
+ * @GDK_WINDOW_TYPE_HINT_DOCK: Used for creating dock or panel windows.
+ * @GDK_WINDOW_TYPE_HINT_DESKTOP: Used for creating the desktop background
+ *  window.
+ * @GDK_WINDOW_TYPE_HINT_DROPDOWN_MENU: A menu that belongs to a menubar.
+ * @GDK_WINDOW_TYPE_HINT_POPUP_MENU: A menu that does not belong to a menubar,
+ *  e.g. a context menu.
+ * @GDK_WINDOW_TYPE_HINT_TOOLTIP: A tooltip.
+ * @GDK_WINDOW_TYPE_HINT_NOTIFICATION: A notification - typically a "bubble"
+ *  that belongs to a status icon.
+ * @GDK_WINDOW_TYPE_HINT_COMBO: A popup from a combo box.
+ * @GDK_WINDOW_TYPE_HINT_DND: A window that is used to implement a DND cursor.
+ *
+ * These are hints for the window manager that indicate what type of function
+ * the window has. The window manager can use this when determining decoration
+ * and behaviour of the window. The hint must be set before mapping the window.
  *
- *   Normal: Normal toplevel window
- *   Dialog: Dialog window
- *   Menu: Window used to implement a menu.
- *   Toolbar: Window used to implement toolbars.
+ * See the
+ * <ulink url="http://www.freedesktop.org/Standards/wm-spec">Extended
+ * Window Manager Hints</ulink> specification for more details about
+ * window types.
  */
 typedef enum
 {
@@ -153,6 +211,20 @@ typedef enum
  * of gdk_window_set_decorations/gdk_window_set_functions
  * will need to change as well.
  */
+/**
+ * GdkWMDecoration:
+ * @GDK_DECOR_ALL: all decorations should be applied.
+ * @GDK_DECOR_BORDER: a frame should be drawn around the window.
+ * @GDK_DECOR_RESIZEH: the frame should have resize handles.
+ * @GDK_DECOR_TITLE: a titlebar should be placed above the window.
+ * @GDK_DECOR_MENU: a button for opening a menu should be included.
+ * @GDK_DECOR_MINIMIZE: a minimize button should be included.
+ * @GDK_DECOR_MAXIMIZE: a maximize button should be included.
+ *
+ * These are hints originally defined by the Motif toolkit.
+ * The window manager can use them when determining how to decorate
+ * the window. The hint must be set before mapping the window.
+ */
 typedef enum
 {
   GDK_DECOR_ALL		= 1 << 0,
@@ -164,6 +236,19 @@ typedef enum
   GDK_DECOR_MAXIMIZE	= 1 << 6
 } GdkWMDecoration;
 
+/**
+ * GdkWMFunction:
+ * @GDK_FUNC_ALL: all functions should be offered.
+ * @GDK_FUNC_RESIZE: the window should be resizable.
+ * @GDK_FUNC_MOVE: the window should be movable.
+ * @GDK_FUNC_MINIMIZE: the window should be minimizable.
+ * @GDK_FUNC_MAXIMIZE: the window should be maximizable.
+ * @GDK_FUNC_CLOSE: the window should be closable.
+ *
+ * These are hints originally defined by the Motif toolkit. The window manager
+ * can use them when determining the functions to offer for the window. The
+ * hint must be set before mapping the window.
+ */
 typedef enum
 {
   GDK_FUNC_ALL		= 1 << 0,
@@ -178,6 +263,26 @@ typedef enum
  * X protocol. If you change that, gdkwindow-x11.c/gdk_window_set_geometry_hints()
  * will need fixing.
  */
+/**
+ * GdkGravity:
+ * @GDK_GRAVITY_NORTH_WEST: the reference point is at the top left corner.
+ * @GDK_GRAVITY_NORTH: the reference point is in the middle of the top edge.
+ * @GDK_GRAVITY_NORTH_EAST: the reference point is at the top right corner.
+ * @GDK_GRAVITY_WEST: the reference point is at the middle of the left edge.
+ * @GDK_GRAVITY_CENTER: the reference point is at the center of the window.
+ * @GDK_GRAVITY_EAST: the reference point is at the middle of the right edge.
+ * @GDK_GRAVITY_SOUTH_WEST: the reference point is at the lower left corner.
+ * @GDK_GRAVITY_SOUTH: the reference point is at the middle of the lower edge.
+ * @GDK_GRAVITY_SOUTH_EAST: the reference point is at the lower right corner.
+ * @GDK_GRAVITY_STATIC: the reference point is at the top left corner of the
+ *  window itself, ignoring window manager decorations.
+ *
+ * Defines the reference point of a window and the meaning of coordinates
+ * passed to gtk_window_move(). See gtk_window_move() and the "implementation
+ * notes" section of the
+ * <ulink url="http://www.freedesktop.org/Standards/wm-spec">Extended
+ * Window Manager Hints</ulink> specification for more details.
+ */
 typedef enum
 {
   GDK_GRAVITY_NORTH_WEST = 1,
@@ -193,6 +298,19 @@ typedef enum
 } GdkGravity;
 
 
+/**
+ * GdkWindowEdge:
+ * @GDK_WINDOW_EDGE_NORTH_WEST: the top left corner.
+ * @GDK_WINDOW_EDGE_NORTH: the top edge.
+ * @GDK_WINDOW_EDGE_NORTH_EAST: the top right corner.
+ * @GDK_WINDOW_EDGE_WEST: the left edge.
+ * @GDK_WINDOW_EDGE_EAST: the right edge.
+ * @GDK_WINDOW_EDGE_SOUTH_WEST: the lower left corner.
+ * @GDK_WINDOW_EDGE_SOUTH: the lower edge.
+ * @GDK_WINDOW_EDGE_SOUTH_EAST: the lower right corner.
+ *
+ * Determines a window edge or corner.
+ */
 typedef enum
 {
   GDK_WINDOW_EDGE_NORTH_WEST,
@@ -205,6 +323,27 @@ typedef enum
   GDK_WINDOW_EDGE_SOUTH_EAST  
 } GdkWindowEdge;
 
+/**
+ * GdkWindowAttr:
+ * @title: title of the window (for toplevel windows)
+ * @event_mask: event mask (see gdk_window_set_events())
+ * @x: X coordinate relative to parent window (see gdk_window_move())
+ * @y: Y coordinate relative to parent window (see gdk_window_move())
+ * @width: width of window
+ * @height: height of window
+ * @wclass: #GDK_INPUT_OUTPUT (normal window) or #GDK_INPUT_ONLY (invisible
+ *  window that receives events)
+ * @visual: #GdkVisual for window
+ * @colormap: #GdkColormap for window
+ * @window_type: type of window
+ * @cursor: cursor for the window (see gdk_window_set_cursor())
+ * @wmclass_name: don't use (see gtk_window_set_wmclass())
+ * @wmclass_class: don't use (see gtk_window_set_wmclass())
+ * @override_redirect: %TRUE to bypass the window manager
+ * @type_hint: a hint of the function of the window
+ *
+ * Attributes to use for a newly-created window.
+ */
 struct _GdkWindowAttr
 {
   gchar *title;
@@ -223,6 +362,82 @@ struct _GdkWindowAttr
   GdkWindowTypeHint type_hint;
 };
 
+/**
+ * GdkGeometry:
+ * @min_width: minimum width of window (or -1 to use requisition, with
+ *  #GtkWindow only)
+ * @min_height: minimum height of window (or -1 to use requisition, with
+ *  #GtkWindow only)
+ * @max_width: maximum width of window (or -1 to use requisition, with
+ *  #GtkWindow only)
+ * @max_height: maximum height of window (or -1 to use requisition, with
+ *  #GtkWindow only)
+ * @base_width: allowed window widths are @base_width + @width_inc * N where N
+ *  is any integer (-1 allowed with #GtkWindow)
+ * @base_height: allowed window widths are @base_height + @height_inc * N where
+ *  N is any integer (-1 allowed with #GtkWindow)
+ * @width_inc: width resize increment
+ * @height_inc: height resize increment
+ * @min_aspect: minimum width/height ratio
+ * @max_aspect: maximum width/height ratio
+ * @win_gravity: window gravity, see gtk_window_set_gravity()
+ *
+ * The #GdkGeometry struct gives the window manager information about
+ * a window's geometry constraints. Normally you would set these on
+ * the GTK+ level using gtk_window_set_geometry_hints(). #GtkWindow
+ * then sets the hints on the #GdkWindow it creates.
+ *
+ * gdk_window_set_geometry_hints() expects the hints to be fully valid already
+ * and simply passes them to the window manager; in contrast,
+ * gtk_window_set_geometry_hints() performs some interpretation. For example,
+ * #GtkWindow will apply the hints to the geometry widget instead of the
+ * toplevel window, if you set a geometry widget. Also, the
+ * @min_width/@min_height/@max_width/@max_height fields may be set to -1, and
+ * #GtkWindow will substitute the size request of the window or geometry widget.
+ * If the minimum size hint is not provided, #GtkWindow will use its requisition
+ * as the minimum size. If the minimum size is provided and a geometry widget is
+ * set, #GtkWindow will take the minimum size as the minimum size of the
+ * geometry widget rather than the entire window. The base size is treated
+ * similarly.
+ *
+ * The canonical use-case for gtk_window_set_geometry_hints() is to get a
+ * terminal widget to resize properly. Here, the terminal text area should be
+ * the geometry widget; #GtkWindow will then automatically set the base size to
+ * the size of other widgets in the terminal window, such as the menubar and
+ * scrollbar. Then, the @width_inc and @height_inc fields should be set to the
+ * size of one character in the terminal. Finally, the base size should be set
+ * to the size of one character. The net effect is that the minimum size of the
+ * terminal will have a 1x1 character terminal area, and only terminal sizes on
+ * the "character grid" will be allowed.
+ *
+ * Here's an example of how the terminal example would be implemented, assuming
+ * a terminal area widget called "terminal" and a toplevel window "toplevel":
+ *
+ * <informalexample><programlisting><![CDATA[
+ * 	GdkGeometry hints;
+ *
+ * 	hints.base_width = terminal->char_width;
+ *         hints.base_height = terminal->char_height;
+ *         hints.min_width = terminal->char_width;
+ *         hints.min_height = terminal->char_height;
+ *         hints.width_inc = terminal->char_width;
+ *         hints.height_inc = terminal->char_height;
+ *
+ *  gtk_window_set_geometry_hints (GTK_WINDOW (toplevel),
+ *                                 GTK_WIDGET (terminal),
+ *                                 &hints,
+ *                                 GDK_HINT_RESIZE_INC |
+ *                                 GDK_HINT_MIN_SIZE |
+ *                                 GDK_HINT_BASE_SIZE);
+ * ]]></programlisting></informalexample>
+ *
+ * The other useful fields are the @min_aspect and @max_aspect fields; these
+ * contain a width/height ratio as a floating point number. If a geometry widget
+ * is set, the aspect applies to the geometry widget rather than the entire
+ * window. The most common use of these hints is probably to set @min_aspect and
+ * @max_aspect to the same value, thus forcing the window to keep a constant
+ * aspect ratio.
+ */
 struct _GdkGeometry
 {
   gint min_width;
@@ -238,6 +453,23 @@ struct _GdkGeometry
   GdkGravity win_gravity;
 };
 
+/**
+ * GdkPointerHooks:
+ * @get_pointer: Obtains the current pointer position and modifier state.
+ *  The position is given in coordinates relative to the window containing
+ *  the pointer, which is returned in @window.
+ * @window_at_pointer: Obtains the window underneath the mouse pointer,
+ *  returning the location of that window in @win_x, @win_y. Returns %NULL
+ *  if the window under the mouse pointer is not known to GDK (for example,
+ *  belongs to another application).
+ *
+ * A table of pointers to functions for getting quantities related to
+ * the current pointer position. GDK has one global table of this type,
+ * which can be set using gdk_set_pointer_hooks().
+ *
+ * This is only useful for such low-level tools as an event recorder.
+ * Applications should never have any reason to use this facility
+ */
 struct _GdkPointerHooks 
 {
   GdkWindow* (*get_pointer)       (GdkWindow	   *window,
diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index 631dbed477..8f6730078d 100644
--- a/gdk/x11/gdkdnd-x11.c
+++ b/gdk/x11/gdkdnd-x11.c
@@ -3837,6 +3837,12 @@ gdk_drop_finish (GdkDragContext   *context,
 }
 
 
+/**
+ * gdk_window_register_dnd:
+ * @window: a #GdkWindow.
+ *
+ * Registers a window as a potential drop destination.
+ */
 void            
 gdk_window_register_dnd (GdkWindow      *window)
 {
diff --git a/gdk/x11/gdkwindow-x11.c b/gdk/x11/gdkwindow-x11.c
index 2dc074af7d..92a64fb47b 100644
--- a/gdk/x11/gdkwindow-x11.c
+++ b/gdk/x11/gdkwindow-x11.c
@@ -4456,8 +4456,10 @@ gdk_window_set_decorations (GdkWindow      *window,
  * @window: The toplevel #GdkWindow to get the decorations from
  * @decorations: The window decorations will be written here
  *
- * Returns the decorations set on the GdkWindow with #gdk_window_set_decorations
- * Returns: TRUE if the window has decorations set, FALSE otherwise.
+ * Returns the decorations set on the GdkWindow with
+ * gdk_window_set_decorations().
+ *
+ * Returns: %TRUE if the window has decorations set, %FALSE otherwise.
  **/
 gboolean
 gdk_window_get_decorations(GdkWindow       *window,