diff --git a/libsecret/secret-backend.c b/libsecret/secret-backend.c
index 6ce2645..946b342 100644
--- a/libsecret/secret-backend.c
+++ b/libsecret/secret-backend.c
@@ -204,7 +204,7 @@ on_ensure_for_flags (GObject *source_object,
 /**
  * secret_backend_get:
  * @flags: flags for which service functionality to ensure is initialized
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
diff --git a/libsecret/secret-collection.c b/libsecret/secret-collection.c
index a6d1e87..0d800bd 100644
--- a/libsecret/secret-collection.c
+++ b/libsecret/secret-collection.c
@@ -777,7 +777,7 @@ on_load_item (GObject *source,
 /**
  * secret_collection_load_items:
  * @self: the secret collection
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -870,7 +870,7 @@ secret_collection_load_items_finish (SecretCollection *self,
 /**
  * secret_collection_load_items_sync:
  * @self: the secret collection
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Ensure that the #SecretCollection proxy has loaded all the items present
@@ -1057,11 +1057,11 @@ _secret_collection_properties_new (const gchar *label)
 
 /**
  * secret_collection_create:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @label: label for the new collection
- * @alias: (allow-none): alias to assign to the collection
+ * @alias: (nullable): alias to assign to the collection
  * @flags: currently unused
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1077,7 +1077,7 @@ _secret_collection_properties_new (const gchar *label)
  * collection with that alias already exists, then a new collection will not
  * be created. The previous one will be returned instead.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  */
@@ -1155,11 +1155,11 @@ secret_collection_create_finish (GAsyncResult *result,
 
 /**
  * secret_collection_create_sync:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @label: label for the new collection
- * @alias: (allow-none): alias to assign to the collection
+ * @alias: (nullable): alias to assign to the collection
  * @flags: currently unused
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Create a new collection in the secret service.
@@ -1174,7 +1174,7 @@ secret_collection_create_finish (GAsyncResult *result,
  * collection with that alias already exists, then a new collection will not
  * be created. The previous one will be returned instead.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * Returns: (transfer full): the new collection, which should be unreferenced
@@ -1397,10 +1397,10 @@ on_search_paths (GObject *source,
 /**
  * secret_collection_search:
  * @self: a secret collection
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1531,10 +1531,10 @@ collection_load_items_sync (SecretCollection *self,
 /**
  * secret_collection_search_sync:
  * @self: a secret collection
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Search for items matching the @attributes in the @collection.
@@ -1625,7 +1625,7 @@ on_service_delete_path (GObject *source,
 /**
  * secret_collection_delete:
  * @self: a collection
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1687,7 +1687,7 @@ secret_collection_delete_finish (SecretCollection *self,
 /**
  * secret_collection_delete_sync:
  * @self: a collection
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Delete this collection.
@@ -1841,7 +1841,7 @@ secret_collection_get_label (SecretCollection *self)
  * secret_collection_set_label:
  * @self: a collection
  * @label: a new label
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1891,7 +1891,7 @@ secret_collection_set_label_finish (SecretCollection *self,
  * secret_collection_set_label_sync:
  * @self: a collection
  * @label: a new label
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Set the label of this collection.
@@ -2104,17 +2104,17 @@ on_read_alias_service (GObject *source,
 
 /**
  * secret_collection_for_alias:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @alias: the alias to lookup
  * @flags: options for the collection initialization
- * @cancellable: (allow-none): optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
  * Lookup which collection is assigned to this alias. Aliases help determine
  * well known collections, such as 'default'.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -2185,16 +2185,16 @@ secret_collection_for_alias_finish (GAsyncResult *result,
 
 /**
  * secret_collection_for_alias_sync:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @alias: the alias to lookup
  * @flags: options for the collection initialization
- * @cancellable: (allow-none): optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Lookup which collection is assigned to this alias. Aliases help determine
  * well known collections, such as 'default'.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block and should not be used in user interface threads.
diff --git a/libsecret/secret-item.c b/libsecret/secret-item.c
index afe90e8..efab923 100644
--- a/libsecret/secret-item.c
+++ b/libsecret/secret-item.c
@@ -718,12 +718,12 @@ item_properties_new (const gchar *label,
 /**
  * secret_item_create:
  * @collection: a secret collection to create this item in
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): attributes for the new item
  * @label: label for the new item
  * @value: secret value for the new item
  * @flags: flags for the creation of the new item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -813,12 +813,12 @@ secret_item_create_finish (GAsyncResult *result,
 /**
  * secret_item_create_sync:
  * @collection: a secret collection to create this item in
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): attributes for the new item
  * @label: label for the new item
  * @value: secret value for the new item
  * @flags: flags for the creation of the new item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Create a new item in the secret service.
@@ -964,7 +964,7 @@ secret_item_delete_finish (SecretItem *self,
 /**
  * secret_item_delete_sync:
  * @self: an item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Delete this secret item.
@@ -1057,7 +1057,7 @@ secret_item_get_service (SecretItem *self)
  *
  * To load the secret call the secret_item_load_secret() method.
  *
- * Returns: (transfer full) (allow-none): the secret value which should be
+ * Returns: (transfer full) (nullable): the secret value which should be
  *          released with secret_value_unref(), or %NULL
  */
 SecretValue *
@@ -1211,7 +1211,7 @@ secret_item_load_secret_finish (SecretItem *self,
 /**
  * secret_item_load_secret_sync:
  * @self: an item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Load the secret value of this item.
@@ -1388,7 +1388,7 @@ on_loads_secrets_session (GObject *source,
 /**
  * secret_item_load_secrets:
  * @items: (element-type Secret.Item): the items to retrieve secrets for
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1483,7 +1483,7 @@ secret_item_load_secrets_finish (GAsyncResult *result,
 /**
  * secret_item_load_secrets_sync:
  * @items: (element-type Secret.Item): the items to retrieve secrets for
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Load the secret values for a secret item stored in the service.
@@ -1588,7 +1588,7 @@ on_set_ensure_session (GObject *source,
  * secret_item_set_secret:
  * @self: an item
  * @value: a new secret value
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1652,7 +1652,7 @@ secret_item_set_secret_finish (SecretItem *self,
  * secret_item_set_secret_sync:
  * @self: an item
  * @value: a new secret value
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Set the secret value of this item.
@@ -1756,9 +1756,9 @@ secret_item_get_attributes (SecretItem *self)
 /**
  * secret_item_set_attributes:
  * @self: an item
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): a new set of attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the asynchronous operation completes
  * @user_data: data to pass to the callback
  *
@@ -1820,9 +1820,9 @@ secret_item_set_attributes_finish (SecretItem *self,
 /**
  * secret_item_set_attributes_sync:
  * @self: an item
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): a new set of attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Set the attributes of this item.
@@ -1888,7 +1888,7 @@ secret_item_get_label (SecretItem *self)
  * secret_item_set_label:
  * @self: an item
  * @label: a new label
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1938,7 +1938,7 @@ secret_item_set_label_finish (SecretItem *self,
  * secret_item_set_label_sync:
  * @self: an item
  * @label: a new label
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Set the label of this item.
diff --git a/libsecret/secret-methods.c b/libsecret/secret-methods.c
index 5eb9cdf..e0ccce4 100644
--- a/libsecret/secret-methods.c
+++ b/libsecret/secret-methods.c
@@ -259,18 +259,18 @@ on_search_service (GObject *source,
 
 /**
  * secret_service_search:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
  * Search for items matching the @attributes. All collections are searched.
  * The @attributes should be a table of string keys and string values.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the
@@ -336,7 +336,7 @@ secret_service_search (SecretService *service,
 
 /**
  * secret_service_search_finish:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @result: asynchronous result passed to callback
  * @error: location to place error on failure
  *
@@ -403,17 +403,17 @@ service_load_items_sync (SecretService *service,
 
 /**
  * secret_service_search_sync:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Search for items matching the @attributes. All collections are searched.
  * The @attributes should be a table of string keys and string values.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the
@@ -726,9 +726,9 @@ service_xlock_finish (SecretService *service,
 
 /**
  * secret_service_lock:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @objects: (element-type Gio.DBusProxy): the items or collections to lock
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -737,7 +737,7 @@ service_xlock_finish (SecretService *service,
  * The secret service may not be able to lock items individually, and may
  * lock an entire collection instead.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method returns immediately and completes asynchronously. The secret
@@ -759,9 +759,9 @@ secret_service_lock (SecretService *service,
 
 /**
  * secret_service_lock_finish:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @result: asynchronous result passed to the callback
- * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (allow-none):
+ * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
  *          location to place list of items or collections that were locked
  * @error: location to place an error on failure
  *
@@ -787,10 +787,10 @@ secret_service_lock_finish (SecretService *service,
 
 /**
  * secret_service_lock_sync:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @objects: (element-type Gio.DBusProxy): the items or collections to lock
- * @cancellable: optional cancellation object
- * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (allow-none):
+ * @cancellable: (nullable): optional cancellation object
+ * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
  *          location to place list of items or collections that were locked
  * @error: location to place an error on failure
  *
@@ -799,7 +799,7 @@ secret_service_lock_finish (SecretService *service,
  * The secret service may not be able to lock items individually, and may
  * lock an entire collection instead.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user
@@ -840,9 +840,9 @@ secret_service_lock_sync (SecretService *service,
 
 /**
  * secret_service_unlock:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @objects: (element-type Gio.DBusProxy): the items or collections to unlock
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -851,7 +851,7 @@ secret_service_lock_sync (SecretService *service,
  * The secret service may not be able to unlock items individually, and may
  * unlock an entire collection instead.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user
@@ -873,9 +873,9 @@ secret_service_unlock (SecretService *service,
 
 /**
  * secret_service_unlock_finish:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @result: asynchronous result passed to the callback
- * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (allow-none):
+ * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
  *            location to place list of items or collections that were unlocked
  * @error: location to place an error on failure
  *
@@ -901,10 +901,10 @@ secret_service_unlock_finish (SecretService *service,
 
 /**
  * secret_service_unlock_sync:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @objects: (element-type Gio.DBusProxy): the items or collections to unlock
- * @cancellable: optional cancellation object
- * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (allow-none):
+ * @cancellable: (nullable): optional cancellation object
+ * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
  *            location to place list of items or collections that were unlocked
  * @error: location to place an error on failure
  *
@@ -913,7 +913,7 @@ secret_service_unlock_finish (SecretService *service,
  * The secret service may not be able to unlock items individually, and may
  * unlock an entire collection instead.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user
@@ -1102,13 +1102,14 @@ on_store_service (GObject *source,
 
 /**
  * secret_service_store:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema to use to check attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema to use to check attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @value: the secret value
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1119,7 +1120,7 @@ on_store_service (GObject *source,
  * If the attributes match a secret item already stored in the collection, then
  * the item will be updated with these new values.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * If @collection is not specified, then the default collection will be
@@ -1193,7 +1194,7 @@ secret_service_store (SecretService *service,
 
 /**
  * secret_service_store_finish:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @result: the asynchronous result passed to the callback
  * @error: location to place an error on failure
  *
@@ -1219,13 +1220,14 @@ secret_service_store_finish (SecretService *service,
 
 /**
  * secret_service_store_sync:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @value: the secret value
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Store a secret value in the secret service.
@@ -1239,7 +1241,7 @@ secret_service_store_finish (SecretService *service,
  * used. Use #SECRET_COLLECTION_SESSION to store the password in the session
  * collection, which doesn't get stored across login sessions.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -1419,10 +1421,10 @@ on_lookup_service (GObject *source,
 
 /**
  * secret_service_lookup:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1430,7 +1432,7 @@ on_lookup_service (GObject *source,
  *
  * The @attributes should be a set of key and value string pairs.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -1480,7 +1482,7 @@ secret_service_lookup (SecretService *service,
 
 /**
  * secret_service_lookup_finish:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @result: the asynchronous result passed to the callback
  * @error: location to place an error on failure
  *
@@ -1517,17 +1519,17 @@ secret_service_lookup_finish (SecretService *service,
 
 /**
  * secret_service_lookup_sync:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Lookup a secret value in the secret service.
  *
  * The @attributes should be a set of key and value string pairs.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -1670,10 +1672,10 @@ on_delete_service (GObject *source,
 
 /**
  * secret_service_clear:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1681,7 +1683,7 @@ on_delete_service (GObject *source,
  *
  * The @attributes should be a set of key and value string pairs.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -1735,7 +1737,7 @@ secret_service_clear (SecretService *service,
 
 /**
  * secret_service_clear_finish:
- * @service: (allow-none): the secret service
+ * @service: (nullable): the secret service
  * @result: the asynchronous result passed to the callback
  * @error: location to place an error on failure
  *
@@ -1767,17 +1769,17 @@ secret_service_clear_finish (SecretService *service,
 
 /**
  * secret_service_clear_sync:
- * @service: (allow-none): the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @service: (nullable): the secret service
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Remove unlocked items which match the attributes from the secret service.
  *
  * The @attributes should be a set of key and value string pairs.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -1881,17 +1883,17 @@ on_set_alias_service (GObject *source,
 
 /**
  * secret_service_set_alias:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @alias: the alias to assign the collection to
- * @collection: (allow-none): the collection to assign to the alias
- * @cancellable: (allow-none): optional cancellation object
+ * @collection: (nullable): the collection to assign to the alias
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
  * Assign a collection to this alias. Aliases help determine
  * well known collections, such as 'default'.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -1945,7 +1947,7 @@ secret_service_set_alias (SecretService *service,
 
 /**
  * secret_service_set_alias_finish:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @result: asynchronous result passed to callback
  * @error: location to place error on failure
  *
@@ -1971,16 +1973,16 @@ secret_service_set_alias_finish (SecretService *service,
 
 /**
  * secret_service_set_alias_sync:
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @alias: the alias to assign the collection to
- * @collection: (allow-none): the collection to assign to the alias
- * @cancellable: (allow-none): optional cancellation object
+ * @collection: (nullable): the collection to assign to the alias
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Assign a collection to this alias. Aliases help determine
  * well known collections, such as 'default'.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block and should not be used in user interface threads.
diff --git a/libsecret/secret-password.c b/libsecret/secret-password.c
index 491e211..6fc7755 100644
--- a/libsecret/secret-password.c
+++ b/libsecret/secret-password.c
@@ -47,10 +47,11 @@
 /**
  * secret_password_store: (skip)
  * @schema: the schema for attributes
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  * @...: the attribute keys and values, terminated with %NULL
@@ -178,10 +179,11 @@ on_store_backend (GObject *source,
  * secret_password_storev: (rename-to secret_password_store)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: (scope async): called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -237,10 +239,11 @@ secret_password_storev (const SecretSchema *schema,
 /**
  * secret_password_store_binary: (skip)
  * @schema: the schema for attributes
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @value: a #SecretValue
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  * @...: the attribute keys and values, terminated with %NULL
@@ -290,10 +293,11 @@ secret_password_store_binary (const SecretSchema *schema,
  * secret_password_storev_binary: (rename-to secret_password_store_binary)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @value: a #SecretValue
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: (scope async): called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -364,10 +368,11 @@ secret_password_store_finish (GAsyncResult *result,
 /**
  * secret_password_store_sync:
  * @schema: the schema for attributes
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -428,10 +433,11 @@ secret_password_store_sync (const SecretSchema *schema,
  * secret_password_storev_sync: (rename-to secret_password_store_sync)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Store a password in the secret service.
@@ -491,10 +497,11 @@ secret_password_storev_sync (const SecretSchema *schema,
 /**
  * secret_password_store_binary_sync:
  * @schema: the schema for attributes
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @value: a #SecretValue
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -548,10 +555,11 @@ secret_password_store_binary_sync (const SecretSchema *schema,
  * secret_password_storev_binary_sync: (rename-to secret_password_store_binary_sync)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @collection: (allow-none): a collection alias, or D-Bus object path of the collection where to store the secret
+ * @collection: (nullable): a collection alias, or D-Bus object path of the
+ *              collection where to store the secret
  * @label: label for the secret
  * @value: a #SecretValue
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Store a password in the secret service.
@@ -607,7 +615,7 @@ secret_password_storev_binary_sync (const SecretSchema *schema,
 /**
  * secret_password_lookup: (skip)
  * @schema: the schema for the attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  * @...: the attribute keys and values, terminated with %NULL
@@ -723,7 +731,7 @@ on_lookup_backend (GObject *source,
  * secret_password_lookupv: (rename-to secret_password_lookup)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: (scope async): called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -840,7 +848,7 @@ secret_password_lookup_finish (GAsyncResult *result,
 /**
  * secret_password_lookup_sync: (skip)
  * @schema: the schema for the attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -892,7 +900,7 @@ secret_password_lookup_sync (const SecretSchema *schema,
 /**
  * secret_password_lookup_nonpageable_sync: (skip)
  * @schema: the schema for the attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -945,7 +953,7 @@ secret_password_lookup_nonpageable_sync (const SecretSchema *schema,
  * secret_password_lookupv_nonpageable_sync: (skip)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Lookup a password in the secret service.
@@ -996,7 +1004,7 @@ secret_password_lookupv_nonpageable_sync (const SecretSchema *schema,
 /**
  * secret_password_lookup_binary_sync: (skip)
  * @schema: the schema for the attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -1047,7 +1055,7 @@ secret_password_lookup_binary_sync (const SecretSchema *schema,
  * secret_password_lookupv_binary_sync: (skip)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Lookup a password in the secret service.
@@ -1100,7 +1108,7 @@ secret_password_lookupv_binary_sync (const SecretSchema *schema,
  * secret_password_lookupv_sync: (rename-to secret_password_lookup_sync)
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Lookup a password in the secret service.
@@ -1151,7 +1159,7 @@ secret_password_lookupv_sync (const SecretSchema *schema,
 /**
  * secret_password_clear:
  * @schema: the schema for the attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  * @...: the attribute keys and values, terminated with %NULL
@@ -1265,7 +1273,7 @@ on_clear_backend (GObject *source,
  * secret_password_clearv: (rename-to secret_password_clear)
  * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: (scope async): called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1328,7 +1336,7 @@ secret_password_clear_finish (GAsyncResult *result,
 /**
  * secret_password_clear_sync:
  * @schema: the schema for the attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -1380,7 +1388,7 @@ secret_password_clear_sync (const SecretSchema* schema,
  * secret_password_clearv_sync: (rename-to secret_password_clear_sync)
  * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Remove unlocked matching passwords from the secret service.
@@ -1431,7 +1439,7 @@ secret_password_clearv_sync (const SecretSchema *schema,
  * secret_password_search: (skip)
  * @schema: the schema for the attributes
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  * @...: the attribute keys and values, terminated with %NULL
@@ -1555,7 +1563,7 @@ on_search_backend (GObject *source,
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: (scope async): called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1623,7 +1631,7 @@ secret_password_search_finish (GAsyncResult *result,
  * secret_password_search_sync: (skip)
  * @schema: the schema for the attributes
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  * @...: the attribute keys and values, terminated with %NULL
  *
@@ -1680,7 +1688,7 @@ secret_password_search_sync (const SecretSchema *schema,
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
  * @flags: search option flags
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Search for items in the secret service.
@@ -1733,7 +1741,7 @@ secret_password_searchv_sync (const SecretSchema *schema,
 
 /**
  * secret_password_free: (skip)
- * @password: (allow-none): password to free
+ * @password: (nullable): password to free
  *
  * Clear the memory used by a password, and then free it.
  *
@@ -1753,7 +1761,7 @@ secret_password_free (gchar *password)
 
 /**
  * secret_password_wipe:
- * @password: (allow-none): password to clear
+ * @password: (nullable): password to clear
  *
  * Clear the memory used by a password.
  */
diff --git a/libsecret/secret-paths.c b/libsecret/secret-paths.c
index 0fca0ce..1fc3adc 100644
--- a/libsecret/secret-paths.c
+++ b/libsecret/secret-paths.c
@@ -41,16 +41,16 @@
 
 /**
  * secret_collection_new_for_dbus_path: (skip)
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @collection_path: the D-Bus path of the collection
  * @flags: options for the collection initialization
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
  * Get a new collection proxy for a collection in the secret service.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -120,15 +120,15 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result,
 
 /**
  * secret_collection_new_for_dbus_path_sync: (skip)
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @collection_path: the D-Bus path of the collection
  * @flags: options for the collection initialization
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Get a new collection proxy for a collection in the secret service.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -170,16 +170,16 @@ secret_collection_new_for_dbus_path_sync (SecretService *service,
 
 /**
  * secret_item_new_for_dbus_path: (skip)
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @item_path: the D-Bus path of the collection
  * @flags: initialization flags for the new item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
  * Get a new item proxy for a secret item in the secret service.
  *
- * If @service is NULL, then secret_service_get() will be called to get
+ * If @service is %NULL, then secret_service_get() will be called to get
  * the default #SecretService proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -248,15 +248,15 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result,
 
 /**
  * secret_item_new_for_dbus_path_sync: (skip)
- * @service: (allow-none): a secret service object
+ * @service: (nullable): a secret service object
  * @item_path: the D-Bus path of the item
  * @flags: initialization flags for the new item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Get a new item proxy for a secret item in the secret service.
  *
- * If @service is NULL, then secret_service_get_sync() will be called to get
+ * If @service is %NULL, then secret_service_get_sync() will be called to get
  * the default #SecretService proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -320,9 +320,9 @@ on_search_items_complete (GObject *source,
 /**
  * secret_collection_search_for_dbus_paths: (skip)
  * @collection: the secret collection
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -416,9 +416,9 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection,
 /**
  * secret_collection_search_for_dbus_paths_sync: (skip)
  * @collection: the secret collection
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Search for items matching the @attributes in @collection, and return their
@@ -471,9 +471,9 @@ secret_collection_search_for_dbus_paths_sync (SecretCollection *collection,
 /**
  * secret_service_search_for_dbus_paths: (skip)
  * @self: the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -543,10 +543,10 @@ _secret_service_search_for_paths_variant (SecretService *self,
  * secret_service_search_for_dbus_paths_finish: (skip)
  * @self: the secret service
  * @result: asynchronous result passed to callback
- * @unlocked: (out) (transfer full) (array zero-terminated=1) (allow-none):
+ * @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
  *            location to place an array of D-Bus object paths for matching
  *            items which were locked.
- * @locked: (out) (transfer full) (array zero-terminated=1) (allow-none):
+ * @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
  *          location to place an array of D-Bus object paths for matching
  *          items which were locked.
  * @error: location to place error on failure
@@ -604,13 +604,13 @@ secret_service_search_for_dbus_paths_finish (SecretService *self,
 /**
  * secret_service_search_for_dbus_paths_sync: (skip)
  * @self: the secret service
- * @schema: (allow-none): the schema for the attributes
+ * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
- * @cancellable: optional cancellation object
- * @unlocked: (out) (transfer full) (array zero-terminated=1) (allow-none):
+ * @cancellable: (nullable): optional cancellation object
+ * @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
  *            location to place an array of D-Bus object paths for matching
  *            items which were locked.
- * @locked: (out) (transfer full) (array zero-terminated=1) (allow-none):
+ * @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
  *          location to place an array of D-Bus object paths for matching
  *          items which were locked.
  * @error: location to place error on failure
@@ -729,7 +729,7 @@ on_get_secrets_session (GObject *source,
  * secret_service_get_secret_for_dbus_path: (skip)
  * @self: the secret service
  * @item_path: the D-Bus path to item to retrieve secret for
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -783,7 +783,7 @@ secret_service_get_secret_for_dbus_path (SecretService *self,
  *
  * Stability: Unstable
  *
- * Returns: (transfer full) (allow-none): the newly allocated secret value
+ * Returns: (transfer full) (nullable): the newly allocated secret value
  *          for the item, which should be released with secret_value_unref()
  */
 SecretValue *
@@ -812,7 +812,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self,
  * secret_service_get_secret_for_dbus_path_sync: (skip)
  * @self: the secret service
  * @item_path: the D-Bus path to item to retrieve secret for
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Get the secret value for a secret item stored in the service.
@@ -828,7 +828,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self,
  *
  * Stability: Unstable
  *
- * Returns: (transfer full) (allow-none): the newly allocated secret value
+ * Returns: (transfer full) (nullable): the newly allocated secret value
  *          for the item, which should be released with secret_value_unref()
  */
 SecretValue *
@@ -865,7 +865,7 @@ secret_service_get_secret_for_dbus_path_sync (SecretService *self,
  * secret_service_get_secrets_for_dbus_paths: (skip)
  * @self: the secret service
  * @item_paths: the D-Bus paths to items to retrieve secrets for
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -949,7 +949,7 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self,
  * secret_service_get_secrets_for_dbus_paths_sync: (skip)
  * @self: the secret service
  * @item_paths: the D-Bus paths to items to retrieve secrets for
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Get the secret values for a secret item stored in the service.
@@ -1149,8 +1149,8 @@ _secret_service_xlock_paths_finish (SecretService *self,
  * secret_service_lock_dbus_paths_sync: (skip)
  * @self: the secret service
  * @paths: (array zero-terminated=1): the D-Bus object paths of the items or collections to lock
- * @cancellable: optional cancellation object
- * @locked: (out) (array zero-terminated=1) (transfer full) (allow-none):
+ * @cancellable: (nullable): optional cancellation object
+ * @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
  *          location to place array of D-Bus paths of items or collections
  *          that were locked
  * @error: location to place an error on failure
@@ -1208,7 +1208,7 @@ secret_service_lock_dbus_paths_sync (SecretService *self,
  * secret_service_lock_dbus_paths: (skip)
  * @self: the secret service
  * @paths: (array zero-terminated=1): the D-Bus paths for items or collections to lock
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1246,7 +1246,7 @@ secret_service_lock_dbus_paths (SecretService *self,
  * secret_service_lock_dbus_paths_finish: (skip)
  * @self: the secret service
  * @result: asynchronous result passed to the callback
- * @locked: (out) (array zero-terminated=1) (transfer full) (allow-none):
+ * @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
  *          location to place array of D-Bus paths of items or collections
  *          that were locked
  * @error: location to place an error on failure
@@ -1279,8 +1279,8 @@ secret_service_lock_dbus_paths_finish (SecretService *self,
  * @self: the secret service
  * @paths: (array zero-terminated=1): the D-Bus object paths of the items or
  *         collections to unlock
- * @cancellable: optional cancellation object
- * @unlocked: (out) (array zero-terminated=1) (transfer full) (allow-none):
+ * @cancellable: (nullable): optional cancellation object
+ * @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
  *            location to place array of D-Bus paths of items or collections
  *            that were unlocked
  * @error: location to place an error on failure
@@ -1339,7 +1339,7 @@ secret_service_unlock_dbus_paths_sync (SecretService *self,
  * @self: the secret service
  * @paths: (array zero-terminated=1): the D-Bus paths for items or
  *         collections to unlock
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1378,7 +1378,7 @@ secret_service_unlock_dbus_paths (SecretService *self,
  * secret_service_unlock_dbus_paths_finish: (skip)
  * @self: the secret service
  * @result: asynchronous result passed to the callback
- * @unlocked: (out) (array zero-terminated=1) (transfer full) (allow-none):
+ * @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
  *            location to place array of D-Bus paths of items or collections
  *            that were unlocked
  * @error: location to place an error on failure
@@ -1533,7 +1533,7 @@ _secret_service_delete_path_finish (SecretService *self,
  * secret_service_delete_item_dbus_path: (skip)
  * @self: the secret service
  * @item_path: the D-Bus path of item to delete
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1585,7 +1585,7 @@ secret_service_delete_item_dbus_path_finish (SecretService *self,
  * secret_service_delete_item_dbus_path_sync: (skip)
  * @self: the secret service
  * @item_path: the D-Bus path of item to delete
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Delete a secret item from the secret service.
@@ -1705,10 +1705,10 @@ on_create_collection_called (GObject *source,
  * @self: a secret service object
  * @properties: (element-type utf8 GLib.Variant): hash table of properties for
  *              the new collection
- * @alias: (allow-none): an alias to check for before creating the new
+ * @alias: (nullable): an alias to check for before creating the new
  *         collection, or to assign to the new collection
  * @flags: not currently used
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1822,10 +1822,10 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
  * @self: a secret service object
  * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
  *              for the new collection
- * @alias: (allow-none): an alias to check for before creating the new
+ * @alias: (nullable): an alias to check for before creating the new
  *         collection, or to assign to the new collection
  * @flags: not currently used
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Create a new collection in the secret service and return its path.
@@ -2011,7 +2011,7 @@ on_create_item_session (GObject *source,
  *              for the new collection
  * @value: the secret value to store in the item
  * @flags: flags for the creation of the new item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -2133,7 +2133,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
  *              for the new collection
  * @value: the secret value to store in the item
  * @flags: flags for the creation of the new item
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Create a new item in a secret service collection and return its D-Bus
@@ -2199,7 +2199,7 @@ secret_service_create_item_dbus_path_sync (SecretService *self,
  * secret_service_read_alias_dbus_path: (skip)
  * @self: a secret service object
  * @alias: the alias to lookup
- * @cancellable: (allow-none): optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -2271,7 +2271,7 @@ secret_service_read_alias_dbus_path_finish (SecretService *self,
  * secret_service_read_alias_dbus_path_sync: (skip)
  * @self: a secret service object
  * @alias: the alias to lookup
- * @cancellable: (allow-none): optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Lookup which collection is assigned to this alias. Aliases help determine
@@ -2318,8 +2318,8 @@ secret_service_read_alias_dbus_path_sync (SecretService *self,
  * secret_service_set_alias_to_dbus_path: (skip)
  * @self: a secret service object
  * @alias: the alias to assign the collection to
- * @collection_path: (allow-none): the dbus object path of the collection to assign to the alias
- * @cancellable: (allow-none): optional cancellation object
+ * @collection_path: (nullable): the dbus object path of the collection to assign to the alias
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -2390,8 +2390,9 @@ secret_service_set_alias_to_dbus_path_finish (SecretService *self,
  * secret_service_set_alias_to_dbus_path_sync: (skip)
  * @self: a secret service object
  * @alias: the alias to assign the collection to
- * @collection_path: (allow-none): the dbus object path of the collection to assign to the alias
- * @cancellable: (allow-none): optional cancellation object
+ * @collection_path: (nullable): the D-Bus object path of the collection to
+ *                   assign to the alias
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Assign a collection to this alias. Aliases help determine
@@ -2444,8 +2445,8 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self,
  * secret_service_prompt_at_dbus_path_sync: (skip)
  * @self: the secret service
  * @prompt_path: the D-Bus object path of the prompt
- * @cancellable: optional cancellation object
- * @return_type: (allow-none): the variant type of the prompt result
+ * @cancellable: (nullable): optional cancellation object
+ * @return_type: (nullable): the variant type of the prompt result
  * @error: location to place error on failure
  *
  * Perform prompting for a #SecretPrompt.
@@ -2491,8 +2492,8 @@ secret_service_prompt_at_dbus_path_sync (SecretService *self,
  * secret_service_prompt_at_dbus_path: (skip)
  * @self: the secret service
  * @prompt_path: the D-Bus object path of the prompt
- * @return_type: (allow-none): the variant type of the prompt result
- * @cancellable: optional cancellation object
+ * @return_type: (nullable): the variant type of the prompt result
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
diff --git a/libsecret/secret-prompt.c b/libsecret/secret-prompt.c
index b6e71a0..e8d8409 100644
--- a/libsecret/secret-prompt.c
+++ b/libsecret/secret-prompt.c
@@ -120,8 +120,8 @@ _secret_prompt_instance (SecretService *service,
 /**
  * secret_prompt_run:
  * @self: a prompt
- * @window_id: (allow-none): string form of XWindow id for parent window to be transient for
- * @cancellable: optional cancellation object
+ * @window_id: (nullable): string form of XWindow id for parent window to be transient for
+ * @cancellable: (nullable): optional cancellation object
  * @return_type: the variant type of the prompt result
  * @error: location to place an error on failure
  *
@@ -180,8 +180,8 @@ secret_prompt_run (SecretPrompt *self,
 /**
  * secret_prompt_perform_sync:
  * @self: a prompt
- * @window_id: (allow-none): string form of XWindow id for parent window to be transient for
- * @cancellable: optional cancellation object
+ * @window_id: (nullable): string form of XWindow id for parent window to be transient for
+ * @cancellable: (nullable): optional cancellation object
  * @return_type: the variant type of the prompt result
  * @error: location to place an error on failure
  *
@@ -408,9 +408,9 @@ on_prompt_cancelled (GCancellable *cancellable,
 /**
  * secret_prompt_perform:
  * @self: a prompt
- * @window_id: (allow-none): string form of XWindow id for parent window to be transient for
+ * @window_id: (nullable): string form of XWindow id for parent window to be transient for
  * @return_type: the variant type of the prompt result
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
diff --git a/libsecret/secret-service.c b/libsecret/secret-service.c
index 36d2feb..c2abbc2 100644
--- a/libsecret/secret-service.c
+++ b/libsecret/secret-service.c
@@ -947,7 +947,7 @@ secret_service_backend_iface (SecretBackendInterface *iface)
 /**
  * secret_service_get:
  * @flags: flags for which service functionality to ensure is initialized
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1045,7 +1045,7 @@ secret_service_get_finish (GAsyncResult *result,
 /**
  * secret_service_get_sync:
  * @flags: flags for which service functionality to ensure is initialized
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Get a #SecretService proxy for the Secret Service. If such a proxy object
@@ -1109,9 +1109,9 @@ secret_service_disconnect (void)
 /**
  * secret_service_open:
  * @service_gtype: the GType of the new secret service
- * @service_bus_name: (allow-none): the D-Bus service name of the secret service
+ * @service_bus_name: (nullable): the D-Bus service name of the secret service
  * @flags: flags for which service functionality to ensure is initialized
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1184,9 +1184,9 @@ secret_service_open_finish (GAsyncResult *result,
 /**
  * secret_service_open_sync:
  * @service_gtype: the GType of the new secret service
- * @service_bus_name: (allow-none): the D-Bus service name of the secret service
+ * @service_bus_name: (nullable): the D-Bus service name of the secret service
  * @flags: flags for which service functionality to ensure is initialized
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Create a new #SecretService proxy for the Secret Service.
@@ -1267,7 +1267,7 @@ secret_service_get_flags (SecretService *self)
  * initializing #SecretService proxy object, then this method will return
  * %NULL. Use secret_service_load_collections() to load the collections.
  *
- * Returns: (transfer full) (element-type Secret.Collection) (allow-none): a
+ * Returns: (transfer full) (element-type Secret.Collection) (nullable): a
  *          list of the collections in the secret service
  */
 GList *
@@ -1372,7 +1372,7 @@ _secret_service_take_session (SecretService *self,
  * This will be %NULL if no session has been established. Use
  * secret_service_ensure_session() to establish a session.
  *
- * Returns: (allow-none): a string representing the algorithms for transferring
+ * Returns: (nullable): a string representing the algorithms for transferring
  *          secrets
  */
 const gchar *
@@ -1402,7 +1402,7 @@ secret_service_get_session_algorithms (SecretService *self)
  * This will be %NULL if no session has been established. Use
  * secret_service_ensure_session() to establish a session.
  *
- * Returns: (allow-none): a string representing the D-Bus object path of the
+ * Returns: (nullable): a string representing the D-Bus object path of the
  *          session
  */
 const gchar *
@@ -1425,7 +1425,7 @@ secret_service_get_session_dbus_path (SecretService *self)
 /**
  * secret_service_ensure_session:
  * @self: the secret service
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1498,7 +1498,7 @@ secret_service_ensure_session_finish (SecretService *self,
 /**
  * secret_service_ensure_session_sync:
  * @self: the secret service
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Ensure that the #SecretService proxy has established a session with the
@@ -1638,7 +1638,7 @@ on_ensure_collection (GObject *source,
 /**
  * secret_service_load_collections:
  * @self: the secret service
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
@@ -1736,7 +1736,7 @@ secret_service_load_collections_finish (SecretService *self,
 /**
  * secret_service_load_collections_sync:
  * @self: the secret service
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
  *
  * Ensure that the #SecretService proxy has loaded all the collections present
@@ -1803,7 +1803,7 @@ secret_service_load_collections_sync (SecretService *self,
  * secret_service_prompt_sync:
  * @self: the secret service
  * @prompt: the prompt
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @return_type: the variant type of the prompt result
  * @error: location to place an error on failure
  *
@@ -1848,8 +1848,8 @@ secret_service_prompt_sync (SecretService *self,
  * secret_service_prompt:
  * @self: the secret service
  * @prompt: the prompt
- * @return_type: (allow-none): the variant type of the prompt result
- * @cancellable: optional cancellation object
+ * @return_type: (nullable): the variant type of the prompt result
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
diff --git a/libsecret/secret-value.c b/libsecret/secret-value.c
index 63464cd..d58feb3 100644
--- a/libsecret/secret-value.c
+++ b/libsecret/secret-value.c
@@ -175,7 +175,7 @@ secret_value_get (SecretValue *value,
  * Get the secret data in the #SecretValue if it contains a textual
  * value. The content type must be <literal>text/plain</literal>.
  *
- * Returns: (allow-none): the content type
+ * Returns: (nullable): the content type
  */
 const gchar *
 secret_value_get_text (SecretValue *value)