[annotations] Add allow-none

This commit was created using a script that searched for all docstrings
containing a parameter and the string 'or %NULL'.
Gdk backends and demos excluded as they are not part of a public API

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

101 files changed, 370 insertions, 370 deletions

diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c
index 82297252f2..7140766ef2 100644
--- a/gdk-pixbuf/gdk-pixbuf-io.c
+++ b/gdk-pixbuf/gdk-pixbuf-io.c
@@ -1861,7 +1861,7 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf         *pixbuf,
  * @pixbuf: a #GdkPixbuf.
  * @filename: name of file to save.
  * @type: name of file format.
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  * @Varargs: list of key-value save options
  *
  * Saves pixbuf to a file in format @type. By default, "jpeg", "png", "ico" 
@@ -2009,7 +2009,7 @@ gdk_pixbuf_save (GdkPixbuf  *pixbuf,
  * @type: name of file format.
  * @option_keys: name of options to set, %NULL-terminated
  * @option_values: values for named options
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  *
  * Saves pixbuf to a file in @type, which is currently "jpeg", "png", "tiff", "ico" or "bmp".
  * If @error is set, %FALSE will be returned. 
@@ -2116,7 +2116,7 @@ gdk_pixbuf_savev (GdkPixbuf  *pixbuf,
  *   the save routine generates.
  * @user_data: user data to pass to the save function.
  * @type: name of file format.
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  * @Varargs: list of key-value save options
  *
  * Saves pixbuf in format @type by feeding the produced data to a 
@@ -2172,7 +2172,7 @@ gdk_pixbuf_save_to_callback    (GdkPixbuf  *pixbuf,
  * @type: name of file format.
  * @option_keys: name of options to set, %NULL-terminated
  * @option_values: values for named options
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  *
  * Saves pixbuf to a callback in format @type, which is currently "jpeg",
  * "png", "tiff", "ico" or "bmp".  If @error is set, %FALSE will be returned. See
@@ -2217,7 +2217,7 @@ gdk_pixbuf_save_to_callbackv   (GdkPixbuf  *pixbuf,
  * @buffer: location to receive a pointer to the new buffer.
  * @buffer_size: location to receive the size of the new buffer.
  * @type: name of file format.
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  * @Varargs: list of key-value save options
  *
  * Saves pixbuf to a new buffer in format @type, which is currently "jpeg",
@@ -2306,7 +2306,7 @@ save_to_buffer_callback (const gchar *data,
  * @type: name of file format.
  * @option_keys: name of options to set, %NULL-terminated
  * @option_values: values for named options
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  *
  * Saves pixbuf to a new buffer in format @type, which is currently "jpeg",
  * "tiff", "png", "ico" or "bmp".  See gdk_pixbuf_save_to_buffer() 
@@ -2402,7 +2402,7 @@ save_to_stream (const gchar  *buffer,
  * @stream: a #GOutputStream to save the pixbuf to
  * @type: name of file format
  * @cancellable: optional #GCancellable object, %NULL to ignore
- * @error: return location for error, or %NULL
+ * @error: (allow-none): return location for error, or %NULL
  * @Varargs: list of key-value save options
  *
  * Saves @pixbuf to an output stream.
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c
index f51d4478d4..9ef23c1ad0 100644
--- a/gdk-pixbuf/gdk-pixbuf-loader.c
+++ b/gdk-pixbuf/gdk-pixbuf-loader.c
@@ -500,7 +500,7 @@ gdk_pixbuf_loader_new (void)
 /**
  * gdk_pixbuf_loader_new_with_type:
  * @image_type: name of the image format to be loaded with the image
- * @error: return location for an allocated #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors
  *
  * Creates a new pixbuf loader object that always attempts to parse
  * image data as if it were an image of type @image_type, instead of
@@ -543,7 +543,7 @@ gdk_pixbuf_loader_new_with_type (const char *image_type,
 /**
  * gdk_pixbuf_loader_new_with_mime_type:
  * @mime_type: the mime type to be loaded 
- * @error: return location for an allocated #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors
  *
  * Creates a new pixbuf loader object that always attempts to parse
  * image data as if it were an image of mime type @mime_type, instead of
@@ -669,7 +669,7 @@ gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader)
 /**
  * gdk_pixbuf_loader_close:
  * @loader: A pixbuf loader.
- * @error: return location for a #GError, or %NULL to ignore errors
+ * @error: (allow-none): return location for a #GError, or %NULL to ignore errors
  *
  * Informs a pixbuf loader that no further writes with
  * gdk_pixbuf_loader_write() will occur, so that it can free its
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 0a5fd93c68..110d662dc7 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -534,7 +534,7 @@ gdk_threads_dispatch_free (gpointer data)
  *            range btweeen #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
  * @function: function to call
  * @data:     data to pass to @function
- * @notify:   function to call when the idle is removed, or %NULL
+ * @notify: (allow-none):   function to call when the idle is removed, or %NULL
  *
  * Adds a function to be called whenever there are no higher priority
  * events pending.  If the function returns %FALSE it is automatically
@@ -634,7 +634,7 @@ gdk_threads_add_idle (GSourceFunc    function,
  *             (1/1000ths of a second)
  * @function: function to call
  * @data:     data to pass to @function
- * @notify:   function to call when the timeout is removed, or %NULL
+ * @notify: (allow-none):   function to call when the timeout is removed, or %NULL
  *
  * Sets a function to be called at regular intervals holding the GDK lock,
  * with the given priority.  The function is called repeatedly until it 
@@ -740,7 +740,7 @@ gdk_threads_add_timeout (guint       interval,
  * @interval: the time between calls to the function, in seconds
  * @function: function to call
  * @data:     data to pass to @function
- * @notify:   function to call when the timeout is removed, or %NULL
+ * @notify: (allow-none):   function to call when the timeout is removed, or %NULL
  *
  * A variant of gdk_threads_add_timout_full() with second-granularity.
  * See g_timeout_add_seconds_full() for a discussion of why it is
diff --git a/gdk/gdkapplaunchcontext.c b/gdk/gdkapplaunchcontext.c
index 7c19770c79..1653e97527 100644
--- a/gdk/gdkapplaunchcontext.c
+++ b/gdk/gdkapplaunchcontext.c
@@ -218,7 +218,7 @@ gdk_app_launch_context_set_timestamp (GdkAppLaunchContext *context,
 /**
  * gdk_app_launch_context_set_icon:
  * @context: a #GdkAppLaunchContext
- * @icon: a #GIcon, or %NULL
+ * @icon: (allow-none): a #GIcon, or %NULL
  *
  * Sets the icon for applications that are launched with this
  * context.
@@ -250,7 +250,7 @@ gdk_app_launch_context_set_icon (GdkAppLaunchContext *context,
 /**
  * gdk_app_launch_context_set_icon_name:
  * @context: a #GdkAppLaunchContext
- * @icon_name: an icon name, or %NULL
+ * @icon_name: (allow-none): an icon name, or %NULL
  *
  * Sets the icon for applications that are launched with this context. 
  * The @icon_name will be interpreted in the same way as the Icon field 
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 34c8035418..ac49a5bf49 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -468,9 +468,9 @@ _gdk_display_enable_motion_hints (GdkDisplay *display)
  * @display: a #GdkDisplay
  * @screen: (allow-none): location to store the screen that the
  *          cursor is on, or %NULL.
- * @x: (out): location to store root window X coordinate of pointer, or %NULL.
- * @y: (out): location to store root window Y coordinate of pointer, or %NULL.
- * @mask: (out): location to store current modifier mask, or %NULL
+ * @x: (allow-none): (out): location to store root window X coordinate of pointer, or %NULL.
+ * @y: (allow-none): (out): location to store root window Y coordinate of pointer, or %NULL.
+ * @mask: (allow-none): (out): location to store current modifier mask, or %NULL
  *
  * Gets the current location of the pointer and the current modifier
  * mask for a given display.
diff --git a/gdk/gdkdraw.c b/gdk/gdkdraw.c
index ef42b8e5f8..0e6ccc573e 100644
--- a/gdk/gdkdraw.c
+++ b/gdk/gdkdraw.c
@@ -99,7 +99,7 @@ gdk_drawable_init (GdkDrawable *drawable)
  * @drawable: a #GdkDrawable
  * @key: name to store the data under
  * @data: arbitrary data
- * @destroy_func: function to free @data, or %NULL
+ * @destroy_func: (allow-none): function to free @data, or %NULL
  *
  * This function is equivalent to g_object_set_data(),
  * the #GObject variant should be used instead.
@@ -142,8 +142,8 @@ gdk_drawable_get_data (GdkDrawable   *drawable,
 /**
  * gdk_drawable_get_size:
  * @drawable: a #GdkDrawable
- * @width: (out): location to store drawable's width, or %NULL
- * @height: (out): location to store drawable's height, or %NULL
+ * @width: (allow-none): (out): location to store drawable's width, or %NULL
+ * @height: (allow-none): (out): location to store drawable's height, or %NULL
  *
  * Fills *@width and *@height with the size of @drawable.
  * @width or @height can be %NULL if you only want the other one.
@@ -733,7 +733,7 @@ gdk_draw_image (GdkDrawable *drawable,
 /**
  * gdk_draw_pixbuf:
  * @drawable: Destination drawable.
- * @gc: a #GdkGC, used for clipping, or %NULL
+ * @gc: (allow-none): a #GdkGC, used for clipping, or %NULL
  * @pixbuf: a #GdkPixbuf
  * @src_x: Source X coordinate within pixbuf.
  * @src_y: Source Y coordinates within pixbuf.
@@ -955,7 +955,7 @@ gdk_draw_glyphs (GdkDrawable      *drawable,
  * gdk_draw_glyphs_transformed:
  * @drawable: a #GdkDrawable
  * @gc: a #GdkGC
- * @matrix: a #PangoMatrix, or %NULL to use an identity transformation
+ * @matrix: (allow-none): a #PangoMatrix, or %NULL to use an identity transformation
  * @font: the font in which to draw the string
  * @x:       the x position of the start of the string (in Pango
  *           units in user space coordinates)
@@ -1038,7 +1038,7 @@ gdk_draw_trapezoids (GdkDrawable        *drawable,
 /**
  * gdk_drawable_copy_to_image:
  * @drawable: a #GdkDrawable
- * @image: a #GdkDrawable, or %NULL if a new @image should be created.
+ * @image: (allow-none): a #GdkDrawable, or %NULL if a new @image should be created.
  * @src_x: x coordinate on @drawable
  * @src_y: y coordinate on @drawable
  * @dest_x: x coordinate within @image. Must be 0 if @image is %NULL
diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index 24efca8b29..825b238b79 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -623,7 +623,7 @@ gdk_pango_renderer_get_default (GdkScreen *screen)
 /**
  * gdk_pango_renderer_set_drawable:
  * @gdk_renderer: a #GdkPangoRenderer
- * @drawable: the new target drawable, or %NULL
+ * @drawable: (allow-none): the new target drawable, or %NULL
  * 
  * Sets the drawable the renderer draws to.
  *
@@ -653,7 +653,7 @@ gdk_pango_renderer_set_drawable (GdkPangoRenderer *gdk_renderer,
 /**
  * gdk_pango_renderer_set_gc:
  * @gdk_renderer: a #GdkPangoRenderer
- * @gc: the new GC to use for drawing, or %NULL
+ * @gc: (allow-none): the new GC to use for drawing, or %NULL
  * 
  * Sets the GC the renderer draws with. Note that the GC must not be
  * modified until it is unset by calling the function again with
@@ -730,7 +730,7 @@ gdk_pango_renderer_set_stipple (GdkPangoRenderer *gdk_renderer,
  * gdk_pango_renderer_set_override_color:
  * @gdk_renderer: a #GdkPangoRenderer
  * @part: the part to render to set the color of
- * @color: the color to use, or %NULL to unset a previously
+ * @color: (allow-none): the color to use, or %NULL to unset a previously
  *         set override color.
  * 
  * Sets the color for a particular render part (foreground,
@@ -851,8 +851,8 @@ release_renderer (PangoRenderer *renderer)
  * @x:         the x position of start of string (in pixels)
  * @y:         the y position of baseline (in pixels)
  * @line:      a #PangoLayoutLine
- * @foreground: foreground override color, or %NULL for none
- * @background: background override color, or %NULL for none
+ * @foreground: (allow-none): foreground override color, or %NULL for none
+ * @background: (allow-none): background override color, or %NULL for none
  *
  * Render a #PangoLayoutLine onto a #GdkDrawable, overriding the
  * layout's normal colors with @foreground and/or @background.
@@ -928,8 +928,8 @@ gdk_draw_layout_line_with_colors (GdkDrawable      *drawable,
  * @x:         the X position of the left of the layout (in pixels)
  * @y:         the Y position of the top of the layout (in pixels)
  * @layout:    a #PangoLayout
- * @foreground: foreground override color, or %NULL for none
- * @background: background override color, or %NULL for none
+ * @foreground: (allow-none): foreground override color, or %NULL for none
+ * @background: (allow-none): background override color, or %NULL for none
  *
  * Render a #PangoLayout onto a #GdkDrawable, overriding the
  * layout's normal colors with @foreground and/or @background.
diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index 98c399be04..036ff521d3 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -1135,7 +1135,7 @@ rgbconvert (GdkImage    *image,
 
 /**
  * gdk_pixbuf_get_from_drawable:
- * @dest: Destination pixbuf, or %NULL if a new pixbuf should be created.
+ * @dest: (allow-none): Destination pixbuf, or %NULL if a new pixbuf should be created.
  * @src: Source drawable.
  * @cmap: A colormap if @src doesn't have one set.
  * @src_x: Source X coordinate within drawable.
@@ -1312,9 +1312,9 @@ gdk_pixbuf_get_from_drawable (GdkPixbuf   *dest,
         
 /**
  * gdk_pixbuf_get_from_image:
- * @dest: Destination pixbuf, or %NULL if a new pixbuf should be created.
+ * @dest: (allow-none): Destination pixbuf, or %NULL if a new pixbuf should be created.
  * @src: Source #GdkImage.
- * @cmap: A colormap, or %NULL to use the one for @src
+ * @cmap: (allow-none): A colormap, or %NULL to use the one for @src
  * @src_x: Source X coordinate within drawable.
  * @src_y: Source Y coordinate within drawable.
  * @dest_x: Destination X coordinate in pixbuf, or 0 if @dest is NULL.
diff --git a/gdk/gdkrectangle.c b/gdk/gdkrectangle.c
index 1f06f7daf6..9ad5509ef0 100644
--- a/gdk/gdkrectangle.c
+++ b/gdk/gdkrectangle.c
@@ -62,7 +62,7 @@ gdk_rectangle_union (const GdkRectangle *src1,
  * gdk_rectangle_intersect:
  * @src1: a #GdkRectangle
  * @src2: a #GdkRectangle
- * @dest: return location for the intersection of @src1 and @src2, or %NULL
+ * @dest: (allow-none): return location for the intersection of @src1 and @src2, or %NULL
  *
  * Calculates the intersection of two rectangles. It is allowed for
  * @dest to be the same as either @src1 or @src2. If the rectangles 
diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c
index cd1dc6c815..4a6e11b657 100644
--- a/gdk/gdkscreen.c
+++ b/gdk/gdkscreen.c
@@ -397,7 +397,7 @@ gdk_screen_height_mm (void)
 /**
  * gdk_screen_set_font_options:
  * @screen: a #GdkScreen
- * @options: a #cairo_font_options_t, or %NULL to unset any
+ * @options: (allow-none): a #cairo_font_options_t, or %NULL to unset any
  *   previously set default font options.
  *
  * Sets the default font options for the screen. These
diff --git a/gdk/gdkselection.c b/gdk/gdkselection.c
index 2a9b84c6a4..fd8f705811 100644
--- a/gdk/gdkselection.c
+++ b/gdk/gdkselection.c
@@ -77,7 +77,7 @@ gdk_text_property_to_text_list (GdkAtom       encoding,
  * @format:   the format of the property
  * @text:     the text to convert
  * @length:   the length of @text, in bytes
- * @list:     location to store the list of strings or %NULL. The
+ * @list: (allow-none):     location to store the list of strings or %NULL. The
  *            list should be freed with g_strfreev().
  * 
  * Convert a text property in the giving encoding to
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 046dae9275..5c9219d583 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -5573,7 +5573,7 @@ gdk_window_invalidate_rect_full (GdkWindow          *window,
 /**
  * gdk_window_invalidate_rect:
  * @window: a #GdkWindow
- * @rect: rectangle to invalidate or %NULL to invalidate the whole
+ * @rect: (allow-none): rectangle to invalidate or %NULL to invalidate the whole
  *      window
  * @invalidate_children: whether to also invalidate child windows
  *
@@ -6777,7 +6777,7 @@ gdk_window_lower (GdkWindow *window)
 /**
  * gdk_window_restack:
  * @window: a #GdkWindow
- * @sibling: a #GdkWindow that is a sibling of @window, or %NULL
+ * @sibling: (allow-none): a #GdkWindow that is a sibling of @window, or %NULL
  * @above: a boolean
  *
  * Changes the position of  @window in the Z-order (stacking order), so that
@@ -7761,7 +7761,7 @@ gdk_window_set_background (GdkWindow      *window,
 /**
  * gdk_window_set_back_pixmap:
  * @window: a #GdkWindow
- * @pixmap: a #GdkPixmap, or %NULL
+ * @pixmap: (allow-none): a #GdkPixmap, or %NULL
  * @parent_relative: whether the tiling origin is at the origin of
  *   @window's parent
  *
@@ -8331,7 +8331,7 @@ gdk_window_merge_child_shapes (GdkWindow *window)
 /**
  * gdk_window_input_shape_combine_mask:
  * @window: a #GdkWindow
- * @mask: shape mask, or %NULL
+ * @mask: (allow-none): shape mask, or %NULL
  * @x: X position of shape mask with respect to @window
  * @y: Y position of shape mask with respect to @window
  *
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 346b89403d..cdba7287ba 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -2416,7 +2416,7 @@ close_cb (GtkAboutDialog *about)
 
 /**
  * gtk_show_about_dialog:
- * @parent: transient parent, or %NULL for none
+ * @parent: (allow-none): transient parent, or %NULL for none
  * @first_property_name: the name of the first property
  * @Varargs: value of first property, followed by more properties, %NULL-terminated
  *
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 4d760b5880..d5d9b53a96 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -691,7 +691,7 @@ gtk_accel_group_connect_by_path (GtkAccelGroup	*accel_group,
 /**
  * gtk_accel_group_disconnect:
  * @accel_group: the accelerator group to remove an accelerator from
- * @closure:     the closure to remove from this accelerator group, or %NULL
+ * @closure: (allow-none):     the closure to remove from this accelerator group, or %NULL
  *               to remove all closures
  * @returns:     %TRUE if the closure was found and got disconnected
  *
@@ -804,8 +804,8 @@ _gtk_accel_group_reconnect (GtkAccelGroup *accel_group,
  * @accel_group:      the accelerator group to query
  * @accel_key:        key value of the accelerator
  * @accel_mods:       modifier combination of the accelerator
- * @n_entries:        location to return the number of entries found, or %NULL
- * @returns:          an array of @n_entries #GtkAccelGroupEntry elements, or %NULL. The array is owned by GTK+ and must not be freed. 
+ * @n_entries: (allow-none):        location to return the number of entries found, or %NULL
+ * @returns: (allow-none):          an array of @n_entries #GtkAccelGroupEntry elements, or %NULL. The array is owned by GTK+ and must not be freed. 
  *
  * Queries an accelerator group for all entries matching @accel_key and 
  * @accel_mods.
@@ -832,7 +832,7 @@ gtk_accel_group_query (GtkAccelGroup  *accel_group,
 /**
  * gtk_accel_group_from_accel_closure:
  * @closure: a #GClosure
- * @returns: the #GtkAccelGroup to which @closure is connected, or %NULL.
+ * @returns: (allow-none): the #GtkAccelGroup to which @closure is connected, or %NULL.
  *
  * Finds the #GtkAccelGroup to which @closure is connected; 
  * see gtk_accel_group_connect().
diff --git a/gtk/gtkaction.c b/gtk/gtkaction.c
index 40cf10f15a..6c552cc4ae 100644
--- a/gtk/gtkaction.c
+++ b/gtk/gtkaction.c
@@ -463,8 +463,8 @@ gtk_action_buildable_get_name (GtkBuildable *buildable)
 /**
  * gtk_action_new:
  * @name: A unique name for the action
- * @label: the label displayed in menu items and on buttons, or %NULL
- * @tooltip: a tooltip for the action, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @tooltip: (allow-none): a tooltip for the action, or %NULL
  * @stock_id: the stock icon to display in widgets representing the
  *   action, or %NULL
  *
@@ -698,7 +698,7 @@ disconnect_proxy (GtkAction *action,
 
 /**
  * _gtk_action_sync_menu_visible:
- * @action: a #GtkAction, or %NULL to determine the action from @proxy
+ * @action: (allow-none): a #GtkAction, or %NULL to determine the action from @proxy
  * @proxy: a proxy menu item
  * @empty: whether the submenu attached to @proxy is empty
  * 
diff --git a/gtk/gtkactivatable.c b/gtk/gtkactivatable.c
index 4aa1b366f1..85abdecfe1 100644
--- a/gtk/gtkactivatable.c
+++ b/gtk/gtkactivatable.c
@@ -356,7 +356,7 @@ gtk_activatable_update (GtkActivatable *activatable,
 /**
  * gtk_activatable_sync_action_properties:
  * @activatable: a #GtkActivatable
- * @action: the related #GtkAction or %NULL
+ * @action: (allow-none): the related #GtkAction or %NULL
  *
  * This is called to update the activatable completely, this is called
  * internally when the #GtkActivatable::related-action property is set
diff --git a/gtk/gtkalignment.c b/gtk/gtkalignment.c
index bf3523b179..49c5271dc3 100644
--- a/gtk/gtkalignment.c
+++ b/gtk/gtkalignment.c
@@ -557,10 +557,10 @@ gtk_alignment_set_padding (GtkAlignment    *alignment,
 /**
  * gtk_alignment_get_padding:
  * @alignment: a #GtkAlignment
- * @padding_top: location to store the padding for the top of the widget, or %NULL
- * @padding_bottom: location to store the padding for the bottom of the widget, or %NULL
- * @padding_left: location to store the padding for the left of the widget, or %NULL
- * @padding_right: location to store the padding for the right of the widget, or %NULL
+ * @padding_top: (allow-none): location to store the padding for the top of the widget, or %NULL
+ * @padding_bottom: (allow-none): location to store the padding for the bottom of the widget, or %NULL
+ * @padding_left: (allow-none): location to store the padding for the left of the widget, or %NULL
+ * @padding_right: (allow-none): location to store the padding for the right of the widget, or %NULL
  *
  * Gets the padding on the different sides of the widget.
  * See gtk_alignment_set_padding ().
diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index 5ee37c112e..e7be4212ea 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -1736,7 +1736,7 @@ gtk_assistant_insert_page (GtkAssistant *assistant,
 /**
  * gtk_assistant_set_forward_page_func:
  * @assistant: a #GtkAssistant
- * @page_func: the #GtkAssistantPageFunc, or %NULL to use the default one
+ * @page_func: (allow-none): the #GtkAssistantPageFunc, or %NULL to use the default one
  * @data: user data for @page_func
  * @destroy: destroy notifier for @data
  *
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index 46137f07a2..d3a8d8e442 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -103,7 +103,7 @@ gtk_buildable_get_name (GtkBuildable *buildable)
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder
  * @child: child to add
- * @type: kind of child or %NULL
+ * @type: (allow-none): kind of child or %NULL
  *
  * Adds a child to @buildable. @type is an optional string
  * describing how the child should be added.
@@ -221,7 +221,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
  * gtk_buildable_custom_tag_start:
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder used to construct this object
- * @child: child object or %NULL for non-child tags
+ * @child: (allow-none): child object or %NULL for non-child tags
  * @tagname: name of tag
  * @parser: a #GMarkupParser structure to fill in
  * @data: return location for user data that will be passed in 
@@ -259,7 +259,7 @@ gtk_buildable_custom_tag_start (GtkBuildable  *buildable,
  * gtk_buildable_custom_tag_end:
  * @buildable: A #GtkBuildable
  * @builder: #GtkBuilder used to construct this object
- * @child: child object or %NULL for non-child tags
+ * @child: (allow-none): child object or %NULL for non-child tags
  * @tagname: name of tag
  * @data: user data that will be passed in to parser functions
  *
@@ -290,7 +290,7 @@ gtk_buildable_custom_tag_end (GtkBuildable  *buildable,
  * gtk_buildable_custom_finished:
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder
- * @child: child object or %NULL for non-child tags
+ * @child: (allow-none): child object or %NULL for non-child tags
  * @tagname: the name of the tag
  * @data: user data created in custom_tag_start
  *
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index a692b751e4..fab4bebaad 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -638,7 +638,7 @@ gtk_builder_new (void)
  * gtk_builder_add_from_file:
  * @builder: a #GtkBuilder
  * @filename: the name of the file to parse
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder 
  * UI definition</link> and merges it with the current contents of @builder. 
@@ -692,7 +692,7 @@ gtk_builder_add_from_file (GtkBuilder   *builder,
  * @builder: a #GtkBuilder
  * @filename: the name of the file to parse
  * @object_ids: nul-terminated array of objects to build
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder 
  * UI definition</link> building only the requested objects and merges
@@ -755,7 +755,7 @@ gtk_builder_add_objects_from_file (GtkBuilder   *builder,
  * @builder: a #GtkBuilder
  * @buffer: the string to parse
  * @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder 
  * UI definition</link> and merges it with the current contents of @builder. 
@@ -800,7 +800,7 @@ gtk_builder_add_from_string (GtkBuilder   *builder,
  * @buffer: the string to parse
  * @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
  * @object_ids: nul-terminated array of objects to build
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder 
  * UI definition</link> building only the requested objects and merges
@@ -909,7 +909,7 @@ gtk_builder_get_objects (GtkBuilder *builder)
 /**
  * gtk_builder_set_translation_domain:
  * @builder: a #GtkBuilder
- * @domain: the translation domain or %NULL
+ * @domain: (allow-none): the translation domain or %NULL
  *
  * Sets the translation domain of @builder. 
  * See #GtkBuilder:translation-domain.
@@ -1110,7 +1110,7 @@ gtk_builder_connect_signals_full (GtkBuilder            *builder,
  * @pspec: the #GParamSpec for the property
  * @string: the string representation of the value
  * @value: the #GValue to store the result in
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * This function demarshals a value from a string. This function
  * calls g_value_init() on the @value argument, so it need not be
@@ -1163,7 +1163,7 @@ gtk_builder_value_from_string (GtkBuilder   *builder,
  * @type: the #GType of the value
  * @string: the string representation of the value
  * @value: the #GValue to store the result in
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Like gtk_builder_value_from_string(), this function demarshals 
  * a value from a string, but takes a #GType instead of #GParamSpec.
diff --git a/gtk/gtkcalendar.c b/gtk/gtkcalendar.c
index 13488e50a2..7203f15269 100644
--- a/gtk/gtkcalendar.c
+++ b/gtk/gtkcalendar.c
@@ -3823,9 +3823,9 @@ gtk_calendar_unmark_day (GtkCalendar *calendar,
 /**
  * gtk_calendar_get_date:
  * @calendar: a #GtkCalendar
- * @year: location to store the year number, or %NULL
- * @month: location to store the month number (between 0 and 11), or %NULL
- * @day: location to store the day number (between 1 and 31), or %NULL
+ * @year: (allow-none): location to store the year number, or %NULL
+ * @month: (allow-none): location to store the month number (between 0 and 11), or %NULL
+ * @day: (allow-none): location to store the day number (between 1 and 31), or %NULL
  * 
  * Obtains the selected date from a #GtkCalendar.
  **/
diff --git a/gtk/gtkcelleditable.c b/gtk/gtkcelleditable.c
index 08e31e52f5..a0a818b610 100644
--- a/gtk/gtkcelleditable.c
+++ b/gtk/gtkcelleditable.c
@@ -130,7 +130,7 @@ gtk_cell_editable_base_init (GtkCellEditableIface *iface)
 /**
  * gtk_cell_editable_start_editing:
  * @cell_editable: A #GtkCellEditable
- * @event: A #GdkEvent, or %NULL
+ * @event: (allow-none): A #GdkEvent, or %NULL
  * 
  * Begins editing on a @cell_editable. @event is the #GdkEvent that began 
  * the editing process. It may be %NULL, in the instance that editing was 
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index 0d3091e35e..b55b0985ae 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -479,11 +479,11 @@ set_cell_bg_color (GtkCellRenderer *cell,
  * gtk_cell_renderer_get_size:
  * @cell: a #GtkCellRenderer
  * @widget: the widget the renderer is rendering to
- * @cell_area: The area a cell will be allocated, or %NULL
- * @x_offset: location to return x offset of cell relative to @cell_area, or %NULL
- * @y_offset: location to return y offset of cell relative to @cell_area, or %NULL
- * @width: location to return width needed to render a cell, or %NULL
- * @height: location to return height needed to render a cell, or %NULL
+ * @cell_area: (allow-none): The area a cell will be allocated, or %NULL
+ * @x_offset: (allow-none): location to return x offset of cell relative to @cell_area, or %NULL
+ * @y_offset: (allow-none): location to return y offset of cell relative to @cell_area, or %NULL
+ * @width: (allow-none): location to return width needed to render a cell, or %NULL
+ * @height: (allow-none): location to return height needed to render a cell, or %NULL
  *
  * Obtains the width and height needed to render the cell. Used by view 
  * widgets to determine the appropriate size for the cell_area passed to
@@ -718,8 +718,8 @@ gtk_cell_renderer_set_fixed_size (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_fixed_size:
  * @cell: A #GtkCellRenderer
- * @width: location to fill in with the fixed width of the cell, or %NULL
- * @height: location to fill in with the fixed height of the cell, or %NULL
+ * @width: (allow-none): location to fill in with the fixed width of the cell, or %NULL
+ * @height: (allow-none): location to fill in with the fixed height of the cell, or %NULL
  *
  * Fills in @width and @height with the appropriate size of @cell.
  **/
@@ -778,8 +778,8 @@ gtk_cell_renderer_set_alignment (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_alignment:
  * @cell: A #GtkCellRenderer
- * @xalign: location to fill in with the x alignment of the cell, or %NULL
- * @yalign: location to fill in with the y alignment of the cell, or %NULL
+ * @xalign: (allow-none): location to fill in with the x alignment of the cell, or %NULL
+ * @yalign: (allow-none): location to fill in with the y alignment of the cell, or %NULL
  *
  * Fills in @xalign and @yalign with the appropriate values of @cell.
  *
@@ -839,8 +839,8 @@ gtk_cell_renderer_set_padding (GtkCellRenderer *cell,
 /**
  * gtk_cell_renderer_get_padding:
  * @cell: A #GtkCellRenderer
- * @xpad: location to fill in with the x padding of the cell, or %NULL
- * @ypad: location to fill in with the y padding of the cell, or %NULL
+ * @xpad: (allow-none): location to fill in with the x padding of the cell, or %NULL
+ * @ypad: (allow-none): location to fill in with the y padding of the cell, or %NULL
  *
  * Fills in @xpad and @ypad with the appropriate values of @cell.
  *
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index f4459f46ab..529a4a57e2 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -5001,7 +5001,7 @@ gtk_combo_box_get_active_iter (GtkComboBox     *combo_box,
 /**
  * gtk_combo_box_set_active_iter:
  * @combo_box: A #GtkComboBox
- * @iter: The #GtkTreeIter, or %NULL
+ * @iter: (allow-none): The #GtkTreeIter, or %NULL
  * 
  * Sets the current active item to be the one referenced by @iter, or
  * unsets the active item if @iter is %NULL.
@@ -5791,8 +5791,8 @@ gtk_combo_box_get_row_separator_func (GtkComboBox *combo_box)
  * gtk_combo_box_set_row_separator_func:
  * @combo_box: a #GtkComboBox
  * @func: a #GtkTreeViewRowSeparatorFunc
- * @data: user data to pass to @func, or %NULL
- * @destroy: destroy notifier for @data, or %NULL
+ * @data: (allow-none): user data to pass to @func, or %NULL
+ * @destroy: (allow-none): destroy notifier for @data, or %NULL
  * 
  * Sets the row separator function, which is used to determine
  * whether a row should be drawn as a separator. If the row separator
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 9a9d1bf87b..f5a169ccdc 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -980,7 +980,7 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
  * gtk_container_class_find_child_property:
  * @cclass: a #GtkContainerClass
  * @property_name: the name of the child property to find
- * @returns: the #GParamSpec of the child property or %NULL if @class has no
+ * @returns: (allow-none): the #GParamSpec of the child property or %NULL if @class has no
  *   child property with that name.
  *
  * Finds a child property of a container class by name.
@@ -2227,7 +2227,7 @@ gtk_container_focus_sort_left_right (GtkContainer     *container,
  * @children:  a list of descendents of @container (they don't
  *             have to be direct children)
  * @direction: focus direction
- * @old_focus: widget to use for the starting position, or %NULL
+ * @old_focus: (allow-none): widget to use for the starting position, or %NULL
  *             to determine this automatically.
  *             (Note, this argument isn't used for GTK_DIR_TAB_*,
  *              which is the only @direction we use currently,
diff --git a/gtk/gtkcustompaperunixdialog.c b/gtk/gtkcustompaperunixdialog.c
index c2ba27fa56..8d95a11f87 100644
--- a/gtk/gtkcustompaperunixdialog.c
+++ b/gtk/gtkcustompaperunixdialog.c
@@ -354,8 +354,8 @@ gtk_custom_paper_unix_dialog_finalize (GObject *object)
 
 /**
  * gtk_custom_paper_unix_dialog_new:
- * @title: the title of the dialog, or %NULL
- * @parent: transient parent of the dialog, or %NULL
+ * @title: (allow-none): the title of the dialog, or %NULL
+ * @parent: (allow-none): transient parent of the dialog, or %NULL
  *
  * Creates a new custom paper dialog.
  *
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 1ebc2848d8..878dbf54dc 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -1384,7 +1384,7 @@ gtk_drag_dest_get_target_list (GtkWidget *widget)
 /**
  * gtk_drag_dest_set_target_list:
  * @widget: a #GtkWidget that's a drag destination
- * @target_list: list of droppable targets, or %NULL for none
+ * @target_list: (allow-none): list of droppable targets, or %NULL for none
  * 
  * Sets the target types that this widget can accept from drag-and-drop.
  * The widget must first be made into a drag destination with
@@ -1666,7 +1666,7 @@ _gtk_drag_dest_handle_event (GtkWidget *toplevel,
  * gtk_drag_dest_find_target:
  * @widget: drag destination widget
  * @context: drag context
- * @target_list: list of droppable targets, or %NULL to use
+ * @target_list: (allow-none): list of droppable targets, or %NULL to use
  *    gtk_drag_dest_get_target_list (@widget).
  * 
  * Looks for a match between @context->targets and the
@@ -2693,7 +2693,7 @@ gtk_drag_source_get_target_list (GtkWidget *widget)
 /**
  * gtk_drag_source_set_target_list:
  * @widget: a #GtkWidget that's a drag source
- * @target_list: list of draggable targets, or %NULL for none
+ * @target_list: (allow-none): list of draggable targets, or %NULL for none
  *
  * Changes the target types that this widget offers for drag-and-drop.
  * The widget must first be made into a drag source with
@@ -3271,7 +3271,7 @@ gtk_drag_set_icon_stock  (GdkDragContext *context,
  *            with a  context for the source side of a drag)
  * @colormap: the colormap of the icon 
  * @pixmap: the image data for the icon 
- * @mask: the transparency mask for the icon or %NULL for none.
+ * @mask: (allow-none): the transparency mask for the icon or %NULL for none.
  * @hot_x: the X offset within @pixmap of the hotspot.
  * @hot_y: the Y offset within @pixmap of the hotspot.
  * 
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 31637b71b1..61421903d9 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -7438,8 +7438,8 @@ gtk_entry_text_index_to_layout_index (GtkEntry *entry,
 /**
  * gtk_entry_get_layout_offsets:
  * @entry: a #GtkEntry
- * @x: location to store X offset of layout, or %NULL
- * @y: location to store Y offset of layout, or %NULL
+ * @x: (allow-none): location to store X offset of layout, or %NULL
+ * @y: (allow-none): location to store Y offset of layout, or %NULL
  *
  *
  * Obtains the position of the #PangoLayout used to render text
@@ -7547,7 +7547,7 @@ gtk_entry_get_alignment (GtkEntry *entry)
  * gtk_entry_set_icon_from_pixbuf:
  * @entry: a #GtkEntry
  * @icon_pos: Icon position
- * @pixbuf: A #GdkPixbuf, or %NULL
+ * @pixbuf: (allow-none): A #GdkPixbuf, or %NULL
  *
  * Sets the icon shown in the specified position using a pixbuf.
  *
@@ -7610,7 +7610,7 @@ gtk_entry_set_icon_from_pixbuf (GtkEntry             *entry,
  * gtk_entry_set_icon_from_stock:
  * @entry: A #GtkEntry
  * @icon_pos: Icon position
- * @stock_id: The name of the stock item, or %NULL
+ * @stock_id: (allow-none): The name of the stock item, or %NULL
  *
  * Sets the icon shown in the entry at the specified position from
  * a stock image.
@@ -7677,7 +7677,7 @@ gtk_entry_set_icon_from_stock (GtkEntry             *entry,
  * gtk_entry_set_icon_from_icon_name:
  * @entry: A #GtkEntry
  * @icon_pos: The position at which to set the icon
- * @icon_name: An icon name, or %NULL
+ * @icon_name: (allow-none): An icon name, or %NULL
  *
  * Sets the icon shown in the entry at the specified position
  * from the current icon theme.
@@ -7747,7 +7747,7 @@ gtk_entry_set_icon_from_icon_name (GtkEntry             *entry,
  * gtk_entry_set_icon_from_gicon:
  * @entry: A #GtkEntry
  * @icon_pos: The position at which to set the icon
- * @icon: The icon to set, or %NULL
+ * @icon: (allow-none): The icon to set, or %NULL
  *
  * Sets the icon shown in the entry at the specified position
  * from the current icon theme.
@@ -8342,7 +8342,7 @@ gtk_entry_get_icon_tooltip_text (GtkEntry             *entry,
  * gtk_entry_set_icon_tooltip_text:
  * @entry: a #GtkEntry
  * @icon_pos: the icon position
- * @tooltip: the contents of the tooltip for the icon, or %NULL
+ * @tooltip: (allow-none): the contents of the tooltip for the icon, or %NULL
  *
  * Sets @tooltip as the contents of the tooltip for the icon
  * at the specified position.
@@ -8420,7 +8420,7 @@ gtk_entry_get_icon_tooltip_markup (GtkEntry             *entry,
  * gtk_entry_set_icon_tooltip_markup:
  * @entry: a #GtkEntry
  * @icon_pos: the icon position
- * @tooltip: the contents of the tooltip for the icon, or %NULL
+ * @tooltip: (allow-none): the contents of the tooltip for the icon, or %NULL
  *
  * Sets @tooltip as the contents of the tooltip for the icon at
  * the specified position. @tooltip is assumed to be marked up with
diff --git a/gtk/gtkentrybuffer.c b/gtk/gtkentrybuffer.c
index 57ce3b325a..33f81e30dc 100644
--- a/gtk/gtkentrybuffer.c
+++ b/gtk/gtkentrybuffer.c
@@ -434,7 +434,7 @@ gtk_entry_buffer_class_init (GtkEntryBufferClass *klass)
 
 /**
  * gtk_entry_buffer_new:
- * @initial_chars: initial buffer text, or %NULL
+ * @initial_chars: (allow-none): initial buffer text, or %NULL
  * @n_initial_chars: number of characters in @initial_chars, or -1
  *
  * Create a new GtkEntryBuffer object.
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 705a845dc6..048e89182a 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -1626,7 +1626,7 @@ gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
  * gtk_file_chooser_set_current_folder_file:
  * @chooser: a #GtkFileChooser
  * @file: the #GFile for the new folder
- * @error: location to store error, or %NULL.
+ * @error: (allow-none): location to store error, or %NULL.
  * 
  * Sets the current folder for @chooser from a #GFile.
  * Internal function, see gtk_file_chooser_set_current_folder_uri().
@@ -1671,7 +1671,7 @@ gtk_file_chooser_get_current_folder_file (GtkFileChooser *chooser)
  * gtk_file_chooser_select_file:
  * @chooser: a #GtkFileChooser
  * @file: the file to select
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Selects the file referred to by @file. An internal function. See
  * _gtk_file_chooser_select_uri().
@@ -1738,7 +1738,7 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  * gtk_file_chooser_set_file:
  * @chooser: a #GtkFileChooser
  * @file: the #GFile to set as current
- * @error: location to store the error, or %NULL to ignore errors.
+ * @error: (allow-none): location to store the error, or %NULL to ignore errors.
  *
  * Sets @file as the current filename for the file chooser, by changing
  * to the file's parent folder and actually selecting the file in list.  If
@@ -2027,7 +2027,7 @@ gtk_file_chooser_get_preview_file (GtkFileChooser *chooser)
  * _gtk_file_chooser_add_shortcut_folder:
  * @chooser: a #GtkFileChooser
  * @file: file for the folder to add
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Adds a folder to be displayed with the shortcut folders in a file chooser.
  * Internal function, see gtk_file_chooser_add_shortcut_folder().
@@ -2052,7 +2052,7 @@ _gtk_file_chooser_add_shortcut_folder (GtkFileChooser  *chooser,
  * _gtk_file_chooser_remove_shortcut_folder:
  * @chooser: a #GtkFileChooser
  * @file: file for the folder to remove
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Removes a folder from the shortcut folders in a file chooser.  Internal
  * function, see gtk_file_chooser_remove_shortcut_folder().
@@ -2301,7 +2301,7 @@ gtk_file_chooser_get_filter (GtkFileChooser *chooser)
  * gtk_file_chooser_add_shortcut_folder:
  * @chooser: a #GtkFileChooser
  * @folder: filename of the folder to add
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Adds a folder to be displayed with the shortcut folders in a file chooser.
  * Note that shortcut folders do not get saved, as they are provided by the
@@ -2335,7 +2335,7 @@ gtk_file_chooser_add_shortcut_folder (GtkFileChooser    *chooser,
  * gtk_file_chooser_remove_shortcut_folder:
  * @chooser: a #GtkFileChooser
  * @folder: filename of the folder to remove
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Removes a folder from a file chooser's list of shortcut folders.
  * 
@@ -2398,7 +2398,7 @@ gtk_file_chooser_list_shortcut_folders (GtkFileChooser *chooser)
  * gtk_file_chooser_add_shortcut_folder_uri:
  * @chooser: a #GtkFileChooser
  * @uri: URI of the folder to add
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Adds a folder URI to be displayed with the shortcut folders in a file
  * chooser.  Note that shortcut folders do not get saved, as they are provided
@@ -2432,7 +2432,7 @@ gtk_file_chooser_add_shortcut_folder_uri (GtkFileChooser    *chooser,
  * gtk_file_chooser_remove_shortcut_folder_uri:
  * @chooser: a #GtkFileChooser
  * @uri: URI of the folder to remove
- * @error: location to store error, or %NULL
+ * @error: (allow-none): location to store error, or %NULL
  * 
  * Removes a folder URI from a file chooser's list of shortcut folders.
  * 
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index f2fd98a346..e88e361afa 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -436,10 +436,10 @@ gtk_file_chooser_dialog_new_valist (const gchar          *title,
 
 /**
  * gtk_file_chooser_dialog_new:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL
  * @action: Open or save mode for the dialog
- * @first_button_text: stock ID or text to go in the first button, or %NULL
+ * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
  * @Varargs: response ID for the first button, then additional (button, id) pairs, ending with %NULL
  *
  * Creates a new #GtkFileChooserDialog.  This function is analogous to
@@ -470,11 +470,11 @@ gtk_file_chooser_dialog_new (const gchar         *title,
 
 /**
  * gtk_file_chooser_dialog_new_with_backend:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL
  * @action: Open or save mode for the dialog
  * @backend: The name of the specific filesystem backend to use.
- * @first_button_text: stock ID or text to go in the first button, or %NULL
+ * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
  * @Varargs: response ID for the first button, then additional (button, id) pairs, ending with %NULL
  *
  * Creates a new #GtkFileChooserDialog with a specified backend. This is
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index bb37078bc4..f64c5761bf 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -156,7 +156,7 @@ gtk_file_filter_new (void)
 /**
  * gtk_file_filter_set_name:
  * @filter: a #GtkFileFilter
- * @name: the human-readable-name for the filter, or %NULL
+ * @name: (allow-none): the human-readable-name for the filter, or %NULL
  *   to remove any existing name.
  * 
  * Sets the human-readable name of the filter; this is the string
diff --git a/gtk/gtkfilesystemmodel.c b/gtk/gtkfilesystemmodel.c
index c73ebb8fa0..5449d30b59 100644
--- a/gtk/gtkfilesystemmodel.c
+++ b/gtk/gtkfilesystemmodel.c
@@ -1333,7 +1333,7 @@ _gtk_file_system_model_new (GtkFileSystemModelGetValue get_func,
 /**
  * _gtk_file_system_model_new_for_directory:
  * @directory: the directory to show.
- * @attributes: attributes to immediately load or %NULL for all
+ * @attributes: (allow-none): attributes to immediately load or %NULL for all
  * @get_func: function that the model should call to query data about a file
  * @get_data: user data to pass to the @get_func
  * @n_columns: number of columns
@@ -1800,7 +1800,7 @@ _gtk_file_system_model_update_file (GtkFileSystemModel *model,
 /**
  * _gtk_file_system_model_set_filter:
  * @mode: a #GtkFileSystemModel
- * @filter: %NULL or filter to use
+ * @filter: (allow-none): %NULL or filter to use
  * 
  * Sets a filter to be used for deciding if a row should be visible or not.
  * Directories are always visible.
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c
index eba0fd9c4d..d8a637b35e 100644
--- a/gtk/gtkframe.c
+++ b/gtk/gtkframe.c
@@ -462,8 +462,8 @@ gtk_frame_set_label_align (GtkFrame *frame,
 /**
  * gtk_frame_get_label_align:
  * @frame: a #GtkFrame
- * @xalign: location to store X alignment of frame's label, or %NULL
- * @yalign: location to store X alignment of frame's label, or %NULL
+ * @xalign: (allow-none): location to store X alignment of frame's label, or %NULL
+ * @yalign: (allow-none): location to store X alignment of frame's label, or %NULL
  * 
  * Retrieves the X and Y alignment of the frame's label. See
  * gtk_frame_set_label_align().
diff --git a/gtk/gtkhscrollbar.c b/gtk/gtkhscrollbar.c
index 64eb5f4130..881e45ee29 100644
--- a/gtk/gtkhscrollbar.c
+++ b/gtk/gtkhscrollbar.c
@@ -49,7 +49,7 @@ gtk_hscrollbar_init (GtkHScrollbar *hscrollbar)
 
 /**
  * gtk_hscrollbar_new:
- * @adjustment: the #GtkAdjustment to use, or %NULL to create a new adjustment
+ * @adjustment: (allow-none): the #GtkAdjustment to use, or %NULL to create a new adjustment
  *
  * Creates a new horizontal scrollbar.
  *
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index a9754e4e22..c825a97242 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -1627,10 +1627,10 @@ render_fallback_image (GtkStyle          *style,
  * @state: widget state
  * @size: (type int): icon size. A size of (GtkIconSize)-1
  *        means render at the size of the source and don't scale.
- * @widget: widget that will display the icon, or %NULL.
+ * @widget: (allow-none): widget that will display the icon, or %NULL.
  *          The only use that is typically made of this
  *          is to determine the appropriate #GdkScreen.
- * @detail: detail to pass to the theme engine, or %NULL.
+ * @detail: (allow-none): detail to pass to the theme engine, or %NULL.
  *          Note that passing a detail of anything but %NULL
  *          will disable caching.
  *
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index bb678d0b75..67ed420332 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -744,7 +744,7 @@ gtk_icon_theme_set_search_path (GtkIconTheme *icon_theme,
 /**
  * gtk_icon_theme_get_search_path:
  * @icon_theme: a #GtkIconTheme
- * @path: (array length=n_elements) (out): location to store a list of icon theme path directories or %NULL
+ * @path: (allow-none): (array length=n_elements) (out): location to store a list of icon theme path directories or %NULL
  *        The stored value should be freed with g_strfreev().
  * @n_elements: location to store number of elements
  *              in @path, or %NULL
@@ -1497,7 +1497,7 @@ gtk_icon_theme_error_quark (void)
  * @size: the desired icon size. The resulting icon may not be
  *        exactly this size; see gtk_icon_info_load_icon().
  * @flags: flags modifying the behavior of the icon lookup
- * @error: Location to store error information on failure, or %NULL.
+ * @error: (allow-none): Location to store error information on failure, or %NULL.
  * 
  * Looks up an icon in an icon theme, scales it to the given size
  * and renders it into a pixbuf. This is a convenience function;
@@ -3035,7 +3035,7 @@ icon_info_ensure_scale_and_pixbuf (GtkIconInfo  *icon_info,
 /**
  * gtk_icon_info_load_icon:
  * @icon_info: a #GtkIconInfo structure from gtk_icon_theme_lookup_icon()
- * @error: location to store error information on failure, or %NULL.
+ * @error: (allow-none): location to store error information on failure, or %NULL.
  * 
  * Renders an icon previously looked up in an icon theme using
  * gtk_icon_theme_lookup_icon(); the size will be based on the size
@@ -3192,9 +3192,9 @@ gtk_icon_info_get_embedded_rect (GtkIconInfo  *icon_info,
 /**
  * gtk_icon_info_get_attach_points:
  * @icon_info: a #GtkIconInfo
- * @points: (array length=n_points) (out): location to store pointer to an array of points, or %NULL
+ * @points: (allow-none): (array length=n_points) (out): location to store pointer to an array of points, or %NULL
  *          free the array of points with g_free().
- * @n_points: location to store the number of points in @points, or %NULL
+ * @n_points: (allow-none): location to store the number of points in @points, or %NULL
  * 
  * Fetches the set of attach points for an icon. An attach point
  * is a location in the icon that can be used as anchor points for attaching
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 9a47509f93..91d1cdf2f0 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -2057,8 +2057,8 @@ gtk_icon_view_set_cursor (GtkIconView     *icon_view,
 /**
  * gtk_icon_view_get_cursor:
  * @icon_view: A #GtkIconView
- * @path: Return location for the current cursor path, or %NULL
- * @cell: Return location the current focus cell, or %NULL
+ * @path: (allow-none): Return location for the current cursor path, or %NULL
+ * @cell: (allow-none): Return location the current focus cell, or %NULL
  *
  * Fills in @path and @cell with the current cursor path and cell. 
  * If the cursor isn't currently set, then *@path will be %NULL.  
@@ -4826,7 +4826,7 @@ gtk_icon_view_get_path_at_pos (GtkIconView *icon_view,
  * @icon_view: A #GtkIconView.
  * @x: The x position to be identified
  * @y: The y position to be identified
- * @path: Return location for the path, or %NULL
+ * @path: (allow-none): Return location for the path, or %NULL
  * @cell: Return location for the renderer responsible for the cell
  *   at (@x, @y), or %NULL
  * 
@@ -4902,7 +4902,7 @@ gtk_icon_view_set_tooltip_item (GtkIconView     *icon_view,
  * @icon_view: a #GtkIconView
  * @tooltip: a #GtkTooltip
  * @path: a #GtkTreePath
- * @cell: a #GtkCellRenderer or %NULL
+ * @cell: (allow-none): a #GtkCellRenderer or %NULL
  *
  * Sets the tip area of @tooltip to the area which @cell occupies in
  * the item pointed to by @path. See also gtk_tooltip_set_tip_area().
@@ -4963,9 +4963,9 @@ gtk_icon_view_set_tooltip_cell (GtkIconView     *icon_view,
  * @x: the x coordinate (relative to widget coordinates)
  * @y: the y coordinate (relative to widget coordinates)
  * @keyboard_tip: whether this is a keyboard tooltip or not
- * @model: a pointer to receive a #GtkTreeModel or %NULL
- * @path: a pointer to receive a #GtkTreePath or %NULL
- * @iter: a pointer to receive a #GtkTreeIter or %NULL
+ * @model: (allow-none): a pointer to receive a #GtkTreeModel or %NULL
+ * @path: (allow-none): a pointer to receive a #GtkTreePath or %NULL
+ * @iter: (allow-none): a pointer to receive a #GtkTreeIter or %NULL
  *
  * This function is supposed to be used in a #GtkWidget::query-tooltip
  * signal handler for #GtkIconView.  The @x, @y and @keyboard_tip values
@@ -5135,8 +5135,8 @@ gtk_icon_view_get_tooltip_column (GtkIconView *icon_view)
 /**
  * gtk_icon_view_get_visible_range:
  * @icon_view: A #GtkIconView
- * @start_path: Return location for start of region, or %NULL
- * @end_path: Return location for end of region, or %NULL
+ * @start_path: (allow-none): Return location for start of region, or %NULL
+ * @end_path: (allow-none): Return location for end of region, or %NULL
  * 
  * Sets @start_path and @end_path to be the first and last visible path. 
  * Note that there may be invisible paths in between.
@@ -7258,8 +7258,8 @@ gtk_icon_view_set_drag_dest_item (GtkIconView              *icon_view,
 /**
  * gtk_icon_view_get_drag_dest_item:
  * @icon_view: a #GtkIconView
- * @path: Return location for the path of the highlighted item, or %NULL.
- * @pos: Return location for the drop position, or %NULL
+ * @path: (allow-none): Return location for the path of the highlighted item, or %NULL.
+ * @pos: (allow-none): Return location for the drop position, or %NULL
  * 
  * Gets information about the item that is highlighted for feedback.
  *
@@ -7289,8 +7289,8 @@ gtk_icon_view_get_drag_dest_item (GtkIconView              *icon_view,
  * @icon_view: a #GtkIconView
  * @drag_x: the position to determine the destination item for
  * @drag_y: the position to determine the destination item for
- * @path: Return location for the path of the item, or %NULL.
- * @pos: Return location for the drop position, or %NULL
+ * @path: (allow-none): Return location for the path of the item, or %NULL.
+ * @pos: (allow-none): Return location for the drop position, or %NULL
  * 
  * Determines the destination item for a given position.
  * 
diff --git a/gtk/gtkimcontext.c b/gtk/gtkimcontext.c
index 16ef87157a..2768b0b153 100644
--- a/gtk/gtkimcontext.c
+++ b/gtk/gtkimcontext.c
@@ -396,7 +396,7 @@ gtk_im_context_real_get_surrounding (GtkIMContext *context,
 /**
  * gtk_im_context_set_client_window:
  * @context: a #GtkIMContext
- * @window:  the client window. This may be %NULL to indicate
+ * @window: (allow-none):  the client window. This may be %NULL to indicate
  *           that the previous client window no longer exists.
  * 
  * Set the client window for the input context; this is the
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index be1e875269..9de968f7f8 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -882,7 +882,7 @@ gtk_info_bar_new (void)
 
 /**
  * gtk_info_bar_new_with_buttons:
- * @first_button_text: stock ID or text to go in first button, or %NULL
+ * @first_button_text: (allow-none): stock ID or text to go in first button, or %NULL
  * @...: response ID for first button, then additional buttons, ending
  *    with %NULL
  *
diff --git a/gtk/gtkitemfactory.c b/gtk/gtkitemfactory.c
index 2eab969869..4197866b14 100644
--- a/gtk/gtkitemfactory.c
+++ b/gtk/gtkitemfactory.c
@@ -423,7 +423,7 @@ gtk_item_factory_construct (GtkItemFactory	*ifactory,
  * gtk_item_factory_from_path:
  * @path: a string starting with a factory path of the form 
  *   <literal>"&lt;name&gt;"</literal>
- * @returns: the #GtkItemFactory created for the given factory path, or %NULL 
+ * @returns: (allow-none): the #GtkItemFactory created for the given factory path, or %NULL 
  *
  * Finds an item factory which has been constructed using the 
  * <literal>"&lt;name&gt;"</literal> prefix of @path as the @path argument 
@@ -521,7 +521,7 @@ gtk_item_factory_finalize (GObject *object)
 /**
  * gtk_item_factory_from_widget:
  * @widget: a widget
- * @returns: the item factory from which @widget was created, or %NULL
+ * @returns: (allow-none): the item factory from which @widget was created, or %NULL
  *
  * Obtains the item factory from which a widget was created.
  *
@@ -638,7 +638,7 @@ gtk_item_factory_create_items_ac (GtkItemFactory      *ifactory,
  * gtk_item_factory_get_widget:
  * @ifactory: a #GtkItemFactory
  * @path: the path to the widget
- * @returns: the widget for the given path, or %NULL if @path doesn't lead
+ * @returns: (allow-none): the widget for the given path, or %NULL if @path doesn't lead
  *   to a widget
  *
  * Obtains the widget which corresponds to @path. 
@@ -691,7 +691,7 @@ gtk_item_factory_get_widget (GtkItemFactory *ifactory,
  * @ifactory: a #GtkItemFactory
  * @action: an action as specified in the @callback_action field
  *   of #GtkItemFactoryEntry
- * @returns: the widget which corresponds to the given action, or %NULL
+ * @returns: (allow-none): the widget which corresponds to the given action, or %NULL
  *   if no widget was found
  *
  * Obtains the widget which was constructed from the #GtkItemFactoryEntry
@@ -728,7 +728,7 @@ gtk_item_factory_get_widget_by_action (GtkItemFactory *ifactory,
  * gtk_item_factory_get_item:
  * @ifactory: a #GtkItemFactory
  * @path: the path to the menu item
- * @returns: the menu item for the given path, or %NULL if @path doesn't
+ * @returns: (allow-none): the menu item for the given path, or %NULL if @path doesn't
  *   lead to a menu item
  *
  * Obtains the menu item which corresponds to @path. 
@@ -762,7 +762,7 @@ gtk_item_factory_get_item (GtkItemFactory *ifactory,
  * @ifactory: a #GtkItemFactory
  * @action: an action as specified in the @callback_action field
  *   of #GtkItemFactoryEntry
- * @returns: the menu item which corresponds to the given action, or %NULL
+ * @returns: (allow-none): the menu item which corresponds to the given action, or %NULL
  *   if no menu item was found
  *
  * Obtains the menu item which was constructed from the first 
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 35de1f95c5..9408de12a5 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -5019,8 +5019,8 @@ gtk_label_get_layout (GtkLabel *label)
 /**
  * gtk_label_get_layout_offsets:
  * @label: a #GtkLabel
- * @x: location to store X offset of layout, or %NULL
- * @y: location to store Y offset of layout, or %NULL
+ * @x: (allow-none): location to store X offset of layout, or %NULL
+ * @y: (allow-none): location to store Y offset of layout, or %NULL
  *
  * Obtains the coordinates where the label will draw the #PangoLayout
  * representing the text in the label; useful to convert mouse events
diff --git a/gtk/gtklayout.c b/gtk/gtklayout.c
index 0a11f48112..f46b473dc4 100644
--- a/gtk/gtklayout.c
+++ b/gtk/gtklayout.c
@@ -118,8 +118,8 @@ G_DEFINE_TYPE (GtkLayout, gtk_layout, GTK_TYPE_CONTAINER)
  */
 /**
  * gtk_layout_new:
- * @hadjustment: horizontal scroll adjustment, or %NULL
- * @vadjustment: vertical scroll adjustment, or %NULL
+ * @hadjustment: (allow-none): horizontal scroll adjustment, or %NULL
+ * @vadjustment: (allow-none): vertical scroll adjustment, or %NULL
  * 
  * Creates a new #GtkLayout. Unless you have a specific adjustment
  * you'd like the layout to use for scrolling, pass %NULL for
@@ -513,8 +513,8 @@ gtk_layout_set_size (GtkLayout     *layout,
 /**
  * gtk_layout_get_size:
  * @layout: a #GtkLayout
- * @width: location to store the width set on @layout, or %NULL
- * @height: location to store the height set on @layout, or %NULL
+ * @width: (allow-none): location to store the width set on @layout, or %NULL
+ * @height: (allow-none): location to store the height set on @layout, or %NULL
  *
  * Gets the size that has been set on the layout, and that determines
  * the total extents of the layout's scrollbar area. See
diff --git a/gtk/gtklinkbutton.c b/gtk/gtklinkbutton.c
index eaa6678dc2..3fa7f955eb 100644
--- a/gtk/gtklinkbutton.c
+++ b/gtk/gtklinkbutton.c
@@ -703,9 +703,9 @@ gtk_link_button_get_uri (GtkLinkButton *link_button)
 
 /**
  * gtk_link_button_set_uri_hook:
- * @func: a function called each time a #GtkLinkButton is clicked, or %NULL
- * @data: user data to be passed to @func, or %NULL
- * @destroy: a #GDestroyNotify that gets called when @data is no longer needed, or %NULL
+ * @func: (allow-none): a function called each time a #GtkLinkButton is clicked, or %NULL
+ * @data: (allow-none): user data to be passed to @func, or %NULL
+ * @destroy: (allow-none): a #GDestroyNotify that gets called when @data is no longer needed, or %NULL
  *
  * Sets @func as the function that should be invoked every time a user clicks
  * a #GtkLinkButton. This function is called before every callback registered
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 71ceb1cad0..d9cd3fd242 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -1042,7 +1042,7 @@ gtk_list_store_insert (GtkListStore *list_store,
  * gtk_list_store_insert_before:
  * @list_store: A #GtkListStore
  * @iter: An unset #GtkTreeIter to set to the new row
- * @sibling: A valid #GtkTreeIter, or %NULL
+ * @sibling: (allow-none): A valid #GtkTreeIter, or %NULL
  *
  * Inserts a new row before @sibling. If @sibling is %NULL, then the row will 
  * be appended to the end of the list. @iter will be changed to point to this 
@@ -1074,7 +1074,7 @@ gtk_list_store_insert_before (GtkListStore *list_store,
  * gtk_list_store_insert_after:
  * @list_store: A #GtkListStore
  * @iter: An unset #GtkTreeIter to set to the new row
- * @sibling: A valid #GtkTreeIter, or %NULL
+ * @sibling: (allow-none): A valid #GtkTreeIter, or %NULL
  *
  * Inserts a new row after @sibling. If @sibling is %NULL, then the row will be
  * prepended to the beginning of the list. @iter will be changed to point to
@@ -1883,7 +1883,7 @@ gtk_list_store_has_default_sort_func (GtkTreeSortable *sortable)
 /**
  * gtk_list_store_insert_with_values:
  * @list_store: A #GtkListStore
- * @iter: An unset #GtkTreeIter to set to the new row, or %NULL.
+ * @iter: (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL.
  * @position: position to insert the new row
  * @Varargs: pairs of column number and value, terminated with -1
  *
@@ -1969,7 +1969,7 @@ gtk_list_store_insert_with_values (GtkListStore *list_store,
 /**
  * gtk_list_store_insert_with_valuesv:
  * @list_store: A #GtkListStore
- * @iter: An unset #GtkTreeIter to set to the new row, or %NULL.
+ * @iter: (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL.
  * @position: position to insert the new row
  * @columns: an array of column numbers
  * @values: an array of GValues 
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 55bf5d9f97..2f04718b16 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1397,9 +1397,9 @@ popup_grab_on_window (GdkWindow *window,
 /**
  * gtk_menu_popup:
  * @menu: a #GtkMenu.
- * @parent_menu_shell: the menu shell containing the triggering menu item, or %NULL
- * @parent_menu_item: the menu item whose activation triggered the popup, or %NULL
- * @func: a user supplied function used to position the menu, or %NULL
+ * @parent_menu_shell: (allow-none): the menu shell containing the triggering menu item, or %NULL
+ * @parent_menu_item: (allow-none): the menu item whose activation triggered the popup, or %NULL
+ * @func: (allow-none): a user supplied function used to position the menu, or %NULL
  * @data: user supplied data to be passed to @func.
  * @button: the mouse button which was pressed to initiate the event.
  * @activate_time: the time at which the activation event occurred.
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 1f3e1a9691..cafddb563e 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -754,7 +754,7 @@ gtk_menu_item_set_use_action_appearance (GtkMenuItem *menu_item,
 /**
  * gtk_menu_item_set_submenu:
  * @menu_item: a #GtkMenuItem
- * @submenu: the submenu, or %NULL
+ * @submenu: (allow-none): the submenu, or %NULL
  *
  * Sets or replaces the menu item's submenu, or removes it when a %NULL
  * submenu is passed.
diff --git a/gtk/gtkmenutoolbutton.c b/gtk/gtkmenutoolbutton.c
index c0022fe0f5..c5e1c54b3b 100644
--- a/gtk/gtkmenutoolbutton.c
+++ b/gtk/gtkmenutoolbutton.c
@@ -442,8 +442,8 @@ gtk_menu_tool_button_destroy (GtkObject *object)
 
 /**
  * gtk_menu_tool_button_new:
- * @icon_widget: a widget that will be used as icon widget, or %NULL
- * @label: a string that will be used as label, or %NULL
+ * @icon_widget: (allow-none): a widget that will be used as icon widget, or %NULL
+ * @label: (allow-none): a string that will be used as label, or %NULL
  *
  * Creates a new #GtkMenuToolButton using @icon_widget as icon and
  * @label as label.
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index b721aded36..71a4098b54 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -544,11 +544,11 @@ gtk_message_dialog_new (GtkWindow     *parent,
 
 /**
  * gtk_message_dialog_new_with_markup:
- * @parent: transient parent, or %NULL for none 
+ * @parent: (allow-none): transient parent, or %NULL for none 
  * @flags: flags
  * @type: type of message
  * @buttons: set of buttons to use
- * @message_format: printf()-style format string, or %NULL
+ * @message_format: (allow-none): printf()-style format string, or %NULL
  * @Varargs: arguments for @message_format
  * 
  * Creates a new message dialog, which is a simple dialog with an icon
@@ -695,7 +695,7 @@ gtk_message_dialog_set_markup (GtkMessageDialog *message_dialog,
 /**
  * gtk_message_dialog_format_secondary_text:
  * @message_dialog: a #GtkMessageDialog
- * @message_format: printf()-style format string, or %NULL
+ * @message_format: (allow-none): printf()-style format string, or %NULL
  * @Varargs: arguments for @message_format
  * 
  * Sets the secondary text of the message dialog to be @message_format 
diff --git a/gtk/gtkmisc.c b/gtk/gtkmisc.c
index 3532ab90ce..2d102a54e7 100644
--- a/gtk/gtkmisc.c
+++ b/gtk/gtkmisc.c
@@ -223,8 +223,8 @@ gtk_misc_set_alignment (GtkMisc *misc,
 /**
  * gtk_misc_get_alignment:
  * @misc: a #GtkMisc
- * @xalign: location to store X alignment of @misc, or %NULL
- * @yalign: location to store Y alignment of @misc, or %NULL
+ * @xalign: (allow-none): location to store X alignment of @misc, or %NULL
+ * @yalign: (allow-none): location to store Y alignment of @misc, or %NULL
  *
  * Gets the X and Y alignment of the widget within its allocation. 
  * See gtk_misc_set_alignment().
@@ -285,8 +285,8 @@ gtk_misc_set_padding (GtkMisc *misc,
 /**
  * gtk_misc_get_padding:
  * @misc: a #GtkMisc
- * @xpad: location to store padding in the X direction, or %NULL
- * @ypad: location to store padding in the Y direction, or %NULL
+ * @xpad: (allow-none): location to store padding in the X direction, or %NULL
+ * @ypad: (allow-none): location to store padding in the Y direction, or %NULL
  *
  * Gets the padding in the X and Y directions of the widget. 
  * See gtk_misc_set_padding().
diff --git a/gtk/gtkmountoperation.c b/gtk/gtkmountoperation.c
index eff119067c..d611631bb8 100644
--- a/gtk/gtkmountoperation.c
+++ b/gtk/gtkmountoperation.c
@@ -1359,7 +1359,7 @@ gtk_mount_operation_aborted (GMountOperation *op)
 
 /**
  * gtk_mount_operation_new:
- * @parent: transient parent of the window, or %NULL
+ * @parent: (allow-none): transient parent of the window, or %NULL
  *
  * Creates a new #GtkMountOperation
  *
@@ -1400,7 +1400,7 @@ gtk_mount_operation_is_showing (GtkMountOperation *op)
 /**
  * gtk_mount_operation_set_parent:
  * @op: a #GtkMountOperation
- * @parent: transient parent of the window, or %NULL
+ * @parent: (allow-none): transient parent of the window, or %NULL
  *
  * Sets the transient parent for windows shown by the
  * #GtkMountOperation.
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index ef9fba5d73..392afedd5a 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -7653,9 +7653,9 @@ gtk_notebook_reorder_child (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_window_creation_hook:
- * @func: the #GtkNotebookWindowCreationFunc, or %NULL
+ * @func: (allow-none): the #GtkNotebookWindowCreationFunc, or %NULL
  * @data: user data for @func
- * @destroy: Destroy notifier for @data, or %NULL
+ * @destroy: (allow-none): Destroy notifier for @data, or %NULL
  *
  * Installs a global function used to create a window
  * when a detached tab is dropped in an empty area.
@@ -7704,7 +7704,7 @@ gtk_notebook_set_group_id (GtkNotebook *notebook,
 /**
  * gtk_notebook_set_group:
  * @notebook: a #GtkNotebook
- * @group: a pointer to identify the notebook group, or %NULL to unset it
+ * @group: (allow-none): a pointer to identify the notebook group, or %NULL to unset it
  *
  * Sets a group identificator pointer for @notebook, notebooks sharing
  * the same group identificator pointer will be able to exchange tabs
diff --git a/gtk/gtkpagesetup.c b/gtk/gtkpagesetup.c
index 9519fded07..0e8c153b77 100644
--- a/gtk/gtkpagesetup.c
+++ b/gtk/gtkpagesetup.c
@@ -476,7 +476,7 @@ gtk_page_setup_get_page_height (GtkPageSetup *setup,
  * gtk_page_setup_load_file:
  * @setup: a #GtkPageSetup
  * @file_name: the filename to read the page setup from
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads the page setup from the file @file_name.
  * See gtk_page_setup_to_file().
@@ -510,7 +510,7 @@ gtk_page_setup_load_file (GtkPageSetup *setup,
 /**
  * gtk_page_setup_new_from_file:
  * @file_name: the filename to read the page setup from
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  * 
  * Reads the page setup from the file @file_name. Returns a 
  * new #GtkPageSetup object with the restored page setup, 
@@ -560,9 +560,9 @@ string_to_enum (GType type,
  * gtk_page_setup_load_key_file:
  * @setup: a #GtkPageSetup
  * @key_file: the #GKeyFile to retrieve the page_setup from
- * @group_name: the name of the group in the key_file to read, or %NULL
+ * @group_name: (allow-none): the name of the group in the key_file to read, or %NULL
  *              to use the default name "Page Setup"
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  * 
  * Reads the page setup from the group @group_name in the key file
  * @key_file.
@@ -648,9 +648,9 @@ out:
 /**
  * gtk_page_setup_new_from_key_file:
  * @key_file: the #GKeyFile to retrieve the page_setup from
- * @group_name: the name of the group in the key_file to read, or %NULL
+ * @group_name: (allow-none): the name of the group in the key_file to read, or %NULL
  *              to use the default name "Page Setup"
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads the page setup from the group @group_name in the key file
  * @key_file. Returns a new #GtkPageSetup object with the restored
@@ -680,7 +680,7 @@ gtk_page_setup_new_from_key_file (GKeyFile     *key_file,
  * gtk_page_setup_to_file:
  * @setup: a #GtkPageSetup
  * @file_name: the file to save to
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  * 
  * This function saves the information from @setup to @file_name.
  * 
diff --git a/gtk/gtkpagesetupunixdialog.c b/gtk/gtkpagesetupunixdialog.c
index 6cc2989ad0..c5f63bf708 100644
--- a/gtk/gtkpagesetupunixdialog.c
+++ b/gtk/gtkpagesetupunixdialog.c
@@ -992,8 +992,8 @@ populate_dialog (GtkPageSetupUnixDialog *ps_dialog)
 
 /**
  * gtk_page_setup_unix_dialog_new:
- * @title: the title of the dialog, or %NULL
- * @parent: transient parent of the dialog, or %NULL
+ * @title: (allow-none): the title of the dialog, or %NULL
+ * @parent: (allow-none): transient parent of the dialog, or %NULL
  *
  * Creates a new page setup dialog.
  *
diff --git a/gtk/gtkpapersize.c b/gtk/gtkpapersize.c
index f24b15f0b2..7188cefe6c 100644
--- a/gtk/gtkpapersize.c
+++ b/gtk/gtkpapersize.c
@@ -792,7 +792,7 @@ gtk_paper_size_get_default_right_margin (GtkPaperSize *size,
  * @key_file: the #GKeyFile to retrieve the papersize from
  * @group_name: the name ofthe group in the key file to read,
  *     or %NULL to read the first group
- * @error: return location for an error, or %NULL
+ * @error: (allow-none): return location for an error, or %NULL
  *
  * Reads a paper size from the group @group_name in the key file
  * @key_file. 
diff --git a/gtk/gtkprintjob.c b/gtk/gtkprintjob.c
index 51d41d1e08..af76152718 100644
--- a/gtk/gtkprintjob.c
+++ b/gtk/gtkprintjob.c
@@ -441,7 +441,7 @@ gtk_print_job_set_source_file (GtkPrintJob *job,
 /**
  * gtk_print_job_get_surface:
  * @job: a #GtkPrintJob
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  * 
  * Gets a cairo surface onto which the pages of
  * the print job should be rendered.
diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c
index c10a1d6cf0..dbf622846f 100644
--- a/gtk/gtkprintoperation-unix.c
+++ b/gtk/gtkprintoperation-unix.c
@@ -1011,8 +1011,8 @@ gtk_print_run_page_setup_dialog (GtkWindow        *parent,
 
 /**
  * gtk_print_run_page_setup_dialog_async:
- * @parent: transient parent, or %NULL
- * @page_setup: an existing #GtkPageSetup, or %NULL
+ * @parent: (allow-none): transient parent, or %NULL
+ * @page_setup: (allow-none): an existing #GtkPageSetup, or %NULL
  * @settings: a #GtkPrintSettings
  * @done_cb: a function to call when the user saves the modified page setup
  * @data: user data to pass to @done_cb
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index bc1b27f57d..72285730c6 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -944,7 +944,7 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class)
    * @operation: the #GtkPrintOperation on which the signal was emitted
    * @preview: the #GtkPrintPreviewOperation for the current operation
    * @context: the #GtkPrintContext that will be used
-   * @parent: the #GtkWindow to use as window parent, or %NULL
+   * @parent: (allow-none): the #GtkWindow to use as window parent, or %NULL
    *
    * Gets emitted when a preview is requested from the native dialog.
    *
@@ -1854,7 +1854,7 @@ gtk_print_operation_set_allow_async (GtkPrintOperation  *op,
 /**
  * gtk_print_operation_set_custom_tab_label:
  * @op: a #GtkPrintOperation
- * @label: the label to use, or %NULL to use the default label
+ * @label: (allow-none): the label to use, or %NULL to use the default label
  *
  * Sets the label for the tab holding custom widgets.
  *
@@ -2993,7 +2993,7 @@ gtk_print_operation_get_error (GtkPrintOperation  *op,
  * @op: a #GtkPrintOperation
  * @action: the action to start
  * @parent: (allow-none): Transient parent of the dialog
- * @error: Return location for errors, or %NULL
+ * @error: (allow-none): Return location for errors, or %NULL
  *
  * Runs the print operation, by first letting the user modify
  * print settings in the print dialog, and then print the document.
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index 748c6ee0d0..4ae7962224 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -1674,7 +1674,7 @@ gtk_print_settings_set_output_bin (GtkPrintSettings *settings,
  * gtk_print_settings_load_file:
  * @settings: a #GtkPrintSettings
  * @file_name: the filename to read the settings from
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  *
  * Reads the print settings from @file_name. If the file could not be loaded
  * then error is set to either a #GFileError or #GKeyFileError.
@@ -1709,7 +1709,7 @@ gtk_print_settings_load_file (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_new_from_file:
  * @file_name: the filename to read the settings from
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  * 
  * Reads the print settings from @file_name. Returns a new #GtkPrintSettings
  * object with the restored settings, or %NULL if an error occurred. If the
@@ -1739,9 +1739,9 @@ gtk_print_settings_new_from_file (const gchar  *file_name,
  * gtk_print_settings_load_key_file:
  * @settings: a #GtkPrintSettings
  * @key_file: the #GKeyFile to retrieve the settings from
- * @group_name: the name of the group to use, or %NULL to use the default
+ * @group_name: (allow-none): the name of the group to use, or %NULL to use the default
  *     "Print Settings"
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  * 
  * Reads the print settings from the group @group_name in @key_file. If the
  * file could not be loaded then error is set to either a #GFileError or
@@ -1800,9 +1800,9 @@ gtk_print_settings_load_key_file (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_new_from_key_file:
  * @key_file: the #GKeyFile to retrieve the settings from
- * @group_name: the name of the group to use, or %NULL to use
+ * @group_name: (allow-none): the name of the group to use, or %NULL to use
  *     the default "Print Settings"
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  *
  * Reads the print settings from the group @group_name in @key_file.  Returns a
  * new #GtkPrintSettings object with the restored settings, or %NULL if an
@@ -1834,7 +1834,7 @@ gtk_print_settings_new_from_key_file (GKeyFile     *key_file,
  * gtk_print_settings_to_file:
  * @settings: a #GtkPrintSettings
  * @file_name: the file to save to
- * @error: return location for errors, or %NULL
+ * @error: (allow-none): return location for errors, or %NULL
  * 
  * This function saves the print settings from @settings to @file_name. If the
  * file could not be loaded then error is set to either a #GFileError or
diff --git a/gtk/gtkprintunixdialog.c b/gtk/gtkprintunixdialog.c
index 92299765c2..bee3cdfe2d 100644
--- a/gtk/gtkprintunixdialog.c
+++ b/gtk/gtkprintunixdialog.c
@@ -3819,8 +3819,8 @@ populate_dialog (GtkPrintUnixDialog *print_dialog)
 
 /**
  * gtk_print_unix_dialog_new:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL
  *
  * Creates a new #GtkPrintUnixDialog.
  *
@@ -4029,7 +4029,7 @@ set_active_printer (GtkPrintUnixDialog *dialog,
 /**
  * gtk_print_unix_dialog_set_settings:
  * @dialog: a #GtkPrintUnixDialog
- * @settings: a #GtkPrintSettings, or %NULL
+ * @settings: (allow-none): a #GtkPrintSettings, or %NULL
  *
  * Sets the #GtkPrintSettings for the #GtkPrintUnixDialog. Typically,
  * this is used to restore saved print settings from a previous print
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index f2c51d8d69..e5f5554b8a 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -1155,7 +1155,7 @@ gtk_progress_bar_pulse (GtkProgressBar *pbar)
 /**
  * gtk_progress_bar_set_text:
  * @pbar: a #GtkProgressBar
- * @text: a UTF-8 string, or %NULL 
+ * @text: (allow-none): a UTF-8 string, or %NULL 
  * 
  * Causes the given @text to appear superimposed on the progress bar.
  **/
diff --git a/gtk/gtkradioaction.c b/gtk/gtkradioaction.c
index 1d9cfc56e6..8338e17a6d 100644
--- a/gtk/gtkradioaction.c
+++ b/gtk/gtkradioaction.c
@@ -183,8 +183,8 @@ gtk_radio_action_init (GtkRadioAction *action)
 /**
  * gtk_radio_action_new:
  * @name: A unique name for the action
- * @label: The label displayed in menu items and on buttons, or %NULL
- * @tooltip: A tooltip for this action, or %NULL
+ * @label: (allow-none): The label displayed in menu items and on buttons, or %NULL
+ * @tooltip: (allow-none): A tooltip for this action, or %NULL
  * @stock_id: The stock icon to display in widgets representing this
  *   action, or %NULL
  * @value: The value which gtk_radio_action_get_current_value() should
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index cef0bb216b..5916378610 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -322,7 +322,7 @@ gtk_radio_button_new_with_label_from_widget (GtkRadioButton *radio_group_member,
 
 /**
  * gtk_radio_button_new_with_mnemonic_from_widget:
- * @radio_group_member: widget to get radio group from or %NULL
+ * @radio_group_member: (allow-none): widget to get radio group from or %NULL
  * @label: the text of the button, with an underscore in front of the
  *         mnemonic character
  * @returns: a new #GtkRadioButton
diff --git a/gtk/gtkradiotoolbutton.c b/gtk/gtkradiotoolbutton.c
index e5e385173b..1aa37da1fb 100644
--- a/gtk/gtkradiotoolbutton.c
+++ b/gtk/gtkradiotoolbutton.c
@@ -109,7 +109,7 @@ gtk_radio_tool_button_set_property (GObject         *object,
 
 /**
  * gtk_radio_tool_button_new:
- * @group: An existing radio button group, or %NULL if you are creating a new group
+ * @group: (allow-none): An existing radio button group, or %NULL if you are creating a new group
  * 
  * Creates a new #GtkRadioToolButton, adding it to @group.
  * 
@@ -132,7 +132,7 @@ gtk_radio_tool_button_new (GSList *group)
 
 /**
  * gtk_radio_tool_button_new_from_stock:
- * @group: an existing radio button group, or %NULL if you are creating a new group
+ * @group: (allow-none): an existing radio button group, or %NULL if you are creating a new group
  * @stock_id: the name of a stock item
  * 
  * Creates a new #GtkRadioToolButton, adding it to @group. 
diff --git a/gtk/gtkrange.c b/gtk/gtkrange.c
index 90cd8cbdf2..7c361e7896 100644
--- a/gtk/gtkrange.c
+++ b/gtk/gtkrange.c
@@ -1012,8 +1012,8 @@ gtk_range_get_range_rect (GtkRange     *range,
 /**
  * gtk_range_get_slider_range:
  * @range: a #GtkRange
- * @slider_start: return location for the slider's start, or %NULL
- * @slider_end: return location for the slider's end, or %NULL
+ * @slider_start: (allow-none): return location for the slider's start, or %NULL
+ * @slider_end: (allow-none): return location for the slider's end, or %NULL
  *
  * This function returns sliders range along the long dimension,
  * in widget->window coordinates.
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index 691cbf1049..2e94cdfcec 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -3868,7 +3868,7 @@ gtk_rc_parse_color (GScanner *scanner,
 /**
  * gtk_rc_parse_color_full:
  * @scanner: a #GScanner
- * @style: a #GtkRcStyle, or %NULL
+ * @style: (allow-none): a #GtkRcStyle, or %NULL
  * @color: a pointer to a #GdkColor structure in which to store the result
  *
  * Parses a color in the <link linkend="color=format">format</link> expected
diff --git a/gtk/gtkrecentaction.c b/gtk/gtkrecentaction.c
index bf5c6d081e..14acfb426a 100644
--- a/gtk/gtkrecentaction.c
+++ b/gtk/gtkrecentaction.c
@@ -649,8 +649,8 @@ gtk_recent_action_init (GtkRecentAction *action)
 /**
  * gtk_recent_action_new:
  * @name: a unique name for the action
- * @label: the label displayed in menu items and on buttons, or %NULL
- * @tooltip: a tooltip for the action, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @tooltip: (allow-none): a tooltip for the action, or %NULL
  * @stock_id: the stock icon to display in widgets representing the
  *   action, or %NULL
  *
@@ -681,11 +681,11 @@ gtk_recent_action_new (const gchar *name,
 /**
  * gtk_recent_action_new_for_manager:
  * @name: a unique name for the action
- * @label: the label displayed in menu items and on buttons, or %NULL
- * @tooltip: a tooltip for the action, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @tooltip: (allow-none): a tooltip for the action, or %NULL
  * @stock_id: the stock icon to display in widgets representing the
  *   action, or %NULL
- * @manager: a #GtkRecentManager, or %NULL for using the default
+ * @manager: (allow-none): a #GtkRecentManager, or %NULL for using the default
  *   #GtkRecentManager
  *
  * Creates a new #GtkRecentAction object. To add the action to
diff --git a/gtk/gtkrecentchooser.c b/gtk/gtkrecentchooser.c
index a69b1c21fb..bb84ef5e07 100644
--- a/gtk/gtkrecentchooser.c
+++ b/gtk/gtkrecentchooser.c
@@ -717,8 +717,8 @@ gtk_recent_chooser_get_sort_type (GtkRecentChooser *chooser)
  * gtk_recent_chooser_set_sort_func:
  * @chooser: a #GtkRecentChooser
  * @sort_func: the comparison function
- * @sort_data: user data to pass to @sort_func, or %NULL
- * @data_destroy: destroy notifier for @sort_data, or %NULL
+ * @sort_data: (allow-none): user data to pass to @sort_func, or %NULL
+ * @data_destroy: (allow-none): destroy notifier for @sort_data, or %NULL
  *
  * Sets the comparison function used when sorting to be @sort_func.  If
  * the @chooser has the sort type set to #GTK_RECENT_SORT_CUSTOM then
@@ -749,7 +749,7 @@ gtk_recent_chooser_set_sort_func  (GtkRecentChooser  *chooser,
  * gtk_recent_chooser_set_current_uri:
  * @chooser: a #GtkRecentChooser
  * @uri: a URI
- * @error: return location for a #GError, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
  *
  * Sets @uri as the current URI for @chooser.
  *
@@ -820,7 +820,7 @@ gtk_recent_chooser_get_current_item (GtkRecentChooser *chooser)
  * gtk_recent_chooser_select_uri:
  * @chooser: a #GtkRecentChooser
  * @uri: a URI
- * @error: return location for a #GError, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
  *
  * Selects @uri inside @chooser.
  *
@@ -916,7 +916,7 @@ gtk_recent_chooser_get_items (GtkRecentChooser *chooser)
 /**
  * gtk_recent_chooser_get_uris:
  * @chooser: a #GtkRecentChooser
- * @length: return location for a the length of the URI list, or %NULL
+ * @length: (allow-none): return location for a the length of the URI list, or %NULL
  *
  * Gets the URI of the recently used resources.
  *
diff --git a/gtk/gtkrecentchooserdialog.c b/gtk/gtkrecentchooserdialog.c
index 09910149d7..abce5ea6da 100644
--- a/gtk/gtkrecentchooserdialog.c
+++ b/gtk/gtkrecentchooserdialog.c
@@ -278,9 +278,9 @@ gtk_recent_chooser_dialog_new_valist (const gchar      *title,
 
 /**
  * gtk_recent_chooser_dialog_new:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL,
- * @first_button_text: stock ID or text to go in the first button, or %NULL
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL,
+ * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
  * @Varargs: response ID for the first button, then additional (button, id)
  *   pairs, ending with %NULL
  *
@@ -313,10 +313,10 @@ gtk_recent_chooser_dialog_new (const gchar *title,
 
 /**
  * gtk_recent_chooser_dialog_new_for_manager:
- * @title: Title of the dialog, or %NULL
- * @parent: Transient parent of the dialog, or %NULL,
+ * @title: (allow-none): Title of the dialog, or %NULL
+ * @parent: (allow-none): Transient parent of the dialog, or %NULL,
  * @manager: a #GtkRecentManager
- * @first_button_text: stock ID or text to go in the first button, or %NULL
+ * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
  * @Varargs: response ID for the first button, then additional (button, id)
  *   pairs, ending with %NULL
  *
diff --git a/gtk/gtkrecentchooserutils.c b/gtk/gtkrecentchooserutils.c
index 8c3abb22fe..f0a0009022 100644
--- a/gtk/gtkrecentchooserutils.c
+++ b/gtk/gtkrecentchooserutils.c
@@ -402,8 +402,8 @@ get_is_recent_filtered (GtkRecentFilter *filter,
  * _gtk_recent_chooser_get_items:
  * @chooser: a #GtkRecentChooser
  * @filter: a #GtkRecentFilter
- * @sort_func: sorting function, or %NULL
- * @sort_data: sorting function data, or %NULL
+ * @sort_func: (allow-none): sorting function, or %NULL
+ * @sort_data: (allow-none): sorting function data, or %NULL
  *
  * Default implementation for getting the filtered, sorted and
  * clamped list of recently used resources from a #GtkRecentChooser.
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 3fd7d34fee..4181d4a0e2 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -986,7 +986,7 @@ gtk_recent_manager_add_full (GtkRecentManager     *manager,
  * gtk_recent_manager_remove_item:
  * @manager: a #GtkRecentManager
  * @uri: the URI of the item you wish to remove
- * @error: return location for a #GError, or %NULL
+ * @error: (allow-none): return location for a #GError, or %NULL
  *
  * Removes a resource pointed by @uri from the recently used resources
  * list handled by a recent manager.
@@ -1135,7 +1135,7 @@ build_recent_info (GBookmarkFile  *bookmarks,
  * gtk_recent_manager_lookup_item:
  * @manager: a #GtkRecentManager
  * @uri: a URI
- * @error: a return location for a #GError, or %NULL
+ * @error: (allow-none): a return location for a #GError, or %NULL
  *
  * Searches for a URI inside the recently used resources list, and
  * returns a structure containing informations about the resource
@@ -1198,9 +1198,9 @@ gtk_recent_manager_lookup_item (GtkRecentManager  *manager,
  * gtk_recent_manager_move_item:
  * @manager: a #GtkRecentManager
  * @uri: the URI of a recently used resource
- * @new_uri: the new URI of the recently used resource, or %NULL to
+ * @new_uri: (allow-none): the new URI of the recently used resource, or %NULL to
  *    remove the item pointed by @uri in the list
- * @error: a return location for a #GError, or %NULL
+ * @error: (allow-none): a return location for a #GError, or %NULL
  *
  * Changes the location of a recently used resource from @uri to @new_uri.
  * 
@@ -1339,7 +1339,7 @@ purge_recent_items_list (GtkRecentManager  *manager,
 /**
  * gtk_recent_manager_purge_items:
  * @manager: a #GtkRecentManager
- * @error: a return location for a #GError, or %NULL
+ * @error: (allow-none): a return location for a #GError, or %NULL
  *
  * Purges every item from the recently used resources list.
  *
diff --git a/gtk/gtkruler.c b/gtk/gtkruler.c
index 1000780e51..6e581aecbb 100644
--- a/gtk/gtkruler.c
+++ b/gtk/gtkruler.c
@@ -386,9 +386,9 @@ gtk_ruler_set_range (GtkRuler *ruler,
 /**
  * gtk_ruler_get_range:
  * @ruler: a #GtkRuler
- * @lower: location to store lower limit of the ruler, or %NULL
- * @upper: location to store upper limit of the ruler, or %NULL
- * @position: location to store the current position of the mark on the ruler, or %NULL
+ * @lower: (allow-none): location to store lower limit of the ruler, or %NULL
+ * @upper: (allow-none): location to store upper limit of the ruler, or %NULL
+ * @position: (allow-none): location to store the current position of the mark on the ruler, or %NULL
  * @max_size: location to store the maximum size of the ruler used when calculating
  *            the space to leave for the text, or %NULL.
  *
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index a69e05375f..cc2e70d50f 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -1297,8 +1297,8 @@ gtk_scale_get_layout (GtkScale *scale)
 /**
  * gtk_scale_get_layout_offsets:
  * @scale: a #GtkScale
- * @x: location to store X offset of layout, or %NULL
- * @y: location to store Y offset of layout, or %NULL
+ * @x: (allow-none): location to store X offset of layout, or %NULL
+ * @y: (allow-none): location to store Y offset of layout, or %NULL
  *
  * Obtains the coordinates where the scale will draw the 
  * #PangoLayout representing the text in the scale. Remember
@@ -1394,7 +1394,7 @@ compare_marks (gpointer a, gpointer b)
  *   is drawn above the scale, anything else below. For a vertical scale,
  *   #GTK_POS_LEFT is drawn to the left of the scale, anything else to the
  *   right.
- * @markup: Text to be shown at the mark, using <link linkend="PangoMarkupFormat">Pango markup</link>, or %NULL
+ * @markup: (allow-none): Text to be shown at the mark, using <link linkend="PangoMarkupFormat">Pango markup</link>, or %NULL
  *
  *
  * Adds a mark at @value. 
diff --git a/gtk/gtkscalebutton.c b/gtk/gtkscalebutton.c
index b1c7a905f7..7259622001 100644
--- a/gtk/gtkscalebutton.c
+++ b/gtk/gtkscalebutton.c
@@ -546,7 +546,7 @@ gtk_scale_button_dispose (GObject *object)
  * @max: the maximum value of the scale (usually 100)
  * @step: the stepping of value when a scroll-wheel event,
  *        or up/down arrow event occurs (usually 2)
- * @icons: a %NULL-terminated array of icon names, or %NULL if
+ * @icons: (allow-none): a %NULL-terminated array of icon names, or %NULL if
  *         you want to set the list later with gtk_scale_button_set_icons()
  *
  * Creates a #GtkScaleButton, with a range between @min and @max, with
diff --git a/gtk/gtkscrollbar.c b/gtk/gtkscrollbar.c
index 5c0864d027..634b33791f 100644
--- a/gtk/gtkscrollbar.c
+++ b/gtk/gtkscrollbar.c
@@ -129,7 +129,7 @@ gtk_scrollbar_style_set (GtkWidget *widget,
 /**
  * gtk_scrollbar_new:
  * @orientation: the scrollbar's orientation.
- * @adjustment: the #GtkAdjustment to use, or %NULL to create a new adjustment.
+ * @adjustment: (allow-none): the #GtkAdjustment to use, or %NULL to create a new adjustment.
  *
  * Creates a new scrollbar with the given orientation.
  *
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 1c350ee7da..cfec07df8e 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -738,7 +738,7 @@ gtk_selection_owner_set_for_display (GdkDisplay   *display,
 
 /**
  * gtk_selection_owner_set:
- * @widget:  a #GtkWidget, or %NULL.
+ * @widget: (allow-none):  a #GtkWidget, or %NULL.
  * @selection:  an interned atom representing the selection to claim
  * @time_: timestamp with which to claim the selection
  * 
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index a9bcd0de68..b2b56918a2 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -31,7 +31,7 @@
 
 /**
  * gtk_show_uri:
- * @screen: screen to show the uri on or %NULL for the default screen
+ * @screen: (allow-none): screen to show the uri on or %NULL for the default screen
  * @uri: the uri to show
  * @timestamp: a timestamp to prevent focus stealing.
  * @error: a #GError that is returned in case of errors
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index ebae4c0fca..8f4919495e 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -1849,8 +1849,8 @@ gtk_spin_button_set_increments (GtkSpinButton *spin_button,
 /**
  * gtk_spin_button_get_increments:
  * @spin_button: a #GtkSpinButton
- * @step: location to store step increment, or %NULL
- * @page: location to store page increment, or %NULL
+ * @step: (allow-none): location to store step increment, or %NULL
+ * @page: (allow-none): location to store page increment, or %NULL
  *
  * Gets the current step and page the increments used by @spin_button. See
  * gtk_spin_button_set_increments().
@@ -1901,8 +1901,8 @@ gtk_spin_button_set_range (GtkSpinButton *spin_button,
 /**
  * gtk_spin_button_get_range:
  * @spin_button: a #GtkSpinButton
- * @min: location to store minimum allowed value, or %NULL
- * @max: location to store maximum allowed value, or %NULL
+ * @min: (allow-none): location to store minimum allowed value, or %NULL
+ * @max: (allow-none): location to store maximum allowed value, or %NULL
  *
  * Gets the range allowed for @spin_button. See
  * gtk_spin_button_set_range().
diff --git a/gtk/gtkstatusicon.c b/gtk/gtkstatusicon.c
index 1fe57442e6..de97c84cbd 100644
--- a/gtk/gtkstatusicon.c
+++ b/gtk/gtkstatusicon.c
@@ -2791,7 +2791,7 @@ gtk_status_icon_get_tooltip_text (GtkStatusIcon *status_icon)
 /**
  * gtk_status_icon_set_tooltip_markup:
  * @status_icon: a #GtkStatusIcon
- * @markup: the contents of the tooltip for @status_icon, or %NULL
+ * @markup: (allow-none): the contents of the tooltip for @status_icon, or %NULL
  *
  * Sets @markup as the contents of the tooltip, which is marked up with
  *  the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index 3e5001be17..abd108e950 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -6740,10 +6740,10 @@ gtk_paint_resize_grip (GtkStyle           *style,
  * @style: a #GtkStyle
  * @window: a #GdkWindow
  * @state_type: a state
- * @area: clip rectangle, or %NULL if the
+ * @area: (allow-none): clip rectangle, or %NULL if the
  *        output should not be clipped
- * @widget: the widget (may be %NULL)
- * @detail: a style detail (may be %NULL)
+ * @widget: (allow-none): the widget (may be %NULL)
+ * @detail: (allow-none): a style detail (may be %NULL)
  * @step: the nth step, a value between 0 and #GtkSpinner:num-steps
  * @x: the x origin of the rectangle in which to draw the spinner
  * @y: the y origin of the rectangle in which to draw the spinner
@@ -6908,7 +6908,7 @@ gtk_style_get_font (GtkStyle *style)
 /**
  * gtk_style_set_font:
  * @style: a #GtkStyle.
- * @font: a #GdkFont, or %NULL to use the #GdkFont corresponding
+ * @font: (allow-none): a #GdkFont, or %NULL to use the #GdkFont corresponding
  *   to style->font_desc.
  * 
  * Sets the #GdkFont to use for a given style. This is
diff --git a/gtk/gtktestutils.c b/gtk/gtktestutils.c
index 64bf351976..a60cdcf651 100644
--- a/gtk/gtktestutils.c
+++ b/gtk/gtktestutils.c
@@ -484,7 +484,7 @@ gtk_test_text_get (GtkWidget *widget)
 /**
  * gtk_test_create_widget
  * @widget_type: a valid widget type.
- * @first_property_name: Name of first property to set or %NULL
+ * @first_property_name: (allow-none): Name of first property to set or %NULL
  * @Varargs: value to set the first property to, followed by more
  *    name-value pairs, terminated by %NULL
  *
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index e223d92527..97abf9a26d 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -735,7 +735,7 @@ gtk_text_buffer_notify (GObject    *object,
 
 /**
  * gtk_text_buffer_new:
- * @table: a tag table, or %NULL to create a new one
+ * @table: (allow-none): a tag table, or %NULL to create a new one
  *
  * Creates a new text buffer.
  *
@@ -2429,8 +2429,8 @@ gtk_text_buffer_select_range (GtkTextBuffer     *buffer,
 /**
  * gtk_text_buffer_create_tag:
  * @buffer: a #GtkTextBuffer
- * @tag_name: name of the new tag, or %NULL
- * @first_property_name: name of first property to set, or %NULL
+ * @tag_name: (allow-none): name of the new tag, or %NULL
+ * @first_property_name: (allow-none): name of first property to set, or %NULL
  * @Varargs: %NULL-terminated list of property names and values
  *
  *
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 360c855a3e..aa5fbc442d 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -1175,7 +1175,7 @@ gtk_text_iter_begins_tag    (const GtkTextIter  *iter,
 /**
  * gtk_text_iter_ends_tag:
  * @iter: an iterator
- * @tag: a #GtkTextTag, or %NULL
+ * @tag: (allow-none): a #GtkTextTag, or %NULL
  *
  * Returns %TRUE if @tag is toggled off at exactly this point. If @tag
  * is %NULL, returns %TRUE if any tag is toggled off at this point. Note
@@ -4308,7 +4308,7 @@ matches_pred (GtkTextIter *iter,
  * @iter: a #GtkTextIter
  * @pred: a function to be called on each character
  * @user_data: user data for @pred
- * @limit: search limit, or %NULL for none 
+ * @limit: (allow-none): search limit, or %NULL for none 
  * 
  * Advances @iter, calling @pred on each character. If
  * @pred returns %TRUE, returns %TRUE and stops scanning.
@@ -4346,7 +4346,7 @@ gtk_text_iter_forward_find_char (GtkTextIter         *iter,
  * @iter: a #GtkTextIter
  * @pred: function to be called on each character
  * @user_data: user data for @pred
- * @limit: search limit, or %NULL for none
+ * @limit: (allow-none): search limit, or %NULL for none
  * 
  * Same as gtk_text_iter_forward_find_char(), but goes backward from @iter.
  * 
diff --git a/gtk/gtktextlayout.c b/gtk/gtktextlayout.c
index c4c7143984..31139d739e 100644
--- a/gtk/gtktextlayout.c
+++ b/gtk/gtktextlayout.c
@@ -2710,8 +2710,8 @@ void gtk_text_layout_get_iter_at_position (GtkTextLayout     *layout,
  * gtk_text_layout_get_cursor_locations:
  * @layout: a #GtkTextLayout
  * @iter: a #GtkTextIter
- * @strong_pos: location to store the strong cursor position (may be %NULL)
- * @weak_pos: location to store the weak cursor position (may be %NULL)
+ * @strong_pos: (allow-none): location to store the strong cursor position (may be %NULL)
+ * @weak_pos: (allow-none): location to store the weak cursor position (may be %NULL)
  *
  * Given an iterator within a text layout, determine the positions of the
  * strong and weak cursors if the insertion point is at that
diff --git a/gtk/gtktextmark.c b/gtk/gtktextmark.c
index 5964108a57..e6d5997209 100644
--- a/gtk/gtktextmark.c
+++ b/gtk/gtktextmark.c
@@ -188,7 +188,7 @@ gtk_text_mark_get_property (GObject    *object,
 
 /**
  * gtk_text_mark_new:
- * @name: mark name or %NULL
+ * @name: (allow-none): mark name or %NULL
  * @left_gravity: whether the mark should have left gravity
  *
  * Creates a text mark. Add it to a buffer using gtk_text_buffer_add_mark().
diff --git a/gtk/gtktexttag.c b/gtk/gtktexttag.c
index 98eea1d479..56af5a4e4e 100644
--- a/gtk/gtktexttag.c
+++ b/gtk/gtktexttag.c
@@ -707,7 +707,7 @@ gtk_text_tag_init (GtkTextTag *text_tag)
 
 /**
  * gtk_text_tag_new:
- * @name: tag name, or %NULL
+ * @name: (allow-none): tag name, or %NULL
  * 
  * Creates a #GtkTextTag. Configure the tag using object arguments,
  * i.e. using g_object_set().
diff --git a/gtk/gtktoggleaction.c b/gtk/gtktoggleaction.c
index 42217fc920..6e464d72e9 100644
--- a/gtk/gtktoggleaction.c
+++ b/gtk/gtktoggleaction.c
@@ -144,8 +144,8 @@ gtk_toggle_action_init (GtkToggleAction *action)
 /**
  * gtk_toggle_action_new:
  * @name: A unique name for the action
- * @label: The label displayed in menu items and on buttons, or %NULL
- * @tooltip: A tooltip for the action, or %NULL
+ * @label: (allow-none): The label displayed in menu items and on buttons, or %NULL
+ * @tooltip: (allow-none): A tooltip for the action, or %NULL
  * @stock_id: The stock icon to display in widgets representing the
  *   action, or %NULL
  *
diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index f383ff539f..87e875486f 100644
--- a/gtk/gtktoolbar.c
+++ b/gtk/gtktoolbar.c
@@ -3595,7 +3595,7 @@ gtk_toolbar_insert_widget (GtkToolbar *toolbar,
  * gtk_toolbar_append_element:
  * @toolbar: a #GtkToolbar.
  * @type: a value of type #GtkToolbarChildType that determines what @widget will be.
- * @widget: a #GtkWidget, or %NULL.
+ * @widget: (allow-none): a #GtkWidget, or %NULL.
  * @text: the element's label.
  * @tooltip_text: the element's tooltip.
  * @tooltip_private_text: used for context-sensitive help about this toolbar element.
@@ -3638,7 +3638,7 @@ gtk_toolbar_append_element (GtkToolbar          *toolbar,
  * gtk_toolbar_prepend_element:
  * @toolbar: a #GtkToolbar.
  * @type: a value of type #GtkToolbarChildType that determines what @widget will be.
- * @widget: a #GtkWidget, or %NULL
+ * @widget: (allow-none): a #GtkWidget, or %NULL
  * @text: the element's label.
  * @tooltip_text: the element's tooltip.
  * @tooltip_private_text: used for context-sensitive help about this toolbar element.
@@ -3681,7 +3681,7 @@ gtk_toolbar_prepend_element (GtkToolbar          *toolbar,
  * @toolbar: a #GtkToolbar.
  * @type: a value of type #GtkToolbarChildType that determines what @widget
  *   will be.
- * @widget: a #GtkWidget, or %NULL. 
+ * @widget: (allow-none): a #GtkWidget, or %NULL. 
  * @text: the element's label.
  * @tooltip_text: the element's tooltip.
  * @tooltip_private_text: used for context-sensitive help about this toolbar element.
diff --git a/gtk/gtktooltip.c b/gtk/gtktooltip.c
index c4700fd48f..36a99955e5 100644
--- a/gtk/gtktooltip.c
+++ b/gtk/gtktooltip.c
@@ -205,7 +205,7 @@ gtk_tooltip_dispose (GObject *object)
 /**
  * gtk_tooltip_set_markup:
  * @tooltip: a #GtkTooltip
- * @markup: a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) or %NULL
+ * @markup: (allow-none): a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) or %NULL
  *
  * Sets the text of the tooltip to be @markup, which is marked up
  * with the <link
@@ -231,7 +231,7 @@ gtk_tooltip_set_markup (GtkTooltip  *tooltip,
 /**
  * gtk_tooltip_set_text:
  * @tooltip: a #GtkTooltip
- * @text: a text string or %NULL
+ * @text: (allow-none): a text string or %NULL
  *
  * Sets the text of the tooltip to be @text. If @text is %NULL, the label
  * will be hidden. See also gtk_tooltip_set_markup().
@@ -255,7 +255,7 @@ gtk_tooltip_set_text (GtkTooltip  *tooltip,
 /**
  * gtk_tooltip_set_icon:
  * @tooltip: a #GtkTooltip
- * @pixbuf: a #GdkPixbuf, or %NULL
+ * @pixbuf: (allow-none): a #GdkPixbuf, or %NULL
  *
  * Sets the icon of the tooltip (which is in front of the text) to be
  * @pixbuf.  If @pixbuf is %NULL, the image will be hidden.
@@ -281,7 +281,7 @@ gtk_tooltip_set_icon (GtkTooltip *tooltip,
 /**
  * gtk_tooltip_set_icon_from_stock:
  * @tooltip: a #GtkTooltip
- * @stock_id: a stock id, or %NULL
+ * @stock_id: (allow-none): a stock id, or %NULL
  * @size: (type int): a stock icon size
  *
  * Sets the icon of the tooltip (which is in front of the text) to be
@@ -308,7 +308,7 @@ gtk_tooltip_set_icon_from_stock (GtkTooltip  *tooltip,
 /**
  * gtk_tooltip_set_icon_from_icon_name:
  * @tooltip: a #GtkTooltip
- * @icon_name: an icon name, or %NULL
+ * @icon_name: (allow-none): an icon name, or %NULL
  * @size: (type int): a stock icon size
  *
  * Sets the icon of the tooltip (which is in front of the text) to be
@@ -335,7 +335,7 @@ gtk_tooltip_set_icon_from_icon_name (GtkTooltip  *tooltip,
 /**
  * gtk_tooltip_set_icon_from_gicon:
  * @tooltip: a #GtkTooltip
- * @gicon: a #GIcon representing the icon, or %NULL
+ * @gicon: (allow-none): a #GIcon representing the icon, or %NULL
  * @size: (type int): a stock icon size
  *
  * Sets the icon of the tooltip (which is in front of the text)
@@ -362,7 +362,7 @@ gtk_tooltip_set_icon_from_gicon (GtkTooltip  *tooltip,
 /**
  * gtk_tooltip_set_custom:
  * @tooltip: a #GtkTooltip
- * @custom_widget: a #GtkWidget, or %NULL to unset the old custom widget.
+ * @custom_widget: (allow-none): a #GtkWidget, or %NULL to unset the old custom widget.
  *
  * Replaces the widget packed into the tooltip with
  * @custom_widget. @custom_widget does not get destroyed when the tooltip goes
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 5f01e6d791..5bdce35479 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -2034,7 +2034,7 @@ gtk_tree_row_reference_get_model (GtkTreeRowReference *reference)
 
 /**
  * gtk_tree_row_reference_valid:
- * @reference: A #GtkTreeRowReference, or %NULL
+ * @reference: (allow-none): A #GtkTreeRowReference, or %NULL
  * 
  * Returns %TRUE if the @reference is non-%NULL and refers to a current valid
  * path.
@@ -2071,7 +2071,7 @@ gtk_tree_row_reference_copy (GtkTreeRowReference *reference)
 
 /**
  * gtk_tree_row_reference_free:
- * @reference: A #GtkTreeRowReference, or %NULL
+ * @reference: (allow-none): A #GtkTreeRowReference, or %NULL
  * 
  * Free's @reference. @reference may be %NULL.
  **/
diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index a161f47943..139f68eff9 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -3011,8 +3011,8 @@ gtk_tree_model_filter_get_model (GtkTreeModelFilter *filter)
  * gtk_tree_model_filter_set_visible_func:
  * @filter: A #GtkTreeModelFilter.
  * @func: A #GtkTreeModelFilterVisibleFunc, the visible function.
- * @data: User data to pass to the visible function, or %NULL.
- * @destroy: Destroy notifier of @data, or %NULL.
+ * @data: (allow-none): User data to pass to the visible function, or %NULL.
+ * @destroy: (allow-none): Destroy notifier of @data, or %NULL.
  *
  * Sets the visible function used when filtering the @filter to be @func. The
  * function should return %TRUE if the given row should be visible and
@@ -3071,8 +3071,8 @@ gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter            *filter,
  * @n_columns: The number of columns in the filter model.
  * @types: The #GType<!-- -->s of the columns.
  * @func: A #GtkTreeModelFilterModifyFunc
- * @data: User data to pass to the modify function, or %NULL.
- * @destroy: Destroy notifier of @data, or %NULL.
+ * @data: (allow-none): User data to pass to the modify function, or %NULL.
+ * @destroy: (allow-none): Destroy notifier of @data, or %NULL.
  *
  * With the @n_columns and @types parameters, you give an array of column
  * types for this model (which will be exposed to the parent model/view).
diff --git a/gtk/gtktreemodelsort.c b/gtk/gtktreemodelsort.c
index f07795cc23..3cad0ec55f 100644
--- a/gtk/gtktreemodelsort.c
+++ b/gtk/gtktreemodelsort.c
@@ -1904,7 +1904,7 @@ gtk_tree_model_sort_elt_get_path (SortLevel *level,
 /**
  * gtk_tree_model_sort_set_model:
  * @tree_model_sort: The #GtkTreeModelSort.
- * @child_model: A #GtkTreeModel, or %NULL.
+ * @child_model: (allow-none): A #GtkTreeModel, or %NULL.
  *
  * Sets the model of @tree_model_sort to be @model.  If @model is %NULL, 
  * then the old model is unset.  The sort function is unset as a result 
diff --git a/gtk/gtktreesortable.c b/gtk/gtktreesortable.c
index d6cd4e2d1e..b98b8eeb77 100644
--- a/gtk/gtktreesortable.c
+++ b/gtk/gtktreesortable.c
@@ -170,8 +170,8 @@ gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,
  * @sortable: A #GtkTreeSortable
  * @sort_column_id: the sort column id to set the function for
  * @sort_func: The comparison function
- * @user_data: User data to pass to @sort_func, or %NULL
- * @destroy: Destroy notifier of @user_data, or %NULL
+ * @user_data: (allow-none): User data to pass to @sort_func, or %NULL
+ * @destroy: (allow-none): Destroy notifier of @user_data, or %NULL
  * 
  * Sets the comparison function used when sorting to be @sort_func. If the
  * current sort column id of @sortable is the same as @sort_column_id, then 
@@ -202,8 +202,8 @@ gtk_tree_sortable_set_sort_func (GtkTreeSortable        *sortable,
  * gtk_tree_sortable_set_default_sort_func:
  * @sortable: A #GtkTreeSortable
  * @sort_func: The comparison function
- * @user_data: User data to pass to @sort_func, or %NULL
- * @destroy: Destroy notifier of @user_data, or %NULL
+ * @user_data: (allow-none): User data to pass to @sort_func, or %NULL
+ * @destroy: (allow-none): Destroy notifier of @user_data, or %NULL
  * 
  * Sets the default comparison function used when sorting to be @sort_func.  
  * If the current sort column id of @sortable is
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index 026ee39e1c..ea5a75fd7f 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -1158,7 +1158,7 @@ gtk_tree_store_remove (GtkTreeStore *tree_store,
  * gtk_tree_store_insert:
  * @tree_store: A #GtkTreeStore
  * @iter: An unset #GtkTreeIter to set to the new row
- * @parent: A valid #GtkTreeIter, or %NULL
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
  * @position: position to insert the new row
  *
  * Creates a new row at @position.  If parent is non-%NULL, then the row will be
@@ -1219,8 +1219,8 @@ gtk_tree_store_insert (GtkTreeStore *tree_store,
  * gtk_tree_store_insert_before:
  * @tree_store: A #GtkTreeStore
  * @iter: An unset #GtkTreeIter to set to the new row
- * @parent: A valid #GtkTreeIter, or %NULL
- * @sibling: A valid #GtkTreeIter, or %NULL
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
+ * @sibling: (allow-none): A valid #GtkTreeIter, or %NULL
  *
  * Inserts a new row before @sibling.  If @sibling is %NULL, then the row will
  * be appended to @parent 's children.  If @parent and @sibling are %NULL, then
@@ -1299,8 +1299,8 @@ gtk_tree_store_insert_before (GtkTreeStore *tree_store,
  * gtk_tree_store_insert_after:
  * @tree_store: A #GtkTreeStore
  * @iter: An unset #GtkTreeIter to set to the new row
- * @parent: A valid #GtkTreeIter, or %NULL
- * @sibling: A valid #GtkTreeIter, or %NULL
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
+ * @sibling: (allow-none): A valid #GtkTreeIter, or %NULL
  *
  * Inserts a new row after @sibling.  If @sibling is %NULL, then the row will be
  * prepended to @parent 's children.  If @parent and @sibling are %NULL, then
@@ -1379,8 +1379,8 @@ gtk_tree_store_insert_after (GtkTreeStore *tree_store,
 /**
  * gtk_tree_store_insert_with_values:
  * @tree_store: A #GtkTreeStore
- * @iter: An unset #GtkTreeIter to set the new row, or %NULL.
- * @parent: A valid #GtkTreeIter, or %NULL
+ * @iter: (allow-none): An unset #GtkTreeIter to set the new row, or %NULL.
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
  * @position: position to insert the new row
  * @Varargs: pairs of column number and value, terminated with -1
  *
@@ -1470,8 +1470,8 @@ gtk_tree_store_insert_with_values (GtkTreeStore *tree_store,
 /**
  * gtk_tree_store_insert_with_valuesv:
  * @tree_store: A #GtkTreeStore
- * @iter: An unset #GtkTreeIter to set the new row, or %NULL.
- * @parent: A valid #GtkTreeIter, or %NULL
+ * @iter: (allow-none): An unset #GtkTreeIter to set the new row, or %NULL.
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
  * @position: position to insert the new row
  * @columns: an array of column numbers
  * @values: an array of GValues
@@ -1548,7 +1548,7 @@ gtk_tree_store_insert_with_valuesv (GtkTreeStore *tree_store,
  * gtk_tree_store_prepend:
  * @tree_store: A #GtkTreeStore
  * @iter: An unset #GtkTreeIter to set to the prepended row
- * @parent: A valid #GtkTreeIter, or %NULL
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
  * 
  * Prepends a new row to @tree_store.  If @parent is non-%NULL, then it will prepend
  * the new row before the first child of @parent, otherwise it will prepend a row
@@ -1606,7 +1606,7 @@ gtk_tree_store_prepend (GtkTreeStore *tree_store,
  * gtk_tree_store_append:
  * @tree_store: A #GtkTreeStore
  * @iter: An unset #GtkTreeIter to set to the appended row
- * @parent: A valid #GtkTreeIter, or %NULL
+ * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
  * 
  * Appends a new row to @tree_store.  If @parent is non-%NULL, then it will append the
  * new row after the last child of @parent, otherwise it will append a row to
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index fe815d24d4..9e2e48ad63 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -10859,7 +10859,7 @@ gtk_tree_view_get_hadjustment (GtkTreeView *tree_view)
 /**
  * gtk_tree_view_set_hadjustment:
  * @tree_view: A #GtkTreeView
- * @adjustment: The #GtkAdjustment to set, or %NULL
+ * @adjustment: (allow-none): The #GtkAdjustment to set, or %NULL
  *
  * Sets the #GtkAdjustment for the current horizontal aspect.
  **/
@@ -10899,7 +10899,7 @@ gtk_tree_view_get_vadjustment (GtkTreeView *tree_view)
 /**
  * gtk_tree_view_set_vadjustment:
  * @tree_view: A #GtkTreeView
- * @adjustment: The #GtkAdjustment to set, or %NULL
+ * @adjustment: (allow-none): The #GtkAdjustment to set, or %NULL
  *
  * Sets the #GtkAdjustment for the current vertical aspect.
  **/
@@ -11541,9 +11541,9 @@ gtk_tree_view_get_expander_column (GtkTreeView *tree_view)
 /**
  * gtk_tree_view_set_column_drag_function:
  * @tree_view: A #GtkTreeView.
- * @func: A function to determine which columns are reorderable, or %NULL.
- * @user_data: User data to be passed to @func, or %NULL
- * @destroy: Destroy notifier for @user_data, or %NULL
+ * @func: (allow-none): A function to determine which columns are reorderable, or %NULL.
+ * @user_data: (allow-none): User data to be passed to @func, or %NULL
+ * @destroy: (allow-none): Destroy notifier for @user_data, or %NULL
  *
  * Sets a user function for determining where a column may be dropped when
  * dragged.  This function is called on every column pair in turn at the
@@ -12566,8 +12566,8 @@ gtk_tree_view_real_set_cursor (GtkTreeView     *tree_view,
 /**
  * gtk_tree_view_get_cursor:
  * @tree_view: A #GtkTreeView
- * @path: A pointer to be filled with the current cursor path, or %NULL
- * @focus_column: A pointer to be filled with the current focus column, or %NULL
+ * @path: (allow-none): A pointer to be filled with the current cursor path, or %NULL
+ * @focus_column: (allow-none): A pointer to be filled with the current focus column, or %NULL
  *
  * Fills in @path and @focus_column with the current path and focus column.  If
  * the cursor isn't currently set, then *@path will be %NULL.  If no column
@@ -12721,10 +12721,10 @@ gtk_tree_view_get_bin_window (GtkTreeView *tree_view)
  * @tree_view: A #GtkTreeView.
  * @x: The x position to be identified (relative to bin_window).
  * @y: The y position to be identified (relative to bin_window).
- * @path: A pointer to a #GtkTreePath pointer to be filled in, or %NULL
- * @column: A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL
- * @cell_x: A pointer where the X coordinate relative to the cell can be placed, or %NULL
- * @cell_y: A pointer where the Y coordinate relative to the cell can be placed, or %NULL
+ * @path: (allow-none): A pointer to a #GtkTreePath pointer to be filled in, or %NULL
+ * @column: (allow-none): A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL
+ * @cell_x: (allow-none): A pointer where the X coordinate relative to the cell can be placed, or %NULL
+ * @cell_y: (allow-none): A pointer where the Y coordinate relative to the cell can be placed, or %NULL
  *
  * Finds the path at the point (@x, @y), relative to bin_window coordinates
  * (please see gtk_tree_view_get_bin_window()).
@@ -12938,8 +12938,8 @@ gtk_tree_view_get_cell_area (GtkTreeView        *tree_view,
 /**
  * gtk_tree_view_get_background_area:
  * @tree_view: a #GtkTreeView
- * @path: a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
- * @column: a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordiantes
+ * @path: (allow-none): a #GtkTreePath for the row, or %NULL to get only horizontal coordinates
+ * @column: (allow-none): a #GtkTreeViewColumn for the column, or %NULL to get only vertical coordiantes
  * @rect: rectangle to fill with cell background rect
  *
  * Fills the bounding rectangle in bin_window coordinates for the cell at the
@@ -13269,8 +13269,8 @@ gtk_tree_view_convert_bin_window_to_tree_coords (GtkTreeView *tree_view,
 /**
  * gtk_tree_view_get_visible_range:
  * @tree_view: A #GtkTreeView
- * @start_path: Return location for start of region, or %NULL.
- * @end_path: Return location for end of region, or %NULL.
+ * @start_path: (allow-none): Return location for start of region, or %NULL.
+ * @end_path: (allow-none): Return location for end of region, or %NULL.
  *
  * Sets @start_path and @end_path to be the first and last visible path.
  * Note that there may be invisible paths in between.
@@ -13475,7 +13475,7 @@ gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view)
 /**
  * gtk_tree_view_set_drag_dest_row:
  * @tree_view: a #GtkTreeView
- * @path: The path of the row to highlight, or %NULL.
+ * @path: (allow-none): The path of the row to highlight, or %NULL.
  * @pos: Specifies whether to drop before, after or into the row
  * 
  * Sets the row that is highlighted for feedback.
@@ -13553,8 +13553,8 @@ gtk_tree_view_set_drag_dest_row (GtkTreeView            *tree_view,
 /**
  * gtk_tree_view_get_drag_dest_row:
  * @tree_view: a #GtkTreeView
- * @path: Return location for the path of the highlighted row, or %NULL.
- * @pos: Return location for the drop position, or %NULL
+ * @path: (allow-none): Return location for the path of the highlighted row, or %NULL.
+ * @pos: (allow-none): Return location for the drop position, or %NULL
  * 
  * Gets information about the row that is highlighted for feedback.
  **/
@@ -13587,8 +13587,8 @@ gtk_tree_view_get_drag_dest_row (GtkTreeView              *tree_view,
  * @tree_view: a #GtkTreeView
  * @drag_x: the position to determine the destination row for
  * @drag_y: the position to determine the destination row for
- * @path: Return location for the path of the highlighted row, or %NULL.
- * @pos: Return location for the drop position, or %NULL
+ * @path: (allow-none): Return location for the path of the highlighted row, or %NULL.
+ * @pos: (allow-none): Return location for the drop position, or %NULL
  * 
  * Determines the destination row for a given position.  @drag_x and
  * @drag_y are expected to be in widget coordinates.  This function is only
@@ -13846,9 +13846,9 @@ gtk_tree_view_create_row_drag_icon (GtkTreeView  *tree_view,
 /**
  * gtk_tree_view_set_destroy_count_func:
  * @tree_view: A #GtkTreeView
- * @func: Function to be called when a view row is destroyed, or %NULL
- * @data: User data to be passed to @func, or %NULL
- * @destroy: Destroy notifier for @data, or %NULL
+ * @func: (allow-none): Function to be called when a view row is destroyed, or %NULL
+ * @data: (allow-none): User data to be passed to @func, or %NULL
+ * @destroy: (allow-none): Destroy notifier for @data, or %NULL
  *
  * This function should almost never be used.  It is meant for private use by
  * ATK for determining the number of visible children that are removed when the
@@ -13985,8 +13985,8 @@ gtk_tree_view_get_search_equal_func (GtkTreeView *tree_view)
  * gtk_tree_view_set_search_equal_func:
  * @tree_view: A #GtkTreeView
  * @search_equal_func: the compare function to use during the search
- * @search_user_data: user data to pass to @search_equal_func, or %NULL
- * @search_destroy: Destroy notifier for @search_user_data, or %NULL
+ * @search_user_data: (allow-none): user data to pass to @search_equal_func, or %NULL
+ * @search_destroy: (allow-none): Destroy notifier for @search_user_data, or %NULL
  *
  * Sets the compare function for the interactive search capabilities; note
  * that somewhat like strcmp() returning 0 for equality
@@ -14104,10 +14104,10 @@ gtk_tree_view_set_search_entry (GtkTreeView *tree_view,
 /**
  * gtk_tree_view_set_search_position_func:
  * @tree_view: A #GtkTreeView
- * @func: the function to use to position the search dialog, or %NULL
+ * @func: (allow-none): the function to use to position the search dialog, or %NULL
  *    to use the default search position function
- * @data: user data to pass to @func, or %NULL
- * @destroy: Destroy notifier for @data, or %NULL
+ * @data: (allow-none): user data to pass to @func, or %NULL
+ * @destroy: (allow-none): Destroy notifier for @data, or %NULL
  *
  * Sets the function to use when positioning the search dialog.
  *
@@ -15049,8 +15049,8 @@ gtk_tree_view_get_row_separator_func (GtkTreeView *tree_view)
  * gtk_tree_view_set_row_separator_func:
  * @tree_view: a #GtkTreeView
  * @func: a #GtkTreeViewRowSeparatorFunc
- * @data: user data to pass to @func, or %NULL
- * @destroy: destroy notifier for @data, or %NULL
+ * @data: (allow-none): user data to pass to @func, or %NULL
+ * @destroy: (allow-none): destroy notifier for @data, or %NULL
  * 
  * Sets the row separator function, which is used to determine
  * whether a row should be drawn as a separator. If the row separator
@@ -15405,9 +15405,9 @@ gtk_tree_view_set_tooltip_row (GtkTreeView *tree_view,
  * gtk_tree_view_set_tooltip_cell:
  * @tree_view: a #GtkTreeView
  * @tooltip: a #GtkTooltip
- * @path: a #GtkTreePath or %NULL
- * @column: a #GtkTreeViewColumn or %NULL
- * @cell: a #GtkCellRenderer or %NULL
+ * @path: (allow-none): a #GtkTreePath or %NULL
+ * @column: (allow-none): a #GtkTreeViewColumn or %NULL
+ * @cell: (allow-none): a #GtkCellRenderer or %NULL
  *
  * Sets the tip area of @tooltip to the area @path, @column and @cell have
  * in common.  For example if @path is %NULL and @column is set, the tip
@@ -15500,9 +15500,9 @@ gtk_tree_view_set_tooltip_cell (GtkTreeView       *tree_view,
  * @x: the x coordinate (relative to widget coordinates)
  * @y: the y coordinate (relative to widget coordinates)
  * @keyboard_tip: whether this is a keyboard tooltip or not
- * @model: a pointer to receive a #GtkTreeModel or %NULL
- * @path: a pointer to receive a #GtkTreePath or %NULL
- * @iter: a pointer to receive a #GtkTreeIter or %NULL
+ * @model: (allow-none): a pointer to receive a #GtkTreeModel or %NULL
+ * @path: (allow-none): a pointer to receive a #GtkTreePath or %NULL
+ * @iter: (allow-none): a pointer to receive a #GtkTreeIter or %NULL
  *
  * This function is supposed to be used in a #GtkWidget::query-tooltip
  * signal handler for #GtkTreeView.  The @x, @y and @keyboard_tip values
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index 41a23c3086..396c816e86 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -2598,11 +2598,11 @@ gtk_tree_view_column_cell_set_cell_data (GtkTreeViewColumn *tree_column,
 /**
  * gtk_tree_view_column_cell_get_size:
  * @tree_column: A #GtkTreeViewColumn.
- * @cell_area: The area a cell in the column will be allocated, or %NULL
- * @x_offset: location to return x offset of a cell relative to @cell_area, or %NULL
- * @y_offset: location to return y offset of a cell relative to @cell_area, or %NULL
- * @width: location to return width needed to render a cell, or %NULL
- * @height: location to return height needed to render a cell, or %NULL
+ * @cell_area: (allow-none): The area a cell in the column will be allocated, or %NULL
+ * @x_offset: (allow-none): location to return x offset of a cell relative to @cell_area, or %NULL
+ * @y_offset: (allow-none): location to return y offset of a cell relative to @cell_area, or %NULL
+ * @width: (allow-none): location to return width needed to render a cell, or %NULL
+ * @height: (allow-none): location to return height needed to render a cell, or %NULL
  * 
  * Obtains the width and height needed to render the column.  This is used
  * primarily by the #GtkTreeView.
diff --git a/gtk/gtkuimanager.c b/gtk/gtkuimanager.c
index 6112bf799f..c5c7794a95 100644
--- a/gtk/gtkuimanager.c
+++ b/gtk/gtkuimanager.c
@@ -2107,7 +2107,7 @@ find_toolbar_position (GNode      *node,
 
 /**
  * _gtk_menu_is_empty:
- * @menu: a #GtkMenu or %NULL
+ * @menu: (allow-none): a #GtkMenu or %NULL
  * 
  * Determines whether @menu is empty. A menu is considered empty if it
  * the only visible children are tearoff menu items or "filler" menu 
diff --git a/gtk/gtkvscrollbar.c b/gtk/gtkvscrollbar.c
index a5f34e1695..3287e09263 100644
--- a/gtk/gtkvscrollbar.c
+++ b/gtk/gtkvscrollbar.c
@@ -49,7 +49,7 @@ gtk_vscrollbar_init (GtkVScrollbar *vscrollbar)
 
 /**
  * gtk_vscrollbar_new:
- * @adjustment: the #GtkAdjustment to use, or %NULL to create a new adjustment
+ * @adjustment: (allow-none): the #GtkAdjustment to use, or %NULL to create a new adjustment
  *
  * Creates a new vertical scrollbar.
  *
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 4adba85299..027e5b8fa8 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -905,7 +905,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::parent-set:
    * @widget: the object on which the signal is emitted
-   * @old_parent: the previous parent, or %NULL if the widget 
+   * @old_parent: (allow-none): the previous parent, or %NULL if the widget
    *   just got its initial parent.
    *
    * The ::parent-set signal is emitted when a new parent 
@@ -924,7 +924,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::hierarchy-changed:
    * @widget: the object on which the signal is emitted
-   * @previous_toplevel: the previous toplevel ancestor, or %NULL
+   * @previous_toplevel: (allow-none): the previous toplevel ancestor, or %NULL
    *   if the widget was previously unanchored
    *
    * The ::hierarchy-changed signal is emitted when the
@@ -946,7 +946,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::style-set:
    * @widget: the object on which the signal is emitted
-   * @previous_style: the previous style, or %NULL if the widget 
+   * @previous_style: (allow-none): the previous style, or %NULL if the widget
    *   just got its initial style 
    *
    * The ::style-set signal is emitted when a new style has been set 
@@ -2337,7 +2337,7 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::screen-changed:
    * @widget: the object on which the signal is emitted
-   * @previous_screen: the previous screen, or %NULL if the
+   * @previous_screen: (allow-none): the previous screen, or %NULL if the
    *   widget was not associated with a screen before
    *
    * The ::screen-changed signal gets emitted when the
@@ -7949,8 +7949,8 @@ gtk_widget_set_size_request (GtkWidget *widget,
 /**
  * gtk_widget_get_size_request:
  * @widget: a #GtkWidget
- * @width: (out): return location for width, or %NULL
- * @height: (out): return location for height, or %NULL
+ * @width: (allow-none): (out): return location for width, or %NULL
+ * @height: (allow-none): (out): return location for height, or %NULL
  *
  * Gets the size request that was explicitly set for the widget using
  * gtk_widget_set_size_request(). A value of -1 stored in @width or
@@ -9290,7 +9290,7 @@ gtk_widget_shape_info_destroy (GtkWidgetShapeInfo *info)
 /**
  * gtk_widget_shape_combine_mask: 
  * @widget: a #GtkWidget
- * @shape_mask: shape to be added, or %NULL to remove an existing shape
+ * @shape_mask: (allow-none): shape to be added, or %NULL to remove an existing shape
  * @offset_x: X position of shape mask with respect to @window
  * @offset_y: Y position of shape mask with respect to @window
  * 
@@ -9514,7 +9514,7 @@ expose_window (GdkWindow *window)
 /**
  * gtk_widget_get_snapshot:
  * @widget:    a #GtkWidget
- * @clip_rect: a #GdkRectangle or %NULL
+ * @clip_rect: (allow-none): a #GdkRectangle or %NULL
  *
  * Create a #GdkPixmap of the contents of the widget and its children.
  *
@@ -9745,7 +9745,7 @@ gtk_widget_class_install_style_property (GtkWidgetClass *klass,
  * gtk_widget_class_find_style_property:
  * @klass: a #GtkWidgetClass
  * @property_name: the name of the style property to find
- * @returns: the #GParamSpec of the style property or %NULL if @class has no
+ * @returns: (allow-none): the #GParamSpec of the style property or %NULL if @class has no
  *   style property with that name.
  *
  * Finds a style property of a widget class by name.
@@ -10917,7 +10917,7 @@ gtk_widget_real_set_has_tooltip (GtkWidget *widget,
 /**
  * gtk_widget_set_tooltip_window:
  * @widget: a #GtkWidget
- * @custom_window: a #GtkWindow, or %NULL
+ * @custom_window: (allow-none): a #GtkWindow, or %NULL
  *
  * Replaces the default, usually yellow, window used for displaying
  * tooltips with @custom_window. GTK+ will take care of showing and
@@ -11069,7 +11069,7 @@ gtk_widget_get_tooltip_text (GtkWidget *widget)
 /**
  * gtk_widget_set_tooltip_markup:
  * @widget: a #GtkWidget
- * @markup: the contents of the tooltip for @widget, or %NULL
+ * @markup: (allow-none): the contents of the tooltip for @widget, or %NULL
  *
  * Sets @markup as the contents of the tooltip, which is marked up with
  *  the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 106c93fad1..31b3889750 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -3627,7 +3627,7 @@ load_pixbuf_verbosely (const char *filename,
  * gtk_window_set_icon_from_file:
  * @window: a #GtkWindow
  * @filename: location of icon file
- * @err: location to store error, or %NULL.
+ * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets the icon for @window.  
  * Warns on failure if @err is %NULL.
@@ -3805,7 +3805,7 @@ gtk_window_get_default_icon_name (void)
 /**
  * gtk_window_set_default_icon_from_file:
  * @filename: location of icon file
- * @err: location to store error, or %NULL.
+ * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets an icon to be used as fallback for windows that haven't
  * had gtk_window_set_icon_list() called on them from a file
@@ -3948,8 +3948,8 @@ gtk_window_set_default_size (GtkWindow   *window,
 /**
  * gtk_window_get_default_size:
  * @window: a #GtkWindow
- * @width: location to store the default width, or %NULL
- * @height: location to store the default height, or %NULL
+ * @width: (allow-none): location to store the default width, or %NULL
+ * @height: (allow-none): location to store the default height, or %NULL
  *
  * Gets the default size of the window. A value of -1 for the width or
  * height indicates that a default size has not been explicitly set
@@ -4016,8 +4016,8 @@ gtk_window_resize (GtkWindow *window,
 /**
  * gtk_window_get_size:
  * @window: a #GtkWindow
- * @width: (out): return location for width, or %NULL
- * @height: (out): return location for height, or %NULL
+ * @width: (allow-none): (out): return location for width, or %NULL
+ * @height: (allow-none): (out): return location for height, or %NULL
  *
  * Obtains the current size of @window. If @window is not onscreen,
  * it returns the size GTK+ will suggest to the <link
@@ -7351,10 +7351,10 @@ gtk_window_begin_resize_drag  (GtkWindow    *window,
 /**
  * gtk_window_get_frame_dimensions:
  * @window: a #GtkWindow
- * @left: location to store the width of the frame at the left, or %NULL
- * @top: location to store the height of the frame at the top, or %NULL
- * @right: location to store the width of the frame at the returns, or %NULL
- * @bottom: location to store the height of the frame at the bottom, or %NULL
+ * @left: (allow-none): location to store the width of the frame at the left, or %NULL
+ * @top: (allow-none): location to store the height of the frame at the top, or %NULL
+ * @right: (allow-none): location to store the width of the frame at the returns, or %NULL
+ * @bottom: (allow-none): location to store the height of the frame at the bottom, or %NULL
  *
  * (Note: this is a special-purpose function intended for the
  *  framebuffer port; see gtk_window_set_has_frame(). It will not
@@ -7723,7 +7723,7 @@ gtk_window_group_list_windows (GtkWindowGroup *window_group)
 
 /**
  * gtk_window_get_group:
- * @window: a #GtkWindow, or %NULL
+ * @window: (allow-none): a #GtkWindow, or %NULL
  *
  * Returns the group for @window or the default group, if
  * @window is %NULL or if @window does not have an explicit
diff --git a/gtk/gtkxembed.c b/gtk/gtkxembed.c
index 37462f91c1..f88c8948e0 100644
--- a/gtk/gtkxembed.c
+++ b/gtk/gtkxembed.c
@@ -123,7 +123,7 @@ gtk_xembed_get_time (void)
 
 /**
  * _gtk_xembed_send_message:
- * @recipient: window to which to send the window, or %NULL
+ * @recipient: (allow-none): window to which to send the window, or %NULL
  *             in which case nothing will be sent
  * @message:   type of message
  * @detail:    detail field of message
@@ -172,7 +172,7 @@ _gtk_xembed_send_message (GdkWindow        *recipient,
 
 /**
  * _gtk_xembed_send_focus_message:
- * @recipient: window to which to send the window, or %NULL
+ * @recipient: (allow-none): window to which to send the window, or %NULL
  *             in which case nothing will be sent
  * @message:   type of message
  * @detail:    detail field of message