From 38d2458f53f2018029d648aa246e8bc90c6afdd6 Mon Sep 17 00:00:00 2001
From: Evan Nemerson <evan@nemerson.com>
Date: Thu, 8 May 2014 12:55:50 -0700
Subject: [PATCH] gdk: add many missing (nullable) return value annotations

https://bugzilla.gnome.org/show_bug.cgi?id=729834
---
 gdk/gdk.c                |  9 +++++----
 gdk/gdkcursor.c          | 10 ++++++----
 gdk/gdkdevice.c          | 17 ++++++++++-------
 gdk/gdkdevicemanager.c   |  6 +++---
 gdk/gdkdisplay.c         | 23 +++++++++++++----------
 gdk/gdkdisplaymanager.c  | 15 ++++++++-------
 gdk/gdkevents.c          | 20 +++++++++++---------
 gdk/gdkframeclock.c      | 10 +++++-----
 gdk/gdkkeys.c            |  6 +++---
 gdk/gdkoffscreenwindow.c |  7 ++++---
 gdk/gdkpixbuf-drawable.c |  8 ++++----
 gdk/gdkscreen.c          | 21 +++++++++++----------
 gdk/gdkselection.c       | 29 ++++++++++++++---------------
 gdk/gdkvisual.c          |  4 ++--
 gdk/gdkwindow.c          | 40 +++++++++++++++++++++-------------------
 15 files changed, 120 insertions(+), 105 deletions(-)

diff --git a/gdk/gdk.c b/gdk/gdk.c
index fd64c83a19..b94798c6a4 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -357,8 +357,9 @@ gdk_get_display (void)
  * Gets the display name specified in the command line arguments passed
  * to gdk_init() or gdk_parse_args(), if any.
  *
- * Returns: the display name, if specified explicitly, otherwise %NULL
- *   this string is owned by GTK+ and must not be modified or freed.
+ * Returns: (nullable): the display name, if specified explicitly,
+ *   otherwise %NULL this string is owned by GTK+ and must not be
+ *   modified or freed.
  *
  * Since: 2.2
  */
@@ -380,8 +381,8 @@ gdk_get_display_arg_name (void)
  * display has previously been set, simply returns that. An internal
  * function that should not be used by applications.
  *
- * Returns: (transfer none): the default display, if it could be
- *   opened, otherwise %NULL.
+ * Returns: (nullable) (transfer none): the default display, if it
+ *   could be opened, otherwise %NULL.
  **/
 GdkDisplay *
 gdk_display_open_default_libgtk_only (void)
diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index af2de2a9d4..42dabddf7a 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -264,8 +264,8 @@ gdk_cursor_new_for_display (GdkDisplay    *display,
  * Creates a new cursor by looking up @name in the current cursor
  * theme.
  *
- * Returns: a new #GdkCursor, or %NULL if there is no cursor with
- *   the given name
+ * Returns: (nullable): a new #GdkCursor, or %NULL if there is no
+ *   cursor with the given name
  *
  * Since: 2.8
  */
@@ -423,7 +423,8 @@ gdk_cursor_get_display (GdkCursor *cursor)
  * on the cursor, GDK may not be able to obtain the image data. In this 
  * case, %NULL is returned.
  *
- * Returns: (transfer full): a #GdkPixbuf representing @cursor, or %NULL
+ * Returns: (nullable) (transfer full): a #GdkPixbuf representing
+ *   @cursor, or %NULL
  *
  * Since: 2.8
  */
@@ -487,7 +488,8 @@ gdk_cursor_get_image (GdkCursor *cursor)
  * on the cursor, GDK may not be able to obtain the image data. In this
  * case, %NULL is returned.
  *
- * Returns: (transfer full): a #cairo_surface_t representing @cursor, or %NULL
+ * Returns: (nullable) (transfer full): a #cairo_surface_t
+ *   representing @cursor, or %NULL
  *
  * Since: 3.10
  */
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 52b66db272..c77f2b8279 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -505,7 +505,8 @@ gdk_device_get_position (GdkDevice        *device,
  * function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
  * unless there is an ongoing grab on them, see gdk_device_grab().
  *
- * Returns: (transfer none): the #GdkWindow under the device position, or %NULL.
+ * Returns: (nullable) (transfer none): the #GdkWindow under the
+ *   device position, or %NULL.
  *
  * Since: 3.0
  **/
@@ -554,7 +555,8 @@ gdk_device_get_window_at_position_double (GdkDevice  *device,
  * function may not be called on devices of type %GDK_DEVICE_TYPE_SLAVE,
  * unless there is an ongoing grab on them, see gdk_device_grab().
  *
- * Returns: (transfer none): the #GdkWindow under the device position, or %NULL.
+ * Returns: (nullable) (transfer none): the #GdkWindow under the
+ * device position, or %NULL.
  *
  * Since: 3.0
  **/
@@ -941,7 +943,8 @@ gdk_device_get_display (GdkDevice *device)
  * If @device is of type %GDK_DEVICE_TYPE_FLOATING, %NULL will be
  * returned, as there is no associated device.
  *
- * Returns: (transfer none): The associated device, or %NULL
+ * Returns: (nullable) (transfer none): The associated device, or
+ *   %NULL
  *
  * Since: 3.0
  **/
@@ -1001,10 +1004,10 @@ _gdk_device_set_associated_device (GdkDevice *device,
  * the list of slave devices attached to it, otherwise it will return
  * %NULL
  *
- * Returns: (transfer container) (element-type GdkDevice): the list of
- *          slave devices, or %NULL. The list must be freed with
- *          g_list_free(), the contents of the list are owned by GTK+
- *          and should not be freed.
+ * Returns: (nullable) (transfer container) (element-type GdkDevice):
+ *          the list of slave devices, or %NULL. The list must be
+ *          freed with g_list_free(), the contents of the list are
+ *          owned by GTK+ and should not be freed.
  **/
 GList *
 gdk_device_list_slave_devices (GdkDevice *device)
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index a056b7a323..47d0292692 100644
--- a/gdk/gdkdevicemanager.c
+++ b/gdk/gdkdevicemanager.c
@@ -284,9 +284,9 @@ gdk_device_manager_get_property (GObject      *object,
  *
  * Gets the #GdkDisplay associated to @device_manager.
  *
- * Returns: (transfer none): the #GdkDisplay to which @device_manager is
- *          associated to, or #NULL. This memory is owned by GDK and
- *          must not be freed or unreferenced.
+ * Returns: (nullable) (transfer none): the #GdkDisplay to which
+ *          @device_manager is associated to, or #NULL. This memory is
+ *          owned by GDK and must not be freed or unreferenced.
  *
  * Since: 3.0
  **/
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 37ac390a2d..34b6cab8ad 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -306,8 +306,9 @@ gdk_display_is_closed  (GdkDisplay  *display)
  * Gets the next #GdkEvent to be processed for @display, fetching events from the
  * windowing system if necessary.
  * 
- * Returns: the next #GdkEvent to be processed, or %NULL if no events
- * are pending. The returned #GdkEvent should be freed with gdk_event_free().
+ * Returns: (nullable): the next #GdkEvent to be processed, or %NULL
+ * if no events are pending. The returned #GdkEvent should be freed
+ * with gdk_event_free().
  *
  * Since: 2.2
  **/
@@ -331,9 +332,9 @@ gdk_display_get_event (GdkDisplay *display)
  * not get more events from the windowing system.  It only checks the events
  * that have already been moved to the GDK event queue.)
  * 
- * Returns: a copy of the first #GdkEvent on the event queue, or %NULL 
- * if no events are in the queue. The returned #GdkEvent should be freed with
- * gdk_event_free().
+ * Returns: (nullable): a copy of the first #GdkEvent on the event
+ * queue, or %NULL if no events are in the queue. The returned
+ * #GdkEvent should be freed with gdk_event_free().
  *
  * Since: 2.2
  **/
@@ -585,7 +586,8 @@ gdk_display_get_pointer (GdkDisplay      *display,
  * if the window under the mouse pointer is not known to GDK (for example, 
  * belongs to another application).
  *
- * Returns: (transfer none): the window under the mouse pointer, or %NULL
+ * Returns: (nullable) (transfer none): the window under the mouse
+ *   pointer, or %NULL
  *
  * Since: 2.2
  *
@@ -1390,8 +1392,9 @@ gdk_display_device_is_grabbed (GdkDisplay *display,
  *
  * Returns the #GdkDeviceManager associated to @display.
  *
- * Returns: (transfer none): A #GdkDeviceManager, or %NULL. This memory is
- *          owned by GDK and must not be freed or unreferenced.
+ * Returns: (nullable) (transfer none): A #GdkDeviceManager, or
+ *          %NULL. This memory is owned by GDK and must not be freed
+ *          or unreferenced.
  *
  * Since: 3.0
  **/
@@ -1780,8 +1783,8 @@ gdk_display_get_app_launch_context (GdkDisplay *display)
  *
  * Opens a display.
  *
- * Returns: (transfer none): a #GdkDisplay, or %NULL
- *     if the display could not be opened
+ * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
+ *     display could not be opened
  *
  * Since: 2.2
  */
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index 6163006a2c..85fb8eefdf 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -313,8 +313,8 @@ gdk_display_manager_get (void)
  *
  * Gets the default #GdkDisplay.
  *
- * Returns: (transfer none): a #GdkDisplay, or %NULL
- *     if there is no default display.
+ * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
+ *     there is no default display.
  *
  * Since: 2.2
  */
@@ -331,8 +331,8 @@ gdk_display_manager_get_default_display (GdkDisplayManager *manager)
  * function for:
  * `gdk_display_manager_get_default_display (gdk_display_manager_get ())`.
  *
- * Returns: (transfer none): a #GdkDisplay, or %NULL if there is no default
- *   display.
+ * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if
+ *   there is no default display.
  *
  * Since: 2.2
  */
@@ -348,7 +348,8 @@ gdk_display_get_default (void)
  * Gets the default screen for the default display. (See
  * gdk_display_get_default ()).
  *
- * Returns: (transfer none): a #GdkScreen, or %NULL if there is no default display.
+ * Returns: (nullable) (transfer none): a #GdkScreen, or %NULL if
+ *     there is no default display.
  *
  * Since: 2.2
  */
@@ -411,8 +412,8 @@ gdk_display_manager_list_displays (GdkDisplayManager *manager)
  *
  * Opens a display.
  *
- * Returns: (transfer none): a #GdkDisplay, or %NULL
- *     if the display could not be opened
+ * Returns: (nullable) (transfer none): a #GdkDisplay, or %NULL if the
+ *     display could not be opened
  *
  * Since: 3.0
  */
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 7562e713a4..54ac136838 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -80,7 +80,8 @@ _gdk_event_emit (GdkEvent *event)
  * Find the first event on the queue that is not still
  * being filled in.
  * 
- * Returns: Pointer to the list node for that event, or NULL.
+ * Returns: (nullable): Pointer to the list node for that event, or
+ *   %NULL.
  **/
 GList*
 _gdk_event_queue_find_first (GdkDisplay *display)
@@ -241,7 +242,7 @@ _gdk_event_queue_remove_link (GdkDisplay *display,
  * Removes and returns the first event from the event
  * queue that is not still being filled in.
  * 
- * Returns: the event, or %NULL. Ownership is transferred
+ * Returns: (nullable): the event, or %NULL. Ownership is transferred
  * to the caller.
  **/
 GdkEvent*
@@ -406,8 +407,9 @@ gdk_events_pending (void)
  * on, fetching events from the windowing system if necessary.
  * See gdk_display_get_event().
  * 
- * Returns: the next #GdkEvent to be processed, or %NULL if no events
- * are pending. The returned #GdkEvent should be freed with gdk_event_free().
+ * Returns: (nullable): the next #GdkEvent to be processed, or %NULL
+ * if no events are pending. The returned #GdkEvent should be freed
+ * with gdk_event_free().
  **/
 GdkEvent*
 gdk_event_get (void)
@@ -435,9 +437,9 @@ gdk_event_get (void)
  * If there is an event waiting in the event queue of some open
  * display, returns a copy of it. See gdk_display_peek_event().
  * 
- * Returns: a copy of the first #GdkEvent on some event queue, or %NULL if no
- * events are in any queues. The returned #GdkEvent should be freed with
- * gdk_event_free().
+ * Returns: (nullable): a copy of the first #GdkEvent on some event
+ * queue, or %NULL if no events are in any queues. The returned
+ * #GdkEvent should be freed with gdk_event_free().
  **/
 GdkEvent*
 gdk_event_peek (void)
@@ -1509,7 +1511,7 @@ gdk_event_set_device (GdkEvent  *event,
  * If the event contains a “device” field, this function will return
  * it, else it will return %NULL.
  *
- * Returns: (transfer none): a #GdkDevice, or %NULL.
+ * Returns: (nullable) (transfer none): a #GdkDevice, or %NULL.
  *
  * Since: 3.0
  **/
@@ -1641,7 +1643,7 @@ gdk_event_set_source_device (GdkEvent  *event,
  * If the event does not contain a device field, this function will
  * return %NULL.
  *
- * Returns: (transfer none): a #GdkDevice, or %NULL.
+ * Returns: (nullable) (transfer none): a #GdkDevice, or %NULL.
  *
  * Since: 3.0
  **/
diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c
index 3a7bb24145..3cf49ca65f 100644
--- a/gdk/gdkframeclock.c
+++ b/gdk/gdkframeclock.c
@@ -436,7 +436,7 @@ _gdk_frame_clock_begin_frame (GdkFrameClock *frame_clock)
  * for the current frame or a recent frame. The #GdkFrameTimings
  * object may not yet be complete: see gdk_frame_timings_get_complete().
  *
- * Returns: the #GdkFrameTimings object for the specified
+ * Returns: (nullable): the #GdkFrameTimings object for the specified
  *  frame, or %NULL if it is not available. See
  *  gdk_frame_clock_get_history_start().
  * Since: 3.8
@@ -469,10 +469,10 @@ gdk_frame_clock_get_timings (GdkFrameClock *frame_clock,
  *
  * Gets the frame timings for the current frame.
  *
- * Returns: the #GdkFrameTimings for the frame currently being
- *  processed, or even no frame is being processed, for the
- *  previous frame. Before any frames have been procesed,
- *  returns %NULL.
+ * Returns: (nullable): the #GdkFrameTimings for the frame currently
+ *  being processed, or even no frame is being processed, for the
+ *  previous frame. Before any frames have been procesed, returns
+ *  %NULL.
  * Since: 3.8
  */
 GdkFrameTimings *
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index 85c900d202..63303dce84 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -680,9 +680,9 @@ gdk_keymap_get_modifier_mask (GdkKeymap         *keymap,
  * `gdk/gdkkeysyms.h` header file
  * but without the leading “GDK_KEY_”.
  *
- * Returns: (transfer none): a string containing the name of the key,
- *     or %NULL if @keyval is not a valid key. The string should not be
- *     modified.
+ * Returns: (nullable) (transfer none): a string containing the name
+ *     of the key, or %NULL if @keyval is not a valid key. The string
+ *     should not be modified.
  */
 gchar *
 gdk_keyval_name (guint keyval)
diff --git a/gdk/gdkoffscreenwindow.c b/gdk/gdkoffscreenwindow.c
index 9276103ca0..3c4eb70e1c 100644
--- a/gdk/gdkoffscreenwindow.c
+++ b/gdk/gdkoffscreenwindow.c
@@ -321,7 +321,8 @@ gdk_offscreen_window_get_device_state (GdkWindow       *window,
  * If you need to keep this around over window resizes, you need to
  * add a reference to it.
  *
- * Returns: (transfer none): The offscreen surface, or %NULL if not offscreen
+ * Returns: (nullable) (transfer none): The offscreen surface, or
+ *   %NULL if not offscreen
  */
 cairo_surface_t *
 gdk_offscreen_window_get_surface (GdkWindow *window)
@@ -608,8 +609,8 @@ gdk_offscreen_window_set_embedder (GdkWindow     *window,
  *
  * Gets the window that @window is embedded in.
  *
- * Returns: (transfer none): the embedding #GdkWindow, or %NULL
- *     if @window is not an mbedded offscreen window
+ * Returns: (nullable) (transfer none): the embedding #GdkWindow, or
+ *     %NULL if @window is not an mbedded offscreen window
  *
  * Since: 2.18
  */
diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index 7ad1d27d01..37952f72f8 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -77,8 +77,8 @@
  * (In short, there are several ways this function can fail, and if it fails
  *  it returns %NULL; so check the return value.)
  *
- * Returns: (transfer full): A newly-created pixbuf with a reference
- *     count of 1, or %NULL on error
+ * Returns: (nullable) (transfer full): A newly-created pixbuf with a
+ *     reference count of 1, or %NULL on error
  */
 GdkPixbuf *
 gdk_pixbuf_get_from_window (GdkWindow *src,
@@ -225,8 +225,8 @@ convert_no_alpha (guchar *dest_data,
  * This function will create an RGB pixbuf with 8 bits per channel.
  * The pixbuf will contain an alpha channel if the @surface contains one.
  *
- * Returns: (transfer full): A newly-created pixbuf with a reference
- *     count of 1, or %NULL on error
+ * Returns: (nullable) (transfer full): A newly-created pixbuf with a
+ *     reference count of 1, or %NULL on error
  */
 GdkPixbuf *
 gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c
index 1ae58fa8a5..599784bb10 100644
--- a/gdk/gdkscreen.c
+++ b/gdk/gdkscreen.c
@@ -427,8 +427,8 @@ gdk_screen_set_font_options (GdkScreen                  *screen,
  * 
  * Gets any options previously set with gdk_screen_set_font_options().
  * 
- * Returns: the current font options, or %NULL if no default
- *  font options have been set.
+ * Returns: (nullable): the current font options, or %NULL if no
+ *  default font options have been set.
  *
  * Since: 2.10
  **/
@@ -760,8 +760,8 @@ gdk_screen_get_monitor_height_mm (GdkScreen *screen,
  * Usually something like VGA, DVI, or TV, not the actual
  * product name of the display device.
  *
- * Returns: a newly-allocated string containing the name of the monitor,
- *   or %NULL if the name cannot be determined
+ * Returns: (nullable): a newly-allocated string containing the name
+ *   of the monitor, or %NULL if the name cannot be determined
  *
  * Since: 2.14
  */
@@ -899,8 +899,9 @@ gdk_screen_get_system_visual (GdkScreen * screen)
  * For setting an overall opacity for a top-level window, see
  * gdk_window_set_opacity().
  *
- * Returns: (transfer none): a visual to use for windows with an
- *     alpha channel or %NULL if the capability is not available.
+ * Returns: (nullable) (transfer none): a visual to use for windows
+ *     with an alpha channel or %NULL if the capability is not
+ *     available.
  *
  * Since: 2.8
  **/
@@ -974,7 +975,8 @@ gdk_screen_make_display_name (GdkScreen *screen)
  * The returned window should be unrefed using g_object_unref() when
  * no longer needed.
  *
- * Returns: (transfer full): the currently active window, or %NULL.
+ * Returns: (nullable) (transfer full): the currently active window,
+ *   or %NULL.
  *
  * Since: 2.10
  **/
@@ -1006,9 +1008,8 @@ 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: (transfer full) (element-type GdkWindow):
- *     a list of #GdkWindows for the current window stack,
- *               or %NULL.
+ * 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 eab6193e20..6540e61570 100644
--- a/gdk/gdkselection.c
+++ b/gdk/gdkselection.c
@@ -95,14 +95,12 @@ gdk_selection_owner_set (GdkWindow *owner,
  *
  * Determines the owner of the given selection.
  *
- * Returns: (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. Note that the return value may be owned
- *   by a different 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
+ *   for this window, and it is a window known to the current process,
+ *   the #GdkWindow that owns the selection, otherwise %NULL. Note
+ *   that the return value may be owned by a different process if a
+ *   foreign window was previously created for that window, but a new
+ *   foreign window will never be created by this call.
  */
 GdkWindow*
 gdk_selection_owner_get (GdkAtom selection)
@@ -179,9 +177,10 @@ 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: (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.
+ * 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.
  *
  * Since: 2.2
  */
@@ -318,10 +317,10 @@ gdk_text_property_to_utf8_list_for_display (GdkDisplay     *display,
  * is not specified; it may be as pseudo-escape sequences
  * \x{ABCD}, or it may be in some other form of approximation.
  *
- * Returns: the newly-allocated string, or %NULL if the
- *               conversion failed. (It should not fail for
- *               any properly formed UTF-8 string unless system
- *               limits like memory or file descriptors are exceeded.)
+ * Returns: (nullable): the newly-allocated string, or %NULL if the
+ *          conversion failed. (It should not fail for any properly
+ *          formed UTF-8 string unless system limits like memory or
+ *          file descriptors are exceeded.)
  **/
 gchar *
 gdk_utf8_to_string_target (const gchar *str)
diff --git a/gdk/gdkvisual.c b/gdk/gdkvisual.c
index 9c27bc0e68..09ea93c34b 100644
--- a/gdk/gdkvisual.c
+++ b/gdk/gdkvisual.c
@@ -203,8 +203,8 @@ gdk_visual_get_best_with_type (GdkVisualType visual_type)
  * Combines gdk_visual_get_best_with_depth() and
  * gdk_visual_get_best_with_type().
  *
- * Returns: (transfer none): best visual with both @depth and
- *     @visual_type, or %NULL if none
+ * Returns: (nullable) (transfer none): best visual with both @depth
+ *     and @visual_type, or %NULL if none
  */
 GdkVisual*
 gdk_visual_get_best_with_both (gint          depth,
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 9eeb7333bd..e48e5d0353 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -329,8 +329,8 @@ gdk_window_class_init (GdkWindowClass *klass)
    * The ::pick-embedded-child signal is emitted to find an embedded
    * child at the given position.
    *
-   * Returns: (transfer none): the #GdkWindow of the embedded child at
-   *     @x, @y, or %NULL
+   * Returns: (nullable) (transfer none): the #GdkWindow of the
+   *     embedded child at @x, @y, or %NULL
    *
    * Since: 2.18
    */
@@ -4412,9 +4412,9 @@ gdk_window_constrain_size (GdkGeometry    *geometry,
  * The position is given in coordinates relative to the upper left
  * corner of @window.
  *
- * Returns: (transfer none): the window containing the pointer (as with
- * gdk_window_at_pointer()), or %NULL if the window containing the
- * pointer isn’t known to GDK
+ * Returns: (nullable) (transfer none): the window containing the
+ * pointer (as with gdk_window_at_pointer()), or %NULL if the window
+ * containing the pointer isn’t known to GDK
  *
  * Deprecated: 3.0: Use gdk_window_get_device_position() instead.
  **/
@@ -4445,8 +4445,9 @@ gdk_window_get_pointer (GdkWindow	  *window,
  * The position is given in coordinates relative to the upper left
  * corner of @window.
  *
- * Returns: (transfer none): The window underneath @device (as with
- * gdk_device_get_window_at_position()), or %NULL if the window is not known to GDK.
+ * Returns: (nullable) (transfer none): The window underneath @device
+ * (as with gdk_device_get_window_at_position()), or %NULL if the
+ * window is not known to GDK.
  *
  * Since: 3.10
  **/
@@ -4501,8 +4502,9 @@ gdk_window_get_device_position_double (GdkWindow       *window,
  *
  * Use gdk_window_get_device_position_double() if you need subpixel precision.
  *
- * Returns: (transfer none): The window underneath @device (as with
- * gdk_device_get_window_at_position()), or %NULL if the window is not known to GDK.
+ * Returns: (nullable) (transfer none): The window underneath @device
+ * (as with gdk_device_get_window_at_position()), or %NULL if the
+ * window is not known to GDK.
  *
  * Since: 3.0
  **/
@@ -5814,8 +5816,8 @@ gdk_window_set_background_pattern (GdkWindow *window,
  * does not have its own background and reuses the parent's, %NULL is
  * returned and you’ll have to query it yourself.
  *
- * Returns: (transfer none): The pattern to use for the background or
- *     %NULL to use the parent’s background.
+ * Returns: (nullable) (transfer none): The pattern to use for the
+ * background or %NULL to use the parent’s background.
  *
  * Since: 2.22
  **/
@@ -5860,10 +5862,10 @@ gdk_window_set_cursor_internal (GdkWindow *window,
  * there is no custom cursor set on the specified window, and it is
  * using the cursor for its parent window.
  *
- * Returns: (transfer none): a #GdkCursor, or %NULL. The returned
- *   object is owned by the #GdkWindow and should not be unreferenced
- *   directly. Use gdk_window_set_cursor() to unset the cursor of the
- *   window
+ * Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The
+ *   returned object is owned by the #GdkWindow and should not be
+ *   unreferenced directly. Use gdk_window_set_cursor() to unset the
+ *   cursor of the window
  *
  * Since: 2.18
  */
@@ -5940,10 +5942,10 @@ gdk_window_set_cursor (GdkWindow *window,
  * there is no custom cursor set on the specified window, and it is
  * using the cursor for its parent window.
  *
- * Returns: (transfer none): a #GdkCursor, or %NULL. The returned
- *   object is owned by the #GdkWindow and should not be unreferenced
- *   directly. Use gdk_window_set_cursor() to unset the cursor of the
- *   window
+ * Returns: (nullable) (transfer none): a #GdkCursor, or %NULL. The
+ *   returned object is owned by the #GdkWindow and should not be
+ *   unreferenced directly. Use gdk_window_set_cursor() to unset the
+ *   cursor of the window
  *
  * Since: 3.0
  **/