Merge in Gdk-custom.c introspection annotations

The Gdk-custom.c file in gir-repository contained a number of
introspection annotations.  Merge those into the GDK source files.

Some documentation was moved from the tmpl/ files to accomodate
the addition of annotations.

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

7 files changed, 42 insertions, 25 deletions

diff --git a/gdk/x11/gdkcursor-x11.c b/gdk/x11/gdkcursor-x11.c
index 19d79cf9ca..5cfbaa52b0 100644
--- a/gdk/x11/gdkcursor-x11.c
+++ b/gdk/x11/gdkcursor-x11.c
@@ -1035,8 +1035,8 @@ gdk_display_get_default_cursor_size (GdkDisplay    *display)
 /**
  * gdk_display_get_maximal_cursor_size:
  * @display: a #GdkDisplay
- * @width: the return location for the maximal cursor width
- * @height: the return location for the maximal cursor height
+ * @width: (out): the return location for the maximal cursor width
+ * @height: (out): the return location for the maximal cursor height
  *
  * Gets the maximal size to use for cursors on @display.
  *
diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index c7c803a0ba..938e7e14da 100644
--- a/gdk/x11/gdkdnd-x11.c
+++ b/gdk/x11/gdkdnd-x11.c
@@ -3170,11 +3170,11 @@ drag_context_find_window_cache (GdkDragContext  *context,
  * @screen: the screen where the destination window is sought. 
  * @x_root: the x position of the pointer in root coordinates.
  * @y_root: the y position of the pointer in root coordinates.
- * @dest_window: location to store the destination window in.
- * @protocol: location to store the DND protocol in.
- * 
+ * @dest_window: (out): location to store the destination window in.
+ * @protocol: (out): location to store the DND protocol in.
+ *
  * Finds the destination window and DND protocol to use at the
- * given pointer position. 
+ * given pointer position.
  *
  * This function is called by the drag source to obtain the 
  * @dest_window and @protocol parameters for gdk_drag_motion().
diff --git a/gdk/x11/gdkinput-x11.c b/gdk/x11/gdkinput-x11.c
index a793a4245f..767b0702c4 100644
--- a/gdk/x11/gdkinput-x11.c
+++ b/gdk/x11/gdkinput-x11.c
@@ -858,6 +858,16 @@ _gdk_device_get_history (GdkDevice         *device,
     return FALSE;
 }
 
+/**
+ * gdk_device_get_state:
+ * @device: a #GdkDevice.
+ * @window: a #GdkWindow.
+ * @axes: an array of doubles to store the values of the axes of @device in,
+ * or %NULL.
+ * @mask: location to store the modifiers, or %NULL.
+ *
+ * Gets the current state of a device.
+ */
 void
 gdk_device_get_state (GdkDevice       *device,
 		      GdkWindow       *window,
diff --git a/gdk/x11/gdkinput.c b/gdk/x11/gdkinput.c
index 95485d78a6..72eb5ab0e8 100644
--- a/gdk/x11/gdkinput.c
+++ b/gdk/x11/gdkinput.c
@@ -243,7 +243,7 @@ impl_coord_in_window (GdkWindow *window,
  * @window: the window with respect to which which the event coordinates will be reported
  * @start: starting timestamp for range of events to return
  * @stop: ending timestamp for the range of events to return
- * @events: location to store a newly-allocated array of #GdkTimeCoord, or %NULL
+ * @events: (array length=n_events) (out) (transfer none): location to store a newly-allocated array of #GdkTimeCoord, or %NULL
  * @n_events: location to store the length of @events, or %NULL
  *
  * Obtains the motion history for a device; given a starting and
@@ -351,6 +351,13 @@ _gdk_device_allocate_history (GdkDevice *device,
   return result;
 }
 
+/**
+ * gdk_device_free_history:
+ * @events: (inout) (transfer none): an array of #GdkTimeCoord.
+ * @n_events: the length of the array.
+ *
+ * Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
+ */
 void
 gdk_device_free_history (GdkTimeCoord **events,
 			 gint           n_events)
diff --git a/gdk/x11/gdkkeys-x11.c b/gdk/x11/gdkkeys-x11.c
index 01d2a182e5..8cb5b3bcf5 100644
--- a/gdk/x11/gdkkeys-x11.c
+++ b/gdk/x11/gdkkeys-x11.c
@@ -834,11 +834,11 @@ gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
 
 /**
  * gdk_keymap_get_entries_for_keyval:
- * @keymap: a #GdkKeymap, or %NULL to use the default keymap
+ * @keymap: (allow-none): a #GdkKeymap, or %NULL to use the default keymap
  * @keyval: a keyval, such as %GDK_a, %GDK_Up, %GDK_Return, etc.
- * @keys: return location for an array of #GdkKeymapKey
- * @n_keys: return location for number of elements in returned array
- * 
+ * @keys: (out): return location for an array of #GdkKeymapKey
+ * @n_keys: (out): return location for number of elements in returned array
+ *
  * Obtains a list of keycode/group/level combinations that will
  * generate @keyval. Groups and levels are two kinds of keyboard mode;
  * in general, the level determines whether the top or bottom symbol
@@ -984,10 +984,10 @@ gdk_keymap_get_entries_for_keyval (GdkKeymap     *keymap,
 
 /**
  * gdk_keymap_get_entries_for_keycode:
- * @keymap: a #GdkKeymap or %NULL to use the default keymap
+ * @keymap: (allow-none): a #GdkKeymap or %NULL to use the default keymap
  * @hardware_keycode: a keycode
- * @keys: return location for array of #GdkKeymapKey, or %NULL
- * @keyvals: return location for array of keyvals, or %NULL
+ * @keys: (out): return location for array of #GdkKeymapKey, or %NULL
+ * @keyvals: (out): return location for array of keyvals, or %NULL
  * @n_entries: length of @keys and @keyvals
  *
  * Returns the keyvals bound to @hardware_keycode.
@@ -1409,14 +1409,14 @@ translate_keysym (GdkKeymapX11   *keymap_x11,
 
 /**
  * gdk_keymap_translate_keyboard_state:
- * @keymap: a #GdkKeymap, or %NULL to use the default
+ * @keymap: (allow-none): a #GdkKeymap, or %NULL to use the default
  * @hardware_keycode: a keycode
- * @state: a modifier state 
+ * @state: a modifier state
  * @group: active keyboard group
- * @keyval: return location for keyval, or %NULL
- * @effective_group: return location for effective group, or %NULL
- * @level: return location for level, or %NULL
- * @consumed_modifiers: return location for modifiers that were used to
+ * @keyval: (out) (allow-none): return location for keyval, or %NULL
+ * @effective_group: (out) (allow-none): return location for effective group, or %NULL
+ * @level: (out) (allow-none):  return location for level, or %NULL
+ * @consumed_modifiers: (out) (allow-none):  return location for modifiers that were used to
  *     determine the group or level, or %NULL
  *
  * Translates the contents of a #GdkEventKey into a keyval, effective
diff --git a/gdk/x11/gdkscreen-x11.c b/gdk/x11/gdkscreen-x11.c
index 3e7b8b9067..5b0cb17846 100644
--- a/gdk/x11/gdkscreen-x11.c
+++ b/gdk/x11/gdkscreen-x11.c
@@ -214,9 +214,9 @@ gdk_screen_get_number (GdkScreen *screen)
  * gdk_screen_get_root_window:
  * @screen: a #GdkScreen
  *
- * Gets the root window of @screen. 
- * 
- * Returns: the root window
+ * Gets the root window of @screen.
+ *
+ * Returns: (transfer none): the root window
  *
  * Since: 2.2
  **/
diff --git a/gdk/x11/gdkvisual-x11.c b/gdk/x11/gdkvisual-x11.c
index 6d827c9ed2..1e781655b6 100644
--- a/gdk/x11/gdkvisual-x11.c
+++ b/gdk/x11/gdkvisual-x11.c
@@ -466,8 +466,8 @@ gdk_visual_get_best_with_both (gint          depth,
 
 /**
  * gdk_query_depths:
- * @depths: return location for available depths 
- * @count: return location for number of available depths
+ * @depths: (out) (array): return location for available depths
+ * @count: (out): return location for number of available depths
  *
  * This function returns the available bit depths for the default
  * screen. It's equivalent to listing the visuals