gdk: assorted introspection and documentation fixes

https://bugzilla.gnome.org/show_bug.cgi?id=729983
2014-05-16 20:12:51 -07:00 · 2014-05-16 20:12:51 -07:00 · 701adf81b6
commit 701adf81b6
parent ca79019586
9 changed files with 32 additions and 26 deletions
--- a/gdk/gdkcursor.c
+++ b/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
- * @y_hot: Location to store the hotspot y position, or %NULL
+ * @x_hot: (optional) (out): Location to store the hotspot x position,
+ *   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.
 *
--- a/gdk/gdkdevice.c
+++ b/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,
- * or %NULL.
- * @mask: location to store the modifiers, or %NULL.
+ * @axes: (nullable) (array): an array of doubles to store the values of
+ * the axes of @device in, 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
- * @n_events: location to store the length of @events, or %NULL
+ * @events: (array length=n_events) (out) (transfer full) (optional):
+ *   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
--- a/gdk/gdkdisplaymanager.c
+++ b/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
--- a/gdk/gdkdnd.c
+++ b/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
 *
--- a/gdk/gdkevents.c
+++ b/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
--- a/gdk/gdkevents.h
+++ b/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.
--- a/gdk/gdkscreen.c
+++ b/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
--- a/gdk/gdkselection.c
+++ b/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.
--- a/gdk/gdkwindow.c
+++ b/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