From 701adf81b6bbc621f65f784f4f5decd2723e3a16 Mon Sep 17 00:00:00 2001 From: Evan Nemerson Date: Fri, 16 May 2014 20:12:51 -0700 Subject: [PATCH] gdk: assorted introspection and documentation fixes https://bugzilla.gnome.org/show_bug.cgi?id=729983 --- gdk/gdkcursor.c | 6 ++++-- gdk/gdkdevice.c | 17 ++++++++++------- gdk/gdkdisplaymanager.c | 6 +++--- gdk/gdkdnd.c | 2 +- gdk/gdkevents.c | 2 +- gdk/gdkevents.h | 2 +- gdk/gdkscreen.c | 2 +- gdk/gdkselection.c | 6 +++--- gdk/gdkwindow.c | 15 ++++++++------- 9 files changed, 32 insertions(+), 26 deletions(-) diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c index 42dabddf7a..c1e959086a 100644 --- 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. * diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c index c77f2b8279..2e9807d316 100644 --- 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 diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c index 85fb8eefdf..c6813d02bc 100644 --- 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 diff --git a/gdk/gdkdnd.c b/gdk/gdkdnd.c index d57c8f7285..6482b0b0e1 100644 --- 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 * diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c index fb785cfe46..2615835b28 100644 --- 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 diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h index e9189834f3..2af1419b8d 100644 --- 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. diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c index 599784bb10..a1ae7e722a 100644 --- 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 diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c index 6540e61570..302a76a2bd 100644 --- 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. diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index e48e5d0353..e50601ab32 100644 --- 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