Merge branch 'doc-fixes' into 'master'

Improvements to documentation and annotations

See merge request GNOME/libsecret!103

17 files changed, 312 insertions, 249 deletions

diff --git a/README.md b/README.md
index ad1353a..ca39d6e 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ https://specifications.freedesktop.org/secret-service/.
 Documentation
 --------
 
-You can find the nighlt documentation at https://gnome.pages.gitlab.gnome.org/libsecret/.
+You can find the nightly documentation at https://gnome.pages.gitlab.gnome.org/libsecret/.
 
 Building
 --------
diff --git a/docs/reference/libsecret/libsecret-simple-api.md b/docs/reference/libsecret/libsecret-simple-api.md
index b6fda5e..11cf8fe 100644
--- a/docs/reference/libsecret/libsecret-simple-api.md
+++ b/docs/reference/libsecret/libsecret-simple-api.md
@@ -20,61 +20,6 @@ the [struct@Schema] structure.
 Each of the functions accept a variable list of attributes names and their
 values. Include a `NULL` to terminate the list of attributes.
 
-## SecretSchema
-
-Represents a set of attributes that are stored with an item. These schemas are
-used for interoperability between various services storing the same types of
-items.
-
-Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a
-set of attributes, and types (string, integer, boolean) for those attributes.
-
-Attributes are stored as strings in the Secret Service, and the attribute types
-simply define standard ways to store integer and boolean values as strings.
-Attributes are represented in libsecret via a [struct@GLib.HashTable] with
-string keys and values. Even for values that defined as an integer or boolean in
-the schema, the attribute values in the [struct@GLib.HashTable] are strings.
-Boolean values are stored as the strings 'true' and 'false'. Integer values are
-stored in decimal, with a preceding negative sign for negative integers.
-
-Schemas are handled entirely on the client side by this library. The name of the
-schema is automatically stored as an attribute on the item.
-
-Normally when looking up passwords only those with matching schema names are
-returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag,
-then lookups will not check that the schema name matches that on the item, only
-the schema's attributes are matched. This is useful when you are looking up
-items that are not stored by the libsecret library. Other libraries such as
-libgnome-keyring don't store the schema name.
-
-Additional schemas can be defined via the %SecretSchema structure like this:
-
-```c
-// in a header:
-
-const SecretSchema * example_get_schema (void) G_GNUC_CONST;
-
-#define EXAMPLE_SCHEMA  example_get_schema ()
-
-
-// in a .c file
-
-const SecretSchema *
-example_get_schema (void)
-{
-    static const SecretSchema the_schema = {
-        "org.example.Password", SECRET_SCHEMA_NONE,
-        {
-            {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
-            {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
-            {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
-            {  NULL, 0 },
-        }
-    };
-    return &the_schema;
-}
-```
-
 ## Secret Attributes
 
 Each item has a set of attributes, which are used to locate the item later.
diff --git a/docs/reference/libsecret/libsecret.toml.in b/docs/reference/libsecret/libsecret.toml.in
index 5af2ac4..5c4094d 100644
--- a/docs/reference/libsecret/libsecret.toml.in
+++ b/docs/reference/libsecret/libsecret.toml.in
@@ -32,7 +32,7 @@ show_index_summary = true
 show_class_hierarchy = true
 
 [source-location]
-base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master"
+base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master/"
 
 [extra]
 # The same order will be used when generating the index
diff --git a/libsecret/meson.build b/libsecret/meson.build
index 0b37328..97e0222 100644
--- a/libsecret/meson.build
+++ b/libsecret/meson.build
@@ -132,6 +132,7 @@ if get_option('introspection')
     'secret-types.h',
     'secret-value.c',
     'secret-value.h',
+    'secret-util.c',
   ]
   libsecret_gir_sources += version_h
   libsecret_gir_sources += _enums_generated
diff --git a/libsecret/secret-backend.c b/libsecret/secret-backend.c
index c527f82..9b3c22b 100644
--- a/libsecret/secret-backend.c
+++ b/libsecret/secret-backend.c
@@ -25,20 +25,12 @@
 #include "libsecret/secret-enum-types.h"
 
 /**
- * SecretBackend
- *
- * A backend implementation of password storage
+ * SecretBackend:
  *
  * #SecretBackend represents a backend implementation of password
  * storage.
  *
  * Stability: Stable
- */
-
-/**
- * SecretBackend:
- *
- * An object representing a backend implementation of password storage.
  *
  * Since: 0.19.0
  */
@@ -66,15 +58,21 @@
  * SecretBackendFlags:
  * @SECRET_BACKEND_NONE: no flags for initializing the #SecretBackend
  * @SECRET_BACKEND_OPEN_SESSION: establish a session for transfer of secrets
- *                               while initializing the #SecretBackend
+ *   while initializing the #SecretBackend
  * @SECRET_BACKEND_LOAD_COLLECTIONS: load collections while initializing the
- *                                   #SecretBackend
+ *   #SecretBackend
  *
  * Flags which determine which parts of the #SecretBackend are initialized.
  *
  * Since: 0.19.0
  */
 
+/**
+ * SECRET_BACKEND_EXTENSION_POINT_NAME:
+ *
+ * Extension point for the secret backend.
+ */
+
 G_DEFINE_INTERFACE_WITH_CODE (SecretBackend, secret_backend, G_TYPE_OBJECT,
 			      g_type_interface_add_prerequisite(g_define_type_id, G_TYPE_ASYNC_INITABLE);
 );
@@ -208,8 +206,9 @@ on_ensure_for_flags (GObject *source_object,
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
- * Get a #SecretBackend instance. If such a backend already exists,
- * then the same backend is returned.
+ * Get a #SecretBackend instance.
+ *
+ * If such a backend already exists, then the same backend is returned.
  *
  * If @flags contains any flags of which parts of the secret backend to
  * ensure are initialized, then those will be initialized before completing.
diff --git a/libsecret/secret-collection.c b/libsecret/secret-collection.c
index 9f426b7..5f40632 100644
--- a/libsecret/secret-collection.c
+++ b/libsecret/secret-collection.c
@@ -70,16 +70,19 @@
 /**
  * SECRET_COLLECTION_DEFAULT:
  *
- * An alias to the default collection. This can be passed to
- * [func@password_store] [func@Collection.for_alias].
+ * An alias to the default collection.
+ *
+ * This can be passed to [func@password_store] [func@Collection.for_alias].
  */
 
 /**
  * SECRET_COLLECTION_SESSION:
  *
  * An alias to the session collection, which will be cleared when the user ends
- * the session. This can be passed to [func@password_store],
- * [func@Collection.for_alias] or similar functions.
+ * the session.
+ *
+ * This can be passed to [func@password_store], [func@Collection.for_alias] or
+ * similar functions.
  */
 
 enum {
@@ -759,8 +762,9 @@ on_load_item (GObject *source,
  * @user_data: data to be passed to the callback
  *
  * Ensure that the #SecretCollection proxy has loaded all the items present
- * in the Secret Service. This affects the result of
- * [method@Collection.get_items].
+ * in the Secret Service.
+ *
+ * This affects the result of [method@Collection.get_items].
  *
  * For collections returned from [method@Service.get_collections] the items will
  * have already been loaded.
@@ -1922,8 +1926,10 @@ secret_collection_get_locked (SecretCollection *self)
  * secret_collection_get_created: (attributes org.gtk.Method.get_property=created)
  * @self: a collection
  *
- * Get the created date and time of the collection. The return value is
- * the number of seconds since the unix epoch, January 1st 1970.
+ * Get the created date and time of the collection.
+ *
+ * The return value is the number of seconds since the unix epoch, January 1st
+ * 1970.
  *
  * Returns: the created date and time
  */
@@ -1948,8 +1954,10 @@ secret_collection_get_created (SecretCollection *self)
  * secret_collection_get_modified: (attributes org.gtk.Method.get_property=modified)
  * @self: a collection
  *
- * Get the modified date and time of the collection. The return value is
- * the number of seconds since the unix epoch, January 1st 1970.
+ * Get the modified date and time of the collection.
+ *
+ * The return value is the number of seconds since the unix epoch, January 1st
+ * 1970.
  *
  * Returns: the modified date and time
  */
diff --git a/libsecret/secret-item.c b/libsecret/secret-item.c
index 3c4ddb6..6773c4b 100644
--- a/libsecret/secret-item.c
+++ b/libsecret/secret-item.c
@@ -353,7 +353,9 @@ secret_item_class_init (SecretItemClass *klass)
 	 * SecretItem:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full)
 	 *
 	 * The attributes set on this item. Attributes are used to locate an
-	 * item. They are not guaranteed to be stored or transferred securely.
+	 * item.
+	 *
+	 * They are not guaranteed to be stored or transferred securely.
 	 */
 	g_object_class_override_property (gobject_class, PROP_ATTRIBUTES, "attributes");
 
@@ -371,8 +373,10 @@ secret_item_class_init (SecretItemClass *klass)
 	/**
 	 * SecretItem:locked: (attributes org.gtk.Property.get=secret_item_get_locked)
 	 *
-	 * Whether the item is locked or not. An item may not be independently
-	 * lockable separate from other items in its collection.
+	 * Whether the item is locked or not.
+	 *
+	 * An item may not be independently lockable separate from other items in
+	 * its collection.
 	 *
 	 * To lock or unlock a item use the [method@Service.lock] or
 	 * [method@Service.unlock] functions.
@@ -588,8 +592,10 @@ secret_item_async_initable_iface (GAsyncInitableIface *iface)
  * secret_item_refresh:
  * @self: the collection
  *
- * Refresh the properties on this item. This fires off a request to
- * refresh, and the properties will be updated later.
+ * Refresh the properties on this item.
+ *
+ * This fires off a request to refresh, and the properties will be updated
+ * later.
  *
  * Calling this method is not normally necessary, as the secret service
  * will notify the client when properties change.
@@ -1046,8 +1052,10 @@ secret_item_get_service (SecretItem *self)
  * secret_item_get_secret:
  * @self: an item
  *
- * Get the secret value of this item. If this item is locked or the secret
- * has not yet been loaded then this will return %NULL.
+ * Get the secret value of this item.
+ *
+ * If this item is locked or the secret has not yet been loaded then this will
+ * return %NULL.
  *
  * To load the secret call the [method@Item.load_secret] method.
  *
@@ -1988,8 +1996,10 @@ secret_item_get_locked (SecretItem *self)
  * secret_item_get_created:
  * @self: an item
  *
- * Get the created date and time of the item. The return value is
- * the number of seconds since the unix epoch, January 1st 1970.
+ * Get the created date and time of the item.
+ *
+ * The return value is the number of seconds since the unix epoch, January 1st
+ * 1970.
  *
  * Returns: the created date and time
  */
@@ -2014,8 +2024,10 @@ secret_item_get_created (SecretItem *self)
  * secret_item_get_modified:
  * @self: an item
  *
- * Get the modified date and time of the item. The return value is
- * the number of seconds since the unix epoch, January 1st 1970.
+ * Get the modified date and time of the item.
+ *
+ * The return value is the number of seconds since the unix epoch, January 1st
+ * 1970.
  *
  * Returns: the modified date and time
  */
diff --git a/libsecret/secret-methods.c b/libsecret/secret-methods.c
index 1101c38..aa7539d 100644
--- a/libsecret/secret-methods.c
+++ b/libsecret/secret-methods.c
@@ -270,8 +270,10 @@ on_search_service (GObject *source,
  * @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.
+ * 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 [func@Service.get] will be called to get
  * the default [class@Service] proxy.
@@ -410,8 +412,10 @@ service_load_items_sync (SecretService *service,
  * @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.
+ * 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 [func@Service.get_sync] will be called to get
  * the default [class@Service] proxy.
@@ -760,7 +764,7 @@ secret_service_lock (SecretService *service,
  * @service: (nullable): the secret service
  * @result: asynchronous result passed to the callback
  * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
- *          location to place list of items or collections that were locked
+ *   location to place list of items or collections that were locked
  * @error: location to place an error on failure
  *
  * Complete asynchronous operation to lock items or collections in the secret
@@ -789,7 +793,7 @@ secret_service_lock_finish (SecretService *service,
  * @objects: (element-type Gio.DBusProxy): the items or collections to lock
  * @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
+ *   location to place list of items or collections that were locked
  * @error: location to place an error on failure
  *
  * Lock items or collections in the secret service.
@@ -874,7 +878,7 @@ secret_service_unlock (SecretService *service,
  * @service: (nullable): the secret service
  * @result: asynchronous result passed to the callback
  * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
- *            location to place list of items or collections that were unlocked
+ *   location to place list of items or collections that were unlocked
  * @error: location to place an error on failure
  *
  * Complete asynchronous operation to unlock items or collections in the secret
@@ -903,7 +907,7 @@ secret_service_unlock_finish (SecretService *service,
  * @objects: (element-type Gio.DBusProxy): the items or collections to unlock
  * @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
+ *   location to place list of items or collections that were unlocked
  * @error: location to place an error on failure
  *
  * Unlock items or collections in the secret service.
@@ -1117,7 +1121,7 @@ on_store_service (GObject *source,
  * @schema: (nullable): the schema to use to check attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @value: the secret value
  * @cancellable: (nullable): optional cancellation object
@@ -1237,7 +1241,7 @@ secret_service_store_finish (SecretService *service,
  * @schema: (nullable): the schema for the attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @value: the secret value
  * @cancellable: (nullable): optional cancellation object
@@ -1875,8 +1879,9 @@ on_set_alias_service (GObject *source,
  * @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'.
+ * Assign a collection to this alias.
+ *
+ * Aliases help determine well known collections, such as 'default'.
  *
  * If @service is %NULL, then [func@Service.get] will be called to get
  * the default [class@Service] proxy.
diff --git a/libsecret/secret-password.c b/libsecret/secret-password.c
index deabdf3..ac6214e 100644
--- a/libsecret/secret-password.c
+++ b/libsecret/secret-password.c
@@ -27,7 +27,7 @@
  * secret_password_store: (skip)
  * @schema: the schema for attributes
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
  * @cancellable: (nullable): optional cancellation object
@@ -159,7 +159,7 @@ on_store_backend (GObject *source,
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
  * @cancellable: (nullable): optional cancellation object
@@ -273,7 +273,7 @@ secret_password_store_binary (const SecretSchema *schema,
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @value: a [struct@Value]
  * @cancellable: (nullable): optional cancellation object
@@ -348,7 +348,7 @@ secret_password_store_finish (GAsyncResult *result,
  * secret_password_store_sync:
  * @schema: the schema for attributes
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
  * @cancellable: (nullable): optional cancellation object
@@ -413,7 +413,7 @@ secret_password_store_sync (const SecretSchema *schema,
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @password: the null-terminated password to store
  * @cancellable: (nullable): optional cancellation object
@@ -477,7 +477,7 @@ secret_password_storev_sync (const SecretSchema *schema,
  * secret_password_store_binary_sync:
  * @schema: the schema for attributes
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @value: a [struct@Value]
  * @cancellable: (nullable): optional cancellation object
@@ -535,7 +535,7 @@ secret_password_store_binary_sync (const SecretSchema *schema,
  * @schema: (nullable): the schema for attributes
  * @attributes: (element-type utf8 utf8): the attribute keys and values
  * @collection: (nullable): a collection alias, or D-Bus object path of the
- *              collection where to store the secret
+ *   collection where to store the secret
  * @label: label for the secret
  * @value: a [struct@Value]
  * @cancellable: (nullable): optional cancellation object
diff --git a/libsecret/secret-paths.c b/libsecret/secret-paths.c
index f39f6c7..8081819 100644
--- a/libsecret/secret-paths.c
+++ b/libsecret/secret-paths.c
@@ -112,7 +112,7 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result,
  *
  * Get a new collection proxy for a collection in the secret service.
  *
- * If @service is %NULL, then [funcService.get_sync] will be called to get
+ * If @service is %NULL, then [func@Service.get_sync] will be called to get
  * the default [class@Service] proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -163,7 +163,7 @@ secret_collection_new_for_dbus_path_sync (SecretService *service,
  *
  * Get a new item proxy for a secret item in the secret service.
  *
- * If @service is %NULL, then [funcService.get] will be called to get
+ * If @service is %NULL, then [func@Service.get] will be called to get
  * the default [class@Service] proxy.
  *
  * This method will return immediately and complete asynchronously.
@@ -240,7 +240,7 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result,
  *
  * Get a new item proxy for a secret item in the secret service.
  *
- * If @service is %NULL, then [funcService.get_sync] will be called to get
+ * If @service is %NULL, then [func@Service.get_sync] will be called to get
  * the default [class@Service] proxy.
  *
  * This method may block indefinitely and should not be used in user interface
@@ -311,8 +311,10 @@ on_search_items_complete (GObject *source,
  * @user_data: data to pass to the callback
  *
  * Search for items in @collection matching the @attributes, and return their
- * DBus object paths. Only the specified collection is searched. The @attributes
- * should be a table of string keys and string values.
+ * DBus object paths.
+ *
+ * Only the specified collection is searched. The @attributes should be a table
+ * of string keys and string values.
  *
  * This function returns immediately and completes asynchronously.
  *
@@ -406,8 +408,9 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection,
  * @error: location to place error on failure
  *
  * Search for items matching the @attributes in @collection, and return their
- * DBus object paths. The @attributes should be a table of string keys and
- * string values.
+ * DBus object paths.
+ *
+ * The @attributes should be a table of string keys and string values.
  *
  * This function may block indefinitely. Use the asynchronous version
  * in user interface threads.
@@ -462,6 +465,7 @@ secret_collection_search_for_dbus_paths_sync (SecretCollection *collection,
  * @user_data: data to pass to the callback
  *
  * Search for items matching the @attributes, and return their D-Bus object paths.
+ *
  * All collections are searched. The @attributes should be a table of string keys
  * and string values.
  *
@@ -528,11 +532,11 @@ _secret_service_search_for_paths_variant (SecretService *self,
  * @self: the secret service
  * @result: asynchronous result passed to callback
  * @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.
+ *   location to place an array of D-Bus object paths for matching
+ *   items which were locked.
  * @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.
+ *   location to place an array of D-Bus object paths for matching
+ *   items which were locked.
  * @error: location to place error on failure
  *
  * Complete asynchronous operation to search for items, and return their
@@ -592,16 +596,18 @@ secret_service_search_for_dbus_paths_finish (SecretService *self,
  * @attributes: (element-type utf8 utf8): search for items matching these attributes
  * @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.
+ *   location to place an array of D-Bus object paths for matching
+ *   items which were locked.
  * @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.
+ *   location to place an array of D-Bus object paths for matching
+ *   items which were locked.
  * @error: location to place error on failure
  *
  * Search for items matching the @attributes, and return their D-Bus object
- * paths. All collections are searched. The @attributes should be a table of
- * string keys and string values.
+ * paths.
+ *
+ * All collections are searched. The @attributes should be a table of string
+ * keys and string values.
  *
  * This function may block indefinitely. Use the asynchronous version
  * in user interface threads.
@@ -904,7 +910,7 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self,
  * Stability: Unstable
  *
  * Returns: (transfer full) (element-type utf8 Secret.Value): a newly
- *   allocated hash table of item_path keys to [struct@Value]
+ *   allocated hash table of item path keys to [struct@Value]
  *   values.
  */
 GHashTable *
@@ -1135,8 +1141,8 @@ _secret_service_xlock_paths_finish (SecretService *self,
  * @paths: (array zero-terminated=1): the D-Bus object paths of the items or collections to lock
  * @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
+ *   location to place array of D-Bus paths of items or collections
+ *   that were locked
  * @error: location to place an error on failure
  *
  * Lock items or collections in the secret service.
@@ -1231,8 +1237,8 @@ secret_service_lock_dbus_paths (SecretService *self,
  * @self: the secret service
  * @result: asynchronous result passed to the callback
  * @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
+ *   location to place array of D-Bus paths of items or collections
+ *   that were locked
  * @error: location to place an error on failure
  *
  * Complete asynchronous operation to lock items or collections in the secret
@@ -1262,11 +1268,11 @@ secret_service_lock_dbus_paths_finish (SecretService *self,
  * secret_service_unlock_dbus_paths_sync: (skip)
  * @self: the secret service
  * @paths: (array zero-terminated=1): the D-Bus object paths of the items or
- *         collections to unlock
+ *   collections to unlock
  * @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
+ *   location to place array of D-Bus paths of items or collections
+ *   that were unlocked
  * @error: location to place an error on failure
  *
  * Unlock items or collections in the secret service.
@@ -1322,7 +1328,7 @@ secret_service_unlock_dbus_paths_sync (SecretService *self,
  * secret_service_unlock_dbus_paths: (skip)
  * @self: the secret service
  * @paths: (array zero-terminated=1): the D-Bus paths for items or
- *         collections to unlock
+ *   collections to unlock
  * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
@@ -1363,8 +1369,8 @@ secret_service_unlock_dbus_paths (SecretService *self,
  * @self: the secret service
  * @result: asynchronous result passed to the callback
  * @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
+ *   location to place array of D-Bus paths of items or collections
+ *   that were unlocked
  * @error: location to place an error on failure
  *
  * Complete asynchronous operation to unlock items or collections in the secret
@@ -1688,9 +1694,9 @@ on_create_collection_called (GObject *source,
  * secret_service_create_collection_dbus_path: (skip)
  * @self: a secret service object
  * @properties: (element-type utf8 GLib.Variant): hash table of properties for
- *              the new collection
+ *   the new collection
  * @alias: (nullable): an alias to check for before creating the new
- *         collection, or to assign to the new collection
+ *   collection, or to assign to the new collection
  * @flags: not currently used
  * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
@@ -1805,9 +1811,9 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
  * secret_service_create_collection_dbus_path_sync: (skip)
  * @self: a secret service object
  * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
- *              for the new collection
+ *   for the new collection
  * @alias: (nullable): an alias to check for before creating the new
- *         collection, or to assign to the new collection
+ *   collection, or to assign to the new collection
  * @flags: not currently used
  * @cancellable: (nullable): optional cancellation object
  * @error: location to place an error on failure
@@ -1837,7 +1843,7 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
  * Stability: Unstable
  *
  * Returns: (transfer full): a new string containing the D-Bus object path
- *          of the collection
+ *   of the collection
  */
 gchar *
 secret_service_create_collection_dbus_path_sync (SecretService *self,
@@ -1992,7 +1998,7 @@ on_create_item_session (GObject *source,
  * @self: a secret service object
  * @collection_path: the D-Bus object path of the collection in which to create item
  * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
- *              for the new collection
+ *   for the new collection
  * @value: the secret value to store in the item
  * @flags: flags for the creation of the new item
  * @cancellable: (nullable): optional cancellation object
@@ -2114,7 +2120,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
  * @self: a secret service object
  * @collection_path: the D-Bus path of the collection in which to create item
  * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
- *              for the new collection
+ *   for the new collection
  * @value: the secret value to store in the item
  * @flags: flags for the creation of the new item
  * @cancellable: (nullable): optional cancellation object
@@ -2143,7 +2149,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
  * Stability: Unstable
  *
  * Returns: (transfer full): a new string containing the D-Bus object path
- *          of the item
+ *   of the item
  */
 gchar *
 secret_service_create_item_dbus_path_sync (SecretService *self,
@@ -2187,9 +2193,10 @@ secret_service_create_item_dbus_path_sync (SecretService *self,
  * @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'. This method looks up the
- * dbus object path of the well known collection.
+ * Lookup which collection is assigned to this alias.
+ *
+ * Aliases help determine well known collections, such as 'default'. This method
+ * looks up the dbus object path of the well known collection.
  *
  * This method will return immediately and complete asynchronously.
  *
@@ -2219,7 +2226,9 @@ secret_service_read_alias_dbus_path (SecretService *self,
  * @error: location to place error on failure
  *
  * Finish an asynchronous operation to lookup which collection is assigned
- * to an alias. This method returns the DBus object path of the collection
+ * to an alias.
+ *
+ * This method returns the DBus object path of the collection
  *
  * Stability: Unstable
  *
@@ -2258,9 +2267,10 @@ secret_service_read_alias_dbus_path_finish (SecretService *self,
  * @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'. This method returns the dbus
- * object path of the collection.
+ * Lookup which collection is assigned to this alias.
+ *
+ * Aliases help determine well known collections, such as 'default'. This method
+ * returns the dbus object path of the collection.
  *
  * This method may block and should not be used in user interface threads.
  *
@@ -2375,13 +2385,14 @@ secret_service_set_alias_to_dbus_path_finish (SecretService *self,
  * @self: a secret service object
  * @alias: the alias to assign the collection to
  * @collection_path: (nullable): the D-Bus object path of the collection to
- *                   assign to the alias
+ *   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'. This method takes the dbus object
- * path of the collection to assign to the alias.
+ * Assign a collection to this alias.
+ *
+ * Aliases help determine well known collections, such as 'default'. This method
+ * takes the dbus object path of the collection to assign to the alias.
  *
  * This method may block and should not be used in user interface threads.
  *
diff --git a/libsecret/secret-prompt.c b/libsecret/secret-prompt.c
index c40ce5d..e64520e 100644
--- a/libsecret/secret-prompt.c
+++ b/libsecret/secret-prompt.c
@@ -119,10 +119,11 @@ _secret_prompt_instance (SecretService *service,
  * @return_type: the variant type of the prompt result
  * @error: location to place an error on failure
  *
- * Runs a prompt and performs the prompting. Returns a variant result if the
- * prompt was completed and not dismissed. The type of result depends on the
- * action the prompt is completing, and is defined in the Secret Service DBus
- * API specification.
+ * Runs a prompt and performs the prompting.
+ *
+ * Returns a variant result if the prompt was completed and not dismissed. The
+ * type of result depends on the action the prompt is completing, and is defined
+ * in the Secret Service DBus API specification.
  *
  * If @window_id is non-null then it is used as an XWindow id on Linux. The API
  * expects this id to be converted to a string using the `%d` printf format. The
@@ -179,10 +180,11 @@ secret_prompt_run (SecretPrompt *self,
  * @return_type: the variant type of the prompt result
  * @error: location to place an error on failure
  *
- * Runs a prompt and performs the prompting. Returns a variant result if the
- * prompt was completed and not dismissed. The type of result depends on the
- * action the prompt is completing, and is defined in the Secret Service DBus
- * API specification.
+ * Runs a prompt and performs the prompting.
+ *
+ * Returns a variant result if the prompt was completed and not dismissed. The
+ * type of result depends on the action the prompt is completing, and is defined
+ * in the Secret Service DBus API specification.
  *
  * If @window_id is non-null then it is used as an XWindow id on Linux. The API
  * expects this id to be converted to a string using the `%d` printf format. The
@@ -402,8 +404,9 @@ on_prompt_cancelled (GCancellable *cancellable,
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
- * Runs a prompt and performs the prompting. Returns %TRUE if the prompt
- * was completed and not dismissed.
+ * Runs a prompt and performs the prompting.
+ *
+ * Returns %TRUE if the prompt was completed and not dismissed.
  *
  * If @window_id is non-null then it is used as an XWindow id on Linux. The API
  * expects this id to be converted to a string using the `%d` printf format. The
diff --git a/libsecret/secret-retrievable.c b/libsecret/secret-retrievable.c
index d64285b..714ad33 100644
--- a/libsecret/secret-retrievable.c
+++ b/libsecret/secret-retrievable.c
@@ -18,9 +18,9 @@
 #include "secret-private.h"
 
 /**
- * SecretRetrievable
+ * SecretRetrievable:
  *
- * A read-only secret item
+ * A read-only view of a secret item in the Secret Service.
  *
  * #SecretRetrievable provides a read-only view of a secret item
  * stored in the Secret Service.
@@ -30,13 +30,6 @@
  * [method@Retrievable.retrieve_secret_finish].
  *
  * Stability: Stable
- */
-
-/**
- * SecretRetrievable:
- *
- * An object representing a read-only view of a secret item in the
- * Secret Service.
  *
  * Since: 0.19.0
  */
@@ -45,9 +38,9 @@
  * SecretRetrievableInterface:
  * @parent_iface: the parent interface
  * @retrieve_secret: implementation of [method@Retrievable.retrieve_secret],
- *                   required
+ *   required
  * @retrieve_secret_finish: implementation of
- *                   [method@Retrievable.retrieve_secret_finish], required
+ *   [method@Retrievable.retrieve_secret_finish], required
  *
  * The interface for #SecretRetrievable.
  *
@@ -62,8 +55,10 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface)
 	/**
 	 * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) (attributes org.gtk.Property.get=secret_retrievable_get_attributes)
 	 *
-	 * The attributes set on this item. Attributes are used to locate an
-	 * item. They are not guaranteed to be stored or transferred securely.
+	 * The attributes set on this item.
+	 *
+	 * Attributes are used to locate an item. They are not guaranteed to be
+	 * stored or transferred securely.
 	 *
 	 * Since: 0.19.0
 	 */
@@ -266,8 +261,10 @@ secret_retrievable_get_label (SecretRetrievable *self)
  * secret_retrievable_get_created: (attributes org.gtk.Method.get_property=created)
  * @self: a retrievable object
  *
- * Get the created date and time of the object. The return value is
- * the number of seconds since the unix epoch, January 1st 1970.
+ * Get the created date and time of the object.
+ *
+ * The return value is the number of seconds since the unix epoch, January 1st
+ * 1970.
  *
  * Returns: the created date and time
  *
@@ -288,8 +285,10 @@ secret_retrievable_get_created (SecretRetrievable *self)
  * secret_retrievable_get_modified: (attributes org.gtk.Method.get_property=modified)
  * @self: a retrievable object
  *
- * Get the modified date and time of the object. The return value is
- * the number of seconds since the unix epoch, January 1st 1970.
+ * Get the modified date and time of the object.
+ *
+ * The return value is the number of seconds since the unix epoch, January 1st
+ * 1970.
  *
  * Returns: the modified date and time
  *
diff --git a/libsecret/secret-schema.c b/libsecret/secret-schema.c
index 32967bf..7e21106 100644
--- a/libsecret/secret-schema.c
+++ b/libsecret/secret-schema.c
@@ -23,10 +23,73 @@
 #include "egg/egg-secure-memory.h"
 
 /**
+ * SecretSchema:
+ * @name: the dotted name of the schema
+ * @flags: flags for the schema
+ * @attributes:  the attribute names and types of those attributes
+ *
+ * Represents a set of attributes that are stored with an item.
+ *
+ * These schemas are used for interoperability between various services storing
+ * the same types of items.
+ *
+ * Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a
+ * set of attributes, and types (string, integer, boolean) for those attributes.
+ *
+ * Attributes are stored as strings in the Secret Service, and the attribute types
+ * simply define standard ways to store integer and boolean values as strings.
+ * Attributes are represented in libsecret via a [struct@GLib.HashTable] with
+ * string keys and values. Even for values that defined as an integer or boolean in
+ * the schema, the attribute values in the [struct@GLib.HashTable] are strings.
+ * Boolean values are stored as the strings 'true' and 'false'. Integer values are
+ * stored in decimal, with a preceding negative sign for negative integers.
+ *
+ * Schemas are handled entirely on the client side by this library. The name of the
+ * schema is automatically stored as an attribute on the item.
+ *
+ * Normally when looking up passwords only those with matching schema names are
+ * returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag,
+ * then lookups will not check that the schema name matches that on the item, only
+ * the schema's attributes are matched. This is useful when you are looking up
+ * items that are not stored by the libsecret library. Other libraries such as
+ * libgnome-keyring don't store the schema name.
+ *
+ * Additional schemas can be defined via the %SecretSchema structure like this:
+ *
+ * ```c
+ * // in a header:
+ *
+ * const SecretSchema * example_get_schema (void) G_GNUC_CONST;
+ *
+ * #define EXAMPLE_SCHEMA  example_get_schema ()
+ *
+ *
+ * // in a .c file
+ *
+ * const SecretSchema *
+ * example_get_schema (void)
+ * {
+ *     static const SecretSchema the_schema = {
+ *         "org.example.Password", SECRET_SCHEMA_NONE,
+ *         {
+ *             {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
+ *             {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
+ *             {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
+ *             {  NULL, 0 },
+ *         }
+ *     };
+ *     return &the_schema;
+ * }
+ * ```
+ *
+ * Stability: Stable
+ */
+
+/**
  * SecretSchemaFlags:
  * @SECRET_SCHEMA_NONE: no flags for the schema
  * @SECRET_SCHEMA_DONT_MATCH_NAME: don't match the schema name when looking up or
- *                                 removing passwords
+ *   removing passwords
  *
  * Flags for a #SecretSchema definition.
  */
@@ -45,9 +108,11 @@
  * @SECRET_SCHEMA_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
  * @SECRET_SCHEMA_ATTRIBUTE_STRING: a utf-8 string attribute
  *
- * The type of an attribute in a #SecretSchema. Attributes are stored as strings
- * in the Secret Service, and the attribute types simply define standard ways
- * to store integer and boolean values as strings.
+ * The type of an attribute in a [struct@SecretSchema].
+ *
+ * Attributes are stored as strings in the Secret Service, and the attribute
+ * types simply define standard ways to store integer and boolean values as
+ * strings.
  */
 
 static SecretSchemaAttribute *
@@ -269,8 +334,9 @@ _secret_schema_ref_if_nonstatic (const SecretSchema *schema)
  * secret_schema_unref:
  * @schema: the schema to reference
  *
- * Releases a reference to the #SecretSchema. If the last reference is
- * released then the schema will be freed.
+ * Releases a reference to the #SecretSchema.
+ *
+ * If the last reference is released then the schema will be freed.
  *
  * It is not normally necessary to call this function from C code, and is
  * mainly present for the sake of bindings. It is an error to call this for
diff --git a/libsecret/secret-service.c b/libsecret/secret-service.c
index bdb8bd7..aabbac7 100644
--- a/libsecret/secret-service.c
+++ b/libsecret/secret-service.c
@@ -76,16 +76,16 @@
  * SecretServiceClass:
  * @parent_class: the parent class
  * @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated
- *                    by the #SecretService proxy
+ *   by the #SecretService proxy
  * @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the
- *              #SecretService proxy
+ *   #SecretService proxy
  * @prompt_async: called to perform asynchronous prompting when necessary
  * @prompt_finish: called to complete an asynchronous prompt operation
  * @prompt_sync: called to perform synchronous prompting when necessary
  * @get_collection_gtype: called to get the GObject type for collections
- *                        instantiated by the #SecretService proxy
+ *   instantiated by the #SecretService proxy
  * @get_item_gtype: called to get the GObject type for collections
- *                  instantiated by the #SecretService proxy
+ *   instantiated by the #SecretService proxy
  *
  * The class for #SecretService.
  */
@@ -94,9 +94,9 @@
  * SecretServiceFlags:
  * @SECRET_SERVICE_NONE: no flags for initializing the #SecretService
  * @SECRET_SERVICE_OPEN_SESSION: establish a session for transfer of secrets
- *                               while initializing the #SecretService
+ *   while initializing the #SecretService
  * @SECRET_SERVICE_LOAD_COLLECTIONS: load collections while initializing the
- *                                   #SecretService
+ *   #SecretService
  *
  * Flags which determine which parts of the #SecretService proxy are initialized
  * during a [func@Service.get] or [func@Service.open] operation.
@@ -585,8 +585,9 @@ secret_service_class_init (SecretServiceClass *klass)
 	 * SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections)
 	 *
 	 * A list of [class@Collection] objects representing the collections in
-	 * the Secret Service. This list may be %NULL if the collections have
-	 * not been loaded.
+	 * the Secret Service.
+	 *
+	 * This list may be %NULL if the collections have not been loaded.
 	 *
 	 * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS
 	 * initialization flag when calling the [func@Service.get] or
@@ -946,8 +947,9 @@ secret_service_backend_iface (SecretBackendInterface *iface)
  * @callback: called when the operation completes
  * @user_data: data to be passed to the callback
  *
- * Get a #SecretService proxy for the Secret Service. If such a proxy object
- * already exists, then the same proxy is returned.
+ * Get a #SecretService proxy for the Secret Service.
+ *
+ * If such a proxy object already exists, then the same proxy is returned.
  *
  * If @flags contains any flags of which parts of the secret service to
  * ensure are initialized, then those will be initialized before completing.
@@ -1043,8 +1045,9 @@ secret_service_get_finish (GAsyncResult *result,
  * @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
- * already exists, then the same proxy is returned.
+ * Get a #SecretService proxy for the Secret Service.
+ *
+ * If such a proxy object already exists, then the same proxy is returned.
  *
  * If @flags contains any flags of which parts of the secret service to
  * ensure are initialized, then those will be initialized before returning.
@@ -1362,7 +1365,7 @@ _secret_service_take_session (SecretService *self,
  * [method@Service.ensure_session] to establish a session.
  *
  * Returns: (nullable): a string representing the algorithms for transferring
- *          secrets
+ *   secrets
  */
 const gchar *
 secret_service_get_session_algorithms (SecretService *self)
@@ -1419,7 +1422,9 @@ secret_service_get_session_dbus_path (SecretService *self)
  * @user_data: data to be passed to the callback
  *
  * Ensure that the #SecretService proxy has established a session with the
- * Secret Service. This session is used to transfer secrets.
+ * Secret Service.
+ *
+ * This session is used to transfer secrets.
  *
  * It is not normally necessary to call this method, as the session is
  * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION
@@ -1491,7 +1496,9 @@ secret_service_ensure_session_finish (SecretService *self,
  * @error: location to place an error on failure
  *
  * Ensure that the #SecretService proxy has established a session with the
- * Secret Service. This session is used to transfer secrets.
+ * Secret Service.
+ *
+ * This session is used to transfer secrets.
  *
  * It is not normally necessary to call this method, as the session is
  * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION
@@ -1632,8 +1639,9 @@ on_ensure_collection (GObject *source,
  * @user_data: data to be passed to the callback
  *
  * Ensure that the #SecretService proxy has loaded all the collections present
- * in the Secret Service. This affects the result of
- * [method@Service.get_collections].
+ * in the Secret Service.
+ *
+ * This affects the result of [method@Service.get_collections].
  *
  * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
  * [func@Service.get_sync] in order to ensure that the collections have been
@@ -1729,8 +1737,9 @@ secret_service_load_collections_finish (SecretService *self,
  * @error: location to place an error on failure
  *
  * Ensure that the #SecretService proxy has loaded all the collections present
- * in the Secret Service. This affects the result of
- * [method@Service.get_collections].
+ * in the Secret Service.
+ *
+ * This affects the result of [method@Service.get_collections].
  *
  * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
  * [func@Service.get_sync] in order to ensure that the collections have been
@@ -1908,6 +1917,7 @@ secret_service_prompt_finish (SecretService *self,
  * @self: the secret service
  *
  * Get the GObject type for collections instantiated by this service.
+ *
  * This will always be either [class@Collection] or derived from it.
  *
  * Returns: the gobject type for collections
@@ -1936,6 +1946,7 @@ secret_service_get_collection_gtype (SecretService *self)
  * @self: the service
  *
  * Get the GObject type for items instantiated by this service.
+ *
  * This will always be either [class@Item] or derived from it.
  *
  * Returns: the gobject type for items
diff --git a/libsecret/secret-util.c b/libsecret/secret-util.c
index 3b601bc..4e6f2bb 100644
--- a/libsecret/secret-util.c
+++ b/libsecret/secret-util.c
@@ -20,36 +20,22 @@
 #include <string.h>
 
 /**
- * SecretError
- *
- * libsecret errors
- *
- * Various errors reported by the libsecret library. No error returned from
- * the libsecret API is suitable for direct display to the user. It is up
- * to the application to handle them appropriately.
- *
- * Stability: Stable
- */
-
-/**
- * SECRET_ERROR:
- *
- * The error domain quark which denotes libsecret specific errors from the
- * #SecretError enumeration.
- */
-
-/**
  * SecretError:
  * @SECRET_ERROR_PROTOCOL: received an invalid data or message from the Secret
- *                         Service
+ *   Service
  * @SECRET_ERROR_IS_LOCKED: the item or collection is locked and the operation
- *                          cannot be performed
- * @SECRET_ERROR_NO_SUCH_OBJECT: no such item or collection found in the
- *                               Secret Service
+ *   cannot be performed
+ * @SECRET_ERROR_NO_SUCH_OBJECT: no such item or collection found in the Secret
+ *   Service
  * @SECRET_ERROR_ALREADY_EXISTS: a relevant item or collection already exists
+ * @SECRET_ERROR_INVALID_FILE_FORMAT: the file format is not valid
+ *
+ * Errors returned by the Secret Service.
  *
- * Errors returned by the Secret Service. None of the errors are appropriate
- * for display to the user.
+ * None of the errors are appropriate for display to the user. It is up to the
+ * application to handle them appropriately.
+ *
+ * Stability: Stable
  */
 
 static void
@@ -86,6 +72,13 @@ _secret_list_get_type (void)
 
 }
 
+/**
+ * secret_error_get_quark:
+ *
+ * Get the error quark.
+ *
+ * Returns: the quark
+ */
 GQuark
 secret_error_get_quark (void)
 {
diff --git a/libsecret/secret-value.c b/libsecret/secret-value.c
index 19a2131..a6f3760 100644
--- a/libsecret/secret-value.c
+++ b/libsecret/secret-value.c
@@ -75,8 +75,9 @@ secret_value_get_type (void)
  * @length: the length of the data
  * @content_type: the content type of the data
  *
- * Create a #SecretValue for the secret data passed in. The secret data is
- * copied into non-pageable 'secure' memory.
+ * Create a #SecretValue for the secret data passed in.
+ *
+ * The secret data is copied into non-pageable 'secure' memory.
  *
  * If the length is less than zero, then @secret is assumed to be
  * null-terminated.
@@ -110,8 +111,10 @@ secret_value_new (const gchar *secret,
  * @content_type: the content type of the data
  * @destroy: function to call to free the secret data
  *
- * Create a #SecretValue for the secret data passed in. The secret data is
- * not copied, and will later be freed with the @destroy function.
+ * Create a #SecretValue for the secret data passed in.
+ *
+ * The secret data is not copied, and will later be freed with the @destroy
+ * function.
  *
  * If the length is less than zero, then @secret is assumed to be
  * null-terminated.
@@ -146,9 +149,11 @@ secret_value_new_full (gchar *secret,
  * @value: the value
  * @length: the length of the secret
  *
- * Get the secret data in the #SecretValue. The value is not necessarily
- * null-terminated unless it was created with [ctor@Value.new] or a
- * null-terminated string was passed to [ctor@Value.new_full].
+ * Get the secret data in the #SecretValue.
+ *
+ * The value is not necessarily null-terminated unless it was created with
+ * [ctor@Value.new] or a null-terminated string was passed to
+ * [ctor@Value.new_full].
  *
  * Returns: (array length=length) (element-type guint8): the secret data
  */
@@ -167,7 +172,9 @@ secret_value_get (SecretValue *value,
  * @value: the value
  *
  * Get the secret data in the #SecretValue if it contains a textual
- * value. The content type must be `text/plain`.
+ * value.
+ *
+ * The content type must be `text/plain`.
  *
  * Returns: (nullable): the content type
  */
@@ -202,8 +209,10 @@ secret_value_get_content_type (SecretValue *value)
  * secret_value_ref:
  * @value: value to reference
  *
- * Add another reference to the #SecretValue. For each reference
- * [method@Value.unref] should be called to unreference the value.
+ * Add another reference to the #SecretValue.
+ *
+ * For each reference [method@Value.unref] should be called to unreference the
+ * value.
  *
  * Returns: (transfer full): the value
  */
@@ -219,8 +228,9 @@ secret_value_ref (SecretValue *value)
  * secret_value_unref:
  * @value: (type Secret.Value): value to unreference
  *
- * Unreference a #SecretValue. When the last reference is gone, then
- * the value will be freed.
+ * Unreference a #SecretValue.
+ *
+ * When the last reference is gone, then the value will be freed.
  */
 void
 secret_value_unref (gpointer value)
@@ -253,7 +263,7 @@ is_password_value (SecretValue *value)
 /**
  * secret_value_unref_to_password:
  * @value: the value
- * @length: the length of the secret
+ * @length: (inout): the length of the secret
  *
  * Unreference a #SecretValue and steal the secret data in
  * #SecretValue as nonpageable memory.
diff --git a/libsecret/secret-version.h.in b/libsecret/secret-version.h.in
index 8dae6a5..810d11e 100644
--- a/libsecret/secret-version.h.in
+++ b/libsecret/secret-version.h.in
@@ -46,8 +46,8 @@
  * @minor: minor version to be satisfied
  * @micro: micro version to be satisfied
  *
- * Returns: %TRUE if using libsecret is newer than or equal to the
- *          given version
+ * Returns `TRUE` if using libsecret is newer than or equal to the
+ * given version.
  */
 #define SECRET_CHECK_VERSION(major, minor, micro)       \
     (SECRET_MAJOR_VERSION > (major) ||                  \