Cypher_Stack/libsecret
2
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libsecret.git synced 2024-12-22 04:38:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: All docs should have a header line

Browse Source 
This line should have a single sentence.
This commit is contained in:
Maximiliano Sandoval R 2022-02-05 20:30:44 +01:00
parent e4ea94621b
commit 8726110219
No known key found for this signature in database
GPG Key ID: D64A8D747F6FE706
10 changed files with 160 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
libsecret/secret-backend.c
View File

@ -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.

28
libsecret/secret-collection.c
View File

@ -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
*/

34
libsecret/secret-item.c
View File

@ -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
*/

17
libsecret/secret-methods.c
View File

@ -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.

43
libsecret/secret-paths.c
View File

@ -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.
*

23
libsecret/secret-prompt.c
View File

@ -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

18
libsecret/secret-retrievable.c
View File

@ -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
*

13
libsecret/secret-schema.c
View File

@ -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

35
libsecret/secret-service.c
View File

@ -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

34
libsecret/secret-value.c
View File

@ -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)