From 87261102192086f58ba0cf2cb8942e684c972f77 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Sat, 5 Feb 2022 20:30:44 +0100 Subject: [PATCH] docs: All docs should have a header line This line should have a single sentence. --- libsecret/secret-backend.c | 5 ++-- libsecret/secret-collection.c | 28 ++++++++++++++-------- libsecret/secret-item.c | 34 ++++++++++++++++++--------- libsecret/secret-methods.c | 17 +++++++++----- libsecret/secret-paths.c | 43 +++++++++++++++++++++------------- libsecret/secret-prompt.c | 23 ++++++++++-------- libsecret/secret-retrievable.c | 18 +++++++++----- libsecret/secret-schema.c | 13 ++++++---- libsecret/secret-service.c | 35 +++++++++++++++++---------- libsecret/secret-value.c | 34 +++++++++++++++++---------- 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)