diff --git a/gio/gaction.c b/gio/gaction.c
index 966cdde7d..85717fa0b 100644
--- a/gio/gaction.c
+++ b/gio/gaction.c
@@ -328,7 +328,7 @@ g_action_get_state_type (GAction *action)
  * The return value (if non-%NULL) should be freed with
  * g_variant_unref() when it is no longer required.
  *
- * Returns: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
  *
  * Since: 2.28
  **/
diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c
index 212df73fb..c608a4a99 100644
--- a/gio/gactiongroup.c
+++ b/gio/gactiongroup.c
@@ -389,7 +389,7 @@ g_action_group_has_action (GActionGroup *action_group,
  * possible for an action to be removed and for a new action to be added
  * with the same name but a different parameter type.
  *
- * Returns: the parameter type
+ * Returns: (nullable): the parameter type
  *
  * Since: 2.28
  **/
@@ -425,7 +425,8 @@ g_action_group_get_action_parameter_type (GActionGroup *action_group,
  * possible for an action to be removed and for a new action to be added
  * with the same name but a different state type.
  *
- * Returns: (transfer full): the state type, if the action is stateful
+ * Returns: (nullable) (transfer full): the state type, if the action
+ * is stateful
  *
  * Since: 2.28
  **/
@@ -463,7 +464,7 @@ g_action_group_get_action_state_type (GActionGroup *action_group,
  * The return value (if non-%NULL) should be freed with
  * g_variant_unref() when it is no longer required.
  *
- * Returns: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
  *
  * Since: 2.28
  **/
@@ -515,7 +516,7 @@ g_action_group_get_action_enabled (GActionGroup *action_group,
  * The return value (if non-%NULL) should be freed with
  * g_variant_unref() when it is no longer required.
  *
- * Returns: (allow-none): the current state of the action
+ * Returns: (nullable): the current state of the action
  *
  * Since: 2.28
  **/
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 8ad7a2faa..d5e508a86 100644
--- a/gio/gapplicationcommandline.c
+++ b/gio/gapplicationcommandline.c
@@ -780,7 +780,7 @@ g_application_command_line_get_exit_status (GApplicationCommandLine *cmdline)
  *
  * For local invocation, it will be %NULL.
  *
- * Returns: (allow-none): the platform data, or %NULL
+ * Returns: (nullable): the platform data, or %NULL
  *
  * Since: 2.28
  **/
diff --git a/gio/gcancellable.c b/gio/gcancellable.c
index e7c48c93e..fcfca3fc4 100644
--- a/gio/gcancellable.c
+++ b/gio/gcancellable.c
@@ -221,8 +221,8 @@ g_cancellable_pop_current (GCancellable *cancellable)
  *
  * Gets the top cancellable from the stack.
  *
- * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
- * if the stack is empty.
+ * Returns: (nullable) (transfer none): a #GCancellable from the top
+ * of the stack, or %NULL if the stack is empty.
  **/
 GCancellable *
 g_cancellable_get_current  (void)
diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c
index 7217f48b4..9586c31d9 100644
--- a/gio/gcontenttype.c
+++ b/gio/gcontenttype.c
@@ -382,7 +382,7 @@ g_content_type_get_description (const gchar *type)
  *
  * Gets the mime type for the content type, if one is registered.
  *
- * Returns: (allow-none): the registered mime type for the given @type,
+ * Returns: (nullable): the registered mime type for the given @type,
  *     or %NULL if unknown.
  */
 char *
@@ -569,8 +569,8 @@ looks_like_text (const guchar *data, gsize data_size)
  *
  * Tries to find a content type based on the mime type name.
  *
- * Returns: (allow-none): Newly allocated string with content type
- *     or %NULL. Free with g_free()
+ * Returns: (nullable): Newly allocated string with content type or
+ *     %NULL. Free with g_free()
  *
  * Since: 2.18
  **/
diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c
index 6ebb7f3ac..3753bd81b 100644
--- a/gio/gdatainputstream.c
+++ b/gio/gdatainputstream.c
@@ -735,12 +735,12 @@ scan_for_newline (GDataInputStream *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
- *  NUL terminated byte array with the line that was read in (without
- *  the newlines).  Set @length to a #gsize to get the length of the
- *  read line.  On an error, it will return %NULL and @error will be
- *  set. If there's no content to read, it will still return %NULL,
- *  but @error won't be set.
+ * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
+ *  a NUL terminated byte array with the line that was read in
+ *  (without the newlines).  Set @length to a #gsize to get the length
+ *  of the read line.  On an error, it will return %NULL and @error
+ *  will be set. If there's no content to read, it will still return
+ *  %NULL, but @error won't be set.
  **/
 char *
 g_data_input_stream_read_line (GDataInputStream  *stream,
@@ -819,12 +819,13 @@ g_data_input_stream_read_line (GDataInputStream  *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: (transfer full): a NUL terminated UTF-8 string with the
- *  line that was read in (without the newlines).  Set @length to a
- *  #gsize to get the length of the read line.  On an error, it will
- *  return %NULL and @error will be set.  For UTF-8 conversion errors,
- *  the set error domain is %G_CONVERT_ERROR.  If there's no content to
- *  read, it will still return %NULL, but @error won't be set.
+ * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
+ *  with the line that was read in (without the newlines).  Set
+ *  @length to a #gsize to get the length of the read line.  On an
+ *  error, it will return %NULL and @error will be set.  For UTF-8
+ *  conversion errors, the set error domain is %G_CONVERT_ERROR.  If
+ *  there's no content to read, it will still return %NULL, but @error
+ *  won't be set.
  *
  * Since: 2.30
  **/
@@ -1197,12 +1198,12 @@ g_data_input_stream_read_until_async (GDataInputStream    *stream,
  * string encoding in g_data_input_stream_read_line() applies here as
  * well.
  *
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8):  a 
- *  NUL-terminated byte array with the line that was read in
- *  (without the newlines).  Set @length to a #gsize to get the
- *  length of the read line.  On an error, it will return %NULL and
- *  @error will be set. If there's no content to read, it will
- *  still return %NULL, but @error won't be set.
+ * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
+ *  a NUL-terminated byte array with the line that was read in
+ *  (without the newlines).  Set @length to a #gsize to get the length
+ *  of the read line.  On an error, it will return %NULL and @error
+ *  will be set. If there's no content to read, it will still return
+ *  %NULL, but @error won't be set.
  *
  * Since: 2.20
  */
@@ -1227,12 +1228,12 @@ g_data_input_stream_read_line_finish (GDataInputStream  *stream,
  * Finish an asynchronous call started by
  * g_data_input_stream_read_line_async().
  *
- * Returns: (transfer full): a string with the line that was read in
- *  (without the newlines).  Set @length to a #gsize to get the length
- *  of the read line.  On an error, it will return %NULL and @error
- *  will be set. For UTF-8 conversion errors, the set error domain is
- *  %G_CONVERT_ERROR.  If there's no content to read, it will still
- *  return %NULL, but @error won't be set.
+ * Returns: (nullable) (transfer full): a string with the line that
+ *  was read in (without the newlines).  Set @length to a #gsize to
+ *  get the length of the read line.  On an error, it will return
+ *  %NULL and @error will be set. For UTF-8 conversion errors, the set
+ *  error domain is %G_CONVERT_ERROR.  If there's no content to read,
+ *  it will still return %NULL, but @error won't be set.
  *
  * Since: 2.30
  */
diff --git a/gio/gdbusmessage.c b/gio/gdbusmessage.c
index 8a53238c6..dade2b9f0 100644
--- a/gio/gdbusmessage.c
+++ b/gio/gdbusmessage.c
@@ -1114,7 +1114,8 @@ g_dbus_message_get_header_fields (GDBusMessage  *message)
  *
  * Gets the body of a message.
  *
- * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
+ * Returns: (transfer none): A #GVariant or %NULL if the body is
+ * empty. Do not free, it is owned by @message.
  *
  * Since: 2.26
  */
diff --git a/gio/gdbusobjectmanagerclient.c b/gio/gdbusobjectmanagerclient.c
index 2165548bb..e90ecb1e6 100644
--- a/gio/gdbusobjectmanagerclient.c
+++ b/gio/gdbusobjectmanagerclient.c
@@ -957,8 +957,8 @@ g_dbus_object_manager_client_get_flags (GDBusObjectManagerClient *manager)
  * #GObject::notify signal to track changes to the
  * #GDBusObjectManagerClient:name-owner property.
  *
- * Returns: The name owner or %NULL if no name owner exists. Free with
- * g_free().
+ * Returns: (nullable): The name owner or %NULL if no name owner
+ * exists. Free with g_free().
  *
  * Since: 2.30
  */
diff --git a/gio/gfile.c b/gio/gfile.c
index 0da16c8bb..3e9123f37 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -486,8 +486,8 @@ g_file_get_uri_scheme (GFile *file)
  *
  * This call does no blocking I/O.
  *
- * Returns: string containing the #GFile's base name, or %NULL
- *     if given #GFile is invalid. The returned string should be
+ * Returns: (nullable): string containing the #GFile's base name, or
+ *     %NULL if given #GFile is invalid. The returned string should be
  *     freed with g_free() when no longer needed.
  */
 char *
@@ -510,9 +510,9 @@ g_file_get_basename (GFile *file)
  *
  * This call does no blocking I/O.
  *
- * Returns: string containing the #GFile's path, or %NULL if
- *     no such path exists. The returned string should be
- *     freed with g_free() when no longer needed.
+ * Returns: (nullable): string containing the #GFile's path, or %NULL
+ *     if no such path exists. The returned string should be freed
+ *     with g_free() when no longer needed.
  */
 char *
 g_file_get_path (GFile *file)
@@ -680,9 +680,9 @@ g_file_equal (GFile *file1,
  *
  * This call does no blocking I/O.
  *
- * Returns: (transfer full): a #GFile structure to the
- *     parent of the given #GFile or %NULL if there is
- *     no parent. Free the returned object with g_object_unref().
+ * Returns: (nullable) (transfer full): a #GFile structure to the
+ *     parent of the given #GFile or %NULL if there is no parent. Free
+ *     the returned object with g_object_unref().
  */
 GFile *
 g_file_get_parent (GFile *file)
@@ -849,10 +849,10 @@ g_file_has_prefix (GFile *file,
  *
  * This call does no blocking I/O.
  *
- * Returns: string with the relative path from @descendant
- *     to @parent, or %NULL if @descendant doesn't have @parent
- *     as prefix. The returned string should be freed with g_free()
- *     when no longer needed.
+ * Returns: (nullable): string with the relative path from @descendant
+ *     to @parent, or %NULL if @descendant doesn't have @parent as
+ *     prefix. The returned string should be freed with g_free() when
+ *     no longer needed.
  */
 char *
 g_file_get_relative_path (GFile *parent,
diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index 597d1acd2..c0d40541a 100644
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -191,8 +191,9 @@ g_file_enumerator_init (GFileEnumerator *enumerator)
  * enumerator is at the end, %NULL will be returned and @error will
  * be unset.
  *
- * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
- *    Free the returned object with g_object_unref() when no longer needed.
+ * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
+ *    or end of enumerator.  Free the returned object with
+ *    g_object_unref() when no longer needed.
  **/
 GFileInfo *
 g_file_enumerator_next_file (GFileEnumerator *enumerator,
diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c
index f47eb85d9..f2ffe645a 100644
--- a/gio/gfileinfo.c
+++ b/gio/gfileinfo.c
@@ -619,9 +619,9 @@ g_file_info_has_namespace (GFileInfo  *info,
  *
  * Lists the file info structure's attributes.
  *
- * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
- * possible attribute types for the given @name_space, or
- * %NULL on error.
+ * Returns: (nullable) (array zero-terminated=1) (transfer full): a
+ * null-terminated array of strings of all of the possible attribute
+ * types for the given @name_space, or %NULL on error.
  **/
 char **
 g_file_info_list_attributes (GFileInfo  *info,
diff --git a/gio/gicon.c b/gio/gicon.c
index 31781f6c3..b5080dae2 100644
--- a/gio/gicon.c
+++ b/gio/gicon.c
@@ -203,8 +203,8 @@ g_icon_to_string_tokenized (GIcon *icon, GString *s)
  *    simply the name (such as `network-server`).
  *
  * Virtual: to_tokens
- * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
- * be serialized. Use g_free() to free.
+ * Returns: (nullable): An allocated NUL-terminated UTF8 string or
+ * %NULL if @icon can't be serialized. Use g_free() to free.
  *
  * Since: 2.20
  */
diff --git a/gio/gloadableicon.c b/gio/gloadableicon.c
index ed1e63f4a..17321bc06 100644
--- a/gio/gloadableicon.c
+++ b/gio/gloadableicon.c
@@ -60,11 +60,12 @@ g_loadable_icon_default_init (GLoadableIconIface *iface)
  * g_loadable_icon_load:
  * @icon: a #GLoadableIcon.
  * @size: an integer.
- * @type: (out) (allow-none): a location to store the type of the
- *        loaded icon, %NULL to ignore.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occurring, or %NULL to 
+ * @type: (out) (optional): a location to store the type of the loaded
+ * icon, %NULL to ignore.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to
  * ignore.
+ * @error: a #GError location to store the error occurring, or %NULL
+ * to ignore.
  * 
  * Loads a loadable icon. For the asynchronous version of this function, 
  * see g_loadable_icon_load_async().
@@ -120,8 +121,8 @@ g_loadable_icon_load_async (GLoadableIcon       *icon,
  * g_loadable_icon_load_finish:
  * @icon: a #GLoadableIcon.
  * @res: a #GAsyncResult.
- * @type: (out) (allow-none): a location to store the type of the
- *        loaded icon, %NULL to ignore.
+ * @type: (out) (optional): a location to store the type of the loaded
+ *        icon, %NULL to ignore.
  * @error: a #GError location to store the error occurring, or %NULL to 
  * ignore.
  * 
diff --git a/gio/gpollableinputstream.c b/gio/gpollableinputstream.c
index c640140e9..45947a440 100644
--- a/gio/gpollableinputstream.c
+++ b/gio/gpollableinputstream.c
@@ -159,8 +159,8 @@ g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
 /**
  * g_pollable_input_stream_read_nonblocking:
  * @stream: a #GPollableInputStream
- * @buffer: a buffer to read data into (which should be at least @count
- *     bytes long).
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ *     read data into (which should be at least @count bytes long).
  * @count: the number of bytes you want to read
  * @cancellable: (allow-none): a #GCancellable, or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
diff --git a/gio/gpollableutils.c b/gio/gpollableutils.c
index 8a778f31f..58313a7fa 100644
--- a/gio/gpollableutils.c
+++ b/gio/gpollableutils.c
@@ -169,7 +169,8 @@ g_pollable_source_new_full (gpointer      pollable_stream,
 /**
  * g_pollable_stream_read:
  * @stream: a #GInputStream
- * @buffer: a buffer to read data into
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ *   read data into
  * @count: the number of bytes to read
  * @blocking: whether to do blocking I/O
  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index 5b996e16d..f643c9f4d 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -394,7 +394,7 @@ g_settings_schema_source_get_default (void)
  *
  * If the schema isn't found, %NULL is returned.
  *
- * Returns: (transfer full): a new #GSettingsSchema
+ * Returns: (nullable) (transfer full): a new #GSettingsSchema
  *
  * Since: 2.32
  **/
diff --git a/gio/gtlsclientconnection.c b/gio/gtlsclientconnection.c
index 410dda9a6..5d2a17d1b 100644
--- a/gio/gtlsclientconnection.c
+++ b/gio/gtlsclientconnection.c
@@ -121,7 +121,7 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
 							     G_PARAM_STATIC_STRINGS));
 
   /**
-   * GTlsClientConnection:accepted-cas:
+   * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray):
    *
    * A list of the distinguished names of the Certificate Authorities
    * that the server will accept client certificates signed by. If the
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index 909938725..20dc86230 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -568,7 +568,9 @@ g_tls_database_verify_chain_finish (GTlsDatabase          *self,
  * and between applications. If a certificate is modified in the database,
  * then it is not guaranteed that this handle will continue to point to it.
  *
- * Returns: (allow-none): a newly allocated string containing the handle.
+ * Returns: (nullable): a newly allocated string containing the
+ * handle.
+ *
  * Since: 2.30
  */
 gchar*
diff --git a/gio/gvolume.c b/gio/gvolume.c
index 087c9b78f..a14cbc613 100644
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -641,8 +641,8 @@ g_volume_enumerate_identifiers (GVolume *volume)
  * implementations to find the underlying mount to shadow, see
  * g_mount_is_shadowed() for more details.
  *
- * Returns: (transfer full): the activation root of @volume or %NULL. Use
- *     g_object_unref() to free.
+ * Returns: (nullable) (transfer full): the activation root of @volume
+ *     or %NULL. Use g_object_unref() to free.
  *
  * Since: 2.18
  */