gdk: assorted introspection and documentation fixes

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

gdk/gdkcursor.c

@@ -479,8 +479,10 @@ gdk_cursor_get_image (GdkCursor *cursor)
 /**
  * gdk_cursor_get_surface:
  * @cursor: a #GdkCursor
- * @x_hot: Location to store the hotspot x position, or %NULL
+ * @x_hot: (optional) (out): Location to store the hotspot x position,
- * @y_hot: Location to store the hotspot y position, or %NULL
+ *   or %NULL
+ * @y_hot: (optional) (out): Location to store the hotspot y position,
+ *   or %NULL
  *
  * Returns a cairo image surface with the image used to display the cursor.
  *

gdk/gdkdevice.c

@@ -383,9 +383,9 @@ gdk_device_get_property (GObject    *object,
  * gdk_device_get_state: (skip)
  * @device: a #GdkDevice.
  * @window: a #GdkWindow.
- * @axes: an array of doubles to store the values of the axes of @device in,
+ * @axes: (nullable) (array): an array of doubles to store the values of
- * or %NULL.
+ * the axes of @device in, or %NULL.
- * @mask: location to store the modifiers, or %NULL.
+ * @mask: (optional) (out): location to store the modifiers, or %NULL.
  *
  * Gets the current state of a pointer device relative to @window. As a slave
  * device’s coordinates are those of its master pointer, this
@@ -585,8 +585,11 @@ gdk_device_get_window_at_position (GdkDevice  *device,
  * @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: (array length=n_events) (out) (transfer full): location to store a newly-allocated array of #GdkTimeCoord, or %NULL
+ * @events: (array length=n_events) (out) (transfer full) (optional):
- * @n_events: location to store the length of @events, or %NULL
+ *   location to store a newly-allocated array of #GdkTimeCoord, or
+ *   %NULL
+ * @n_events: (out) (optional): location to store the length of
+ *   @events, or %NULL
  *
  * Obtains the motion history for a pointer device; given a starting and
  * ending timestamp, return all events in the motion history for
@@ -646,7 +649,7 @@ _gdk_device_allocate_history (GdkDevice *device,
 
 /**
  * gdk_device_free_history: (skip)
- * @events: an array of #GdkTimeCoord.
+ * @events: (array length=n_events): an array of #GdkTimeCoord.
  * @n_events: the length of the array.
  *
  * Frees an array of #GdkTimeCoord that was returned by gdk_device_get_history().
@@ -1120,7 +1123,7 @@ gdk_device_list_axes (GdkDevice *device)
  * @device: a pointer #GdkDevice.
  * @axes: (array): pointer to an array of axes
  * @axis_label: #GdkAtom with the axis label.
- * @value: location to store the found value.
+ * @value: (out): location to store the found value.
  *
  * Interprets an array of double as axis values for a given device,
  * and locates the value in the array for a given axis label, as returned

gdk/gdkdisplaymanager.c

@@ -69,13 +69,13 @@
  * notification when displays appear or disappear or the default display
  * changes.
  *
- * You can use gdk_display_manager_get() to obtain the GdkDisplayManager
+ * You can use gdk_display_manager_get() to obtain the #GdkDisplayManager
  * singleton, but that should be rarely necessary. Typically, initializing
  * GTK+ opens a display that you can work with without ever accessing the
- * GdkDisplayManager.
+ * #GdkDisplayManager.
  *
  * The GDK library can be built with support for multiple backends.
- * The GdkDisplayManager object determines which backend is used
+ * The #GdkDisplayManager object determines which backend is used
  * at runtime.
  *
  * When writing backend-specific code that is supposed to work with

gdk/gdkdnd.c

@@ -68,7 +68,7 @@ gdk_drag_context_list_targets (GdkDragContext *context)
  * @context: a #GdkDragContext
  *
  * Determines the bitmask of actions proposed by the source if
- * gdk_drag_context_get_suggested_action() returns GDK_ACTION_ASK.
+ * gdk_drag_context_get_suggested_action() returns %GDK_ACTION_ASK.
  *
  * Returns: the #GdkDragAction flags
  *

gdk/gdkevents.c

@@ -910,7 +910,7 @@ gdk_event_get_time (const GdkEvent *event)
 
 /**
  * gdk_event_get_state:
- * @event: a #GdkEvent or NULL
+ * @event: (allow-none): a #GdkEvent or %NULL
  * @state: (out): return location for state
  * 
  * If the event contains a “state” field, puts that field in @state. Otherwise

gdk/gdkevents.h

@@ -189,7 +189,7 @@ typedef enum {
  * 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.
+ * @data: (closure): 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.

gdk/gdkscreen.c

@@ -1008,7 +1008,7 @@ gdk_screen_get_active_window (GdkScreen *screen)
  * windows it contains, so it should be freed using g_list_free() and
  * its windows unrefed using g_object_unref() when no longer needed.
  *
- * Returns: (nullable): (transfer full) (element-type GdkWindow): a
+ * Returns: (nullable) (transfer full) (element-type GdkWindow): a
  *     list of #GdkWindows for the current window stack, or %NULL.
  *
  * Since: 2.10

gdk/gdkselection.c

@@ -62,7 +62,7 @@
 
 /**
  * gdk_selection_owner_set:
- * @owner: a #GdkWindow or %NULL to indicate that the
+ * @owner: (allow-none): a #GdkWindow or %NULL to indicate that the
  *   the owner for the given should be unset.
  * @selection: an atom identifying a selection.
  * @time_: timestamp to use when setting the selection.
@@ -136,7 +136,7 @@ gdk_selection_send_notify (GdkWindow      *requestor,
 /**
  * gdk_selection_owner_set_for_display:
  * @display: the #GdkDisplay
- * @owner: a #GdkWindow or %NULL to indicate that the owner for
+ * @owner: (nullable): a #GdkWindow or %NULL to indicate that the owner for
  *         the given should be unset
  * @selection: an atom identifying a selection
  * @time_: timestamp to use when setting the selection
@@ -177,7 +177,7 @@ gdk_selection_owner_set_for_display (GdkDisplay *display,
  * process if a foreign window was previously created for that
  * window, but a new foreign window will never be created by this call.
  *
- * Returns: (nullable): (transfer none): if there is a selection owner
+ * Returns: (nullable) (transfer none): if there is a selection owner
  *    for this window, and it is a window known to the current
  *    process, the #GdkWindow that owns the selection, otherwise
  *    %NULL.

gdk/gdkwindow.c

@@ -1853,14 +1853,14 @@ window_remove_from_pointer_info (GdkWindow  *window,
 /**
  * _gdk_window_destroy_hierarchy:
  * @window: a #GdkWindow
- * @recursing: If TRUE, then this is being called because a parent
+ * @recursing: If %TRUE, then this is being called because a parent
  *            was destroyed.
- * @recursing_native: If TRUE, then this is being called because a native parent
+ * @recursing_native: If %TRUE, then this is being called because a native parent
  *            was destroyed. This generally means that the call to the
  *            windowing system to destroy the window can be omitted, since
  *            it will be destroyed as a result of the parent being destroyed.
  *            Unless @foreign_destroy.
- * @foreign_destroy: If TRUE, the window or a parent was destroyed by some
+ * @foreign_destroy: If %TRUE, the window or a parent was destroyed by some
  *            external agency. The window has already been destroyed and no
  *            windowing system calls should be made. (This may never happen
  *            for some windowing systems.)
@@ -2024,7 +2024,7 @@ _gdk_window_destroy_hierarchy (GdkWindow *window,
 /**
  * _gdk_window_destroy:
  * @window: a #GdkWindow
- * @foreign_destroy: If TRUE, the window or a parent was destroyed by some
+ * @foreign_destroy: If %TRUE, the window or a parent was destroyed by some
  *            external agency. The window has already been destroyed and no
  *            windowing system calls should be made. (This may never happen
  *            for some windowing systems.)
@@ -3779,7 +3779,7 @@ gdk_window_invalidate_rect (GdkWindow          *window,
 }
 
 /**
- * gdk_window_set_invalidate_handler:
+ * gdk_window_set_invalidate_handler: (skip)
  * @window: a #GdkWindow
  * @handler: a #GdkWindowInvalidateHandlerFunc callback function
  *
@@ -3961,7 +3961,7 @@ gdk_window_invalidate_maybe_recurse_full (GdkWindow            *window,
  *
  * The @child_func parameter controls whether the region of
  * each child window that intersects @region will also be invalidated.
- * Only children for which @child_func returns TRUE will have the area
+ * Only children for which @child_func returns #TRUE will have the area
  * invalidated.
  **/
 void
@@ -9300,7 +9300,8 @@ gdk_window_create_similar_surface (GdkWindow *     window,
 
 /**
  * gdk_window_create_similar_image_surface:
- * @window: window to make new surface similar to, or %NULL if none
+ * @window: (nullable): window to make new surface similar to, or
+ *   %NULL if none
  * @format: (type int): the format for the new surface
  * @width: width of the new surface
  * @height: height of the new surface