docs: All docs should have a header line

This line should have a single sentence.

10 files changed, 160 insertions, 90 deletions

diff --git a/libsecret/secret-backend.c b/libsecret/secret-backend.c
index d18982a..2a74ad7 100644
--- a/libsecret/secret-backend.c
+++ b/libsecret/secret-backend.c
@@ -214,8 +214,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..bea98f6 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.
@@ -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-paths.c b/libsecret/secret-paths.c
index f39f6c7..0b044a1 100644
--- a/libsecret/secret-paths.c
+++ b/libsecret/secret-paths.c
@@ -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.
  *
@@ -600,8 +604,10 @@ secret_service_search_for_dbus_paths_finish (SecretService *self,
  * @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.
@@ -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.
  *
@@ -2379,9 +2389,10 @@ secret_service_set_alias_to_dbus_path_finish (SecretService *self,
  * @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..37d1bb6 100644
--- a/libsecret/secret-retrievable.c
+++ b/libsecret/secret-retrievable.c
@@ -62,8 +62,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 +268,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 +292,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 3c7f51a..4af52c0 100644
--- a/libsecret/secret-schema.c
+++ b/libsecret/secret-schema.c
@@ -108,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 *
@@ -332,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..5d281b9 100644
--- a/libsecret/secret-service.c
+++ b/libsecret/secret-service.c
@@ -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.
@@ -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-value.c b/libsecret/secret-value.c
index db2fcc2..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)