Round up the documentation

.gitignore

@@ -51,6 +51,7 @@ stamp*
 /docs/reference/libsecret/libsecret-unused.txt
 /docs/reference/libsecret/libsecret.args
 /docs/reference/libsecret/libsecret.hierarchy
+/docs/reference/libsecret/libsecret.interfaces
 /docs/reference/libsecret/libsecret.prerequisites
 /docs/reference/libsecret/libsecret.signals
 /docs/reference/libsecret/tmpl

docs/reference/libsecret/libsecret-docs.sgml

@@ -16,6 +16,7 @@
 	<part id="simple">
 		<title>Simple API</title>
 		<xi:include href="xml/secret-password.xml"/>
+		<xi:include href="xml/secret-schema.xml"/>
 	</part>
 
 	<part id="complete">

docs/reference/libsecret/libsecret-sections.txt

@@ -86,6 +86,8 @@ secret_error_get_type
 
 <SECTION>
 <FILE>secret-password</FILE>
+SECRET_COLLECTION_DEFAULT
+SECRET_COLLECTION_SESSION
 secret_password_store
 secret_password_storev
 secret_password_store_finish
@@ -94,29 +96,42 @@ secret_password_storev_sync
 secret_password_lookup
 secret_password_lookupv
 secret_password_lookup_finish
+secret_password_lookup_nonpageable_finish
 secret_password_lookup_sync
+secret_password_lookup_nonpageable_sync
 secret_password_lookupv_sync
+secret_password_lookupv_nonpageable_sync
 secret_password_remove
 secret_password_removev
 secret_password_remove_finish
 secret_password_remove_sync
 secret_password_removev_sync
 secret_password_free
+
 </SECTION>
 
 <SECTION>
 <FILE>secret-schema</FILE>
 SecretSchema
+SECRET_SCHEMA_IDENTIFIER_GENERIC
+SECRET_SCHEMA_IDENTIFIER_NETWORK
+SECRET_SCHEMA_IDENTIFIER_NOTE
+SECRET_SCHEMA_GENERIC
+SECRET_SCHEMA_NETWORK
+SECRET_SCHEMA_NOTE
+SecretSchemaFlags
 SecretSchemaAttribute
-SecretAttributeType
+SecretSchemaAttributeType
 secret_schema_new
 secret_schema_ref
 secret_schema_unref
 <SUBSECTION Standard>
-SECRET_TYPE_SCHEMA
 secret_schema_get_type
-SECRET_TYPE_ATTRIBUTE_TYPE
+secret_schema_attribute_get_type
-secret_attribute_type_get_type
+secret_schema_attribute_type_get_type
+secret_schema_flags_get_type
+SECRET_TYPE_SCHEMA_FLAGS
+SECRET_TYPE_SCHEMA_ATTRIBUTE_TYPE
 </SECTION>
 
 <SECTION>

library/secret-collection.c

@@ -32,7 +32,7 @@
  * A collection can be in a locked or unlocked state. Use secret_service_lock()
  * or secret_service_unlock() to lock or unlock the collection.
  *
- * Use the SecretCollection::items property or secret_service_get_items() to
+ * Use the SecretCollection::items property or secret_collection_get_items() to
  * lookup the items in the collection. There may not be any items exposed when
  * the collection is locked.
  */

library/secret-item.c

@@ -30,7 +30,7 @@
  * #SecretItem represents a secret item stored in the Secret Service.
  *
  * Each item has a value, represented by a #SecretValue, which can be
- * retrieved by secret_service_get_secret() or set by secret_service_set_secret().
+ * retrieved by secret_item_get_secret() or set by secret_item_set_secret().
  * The item is only available when the item is not locked.
  *
  * Items can be locked or unlocked using the secret_service_lock() or

library/secret-prompt.c

@@ -29,7 +29,7 @@
  * Certain actions on the Secret Service require user prompting to complete,
  * such as creating a collection, or unlocking a collection. When such a prompt
  * is necessary, then a #SecretPrompt object is created by this library, and
- * passed to the secret_service_prompt_async() method. In this way it is handled
+ * passed to the secret_service_prompt() method. In this way it is handled
  * automatically.
  *
  * In order to customize prompt handling, override the

library/secret-schema.c

@@ -32,12 +32,14 @@
  *
  * Additional schemas can be defined via the %SecretSchema structure like this:
  *
- * xxxx
+ * If the schema flags contain the %SECRET_SCHEMA_ALLOW_UNDEFINED flag, then
+ * undefined attributes are permitted.
  */
 
 /**
  * SecretSchema:
  * @identifier: the dotted identifer 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
@@ -49,6 +51,17 @@
  *
  * 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.
+ *
+ * If @flags contains the %SECRET_SCHEMA_ALLOW_UNDEFINED flag, then attributes
+ * not listed in @attributes are permitted.
+ */
+
+/**
+ * SecretSchemaFlags:
+ * @SECRET_SCHEMA_NONE: no flags for the schema
+ * @SECRET_SCHEMA_ALLOW_UNDEFINED: allow undefined attributes
+ *
+ * Flags for a #SecretSchema definition.
  */
 
 /**
@@ -60,10 +73,10 @@
  */
 
 /**
- * SecretAttributeType:
+ * SecretSchemaAttributeType:
- * @SECRET_ATTRIBUTE_BOOLEAN: a boolean attribute, stored as 'true' or 'false'
+ * @SECRET_SCHEMA_ATTRIBUTE_BOOLEAN: a boolean attribute, stored as 'true' or 'false'
- * @SECRET_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
+ * @SECRET_SCHEMA_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
- * @SECRET_ATTRIBUTE_STRING: a utf-8 string attribute
+ * @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
@@ -131,6 +144,7 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute,
 /**
  * secret_schema_new:
  * @identifier: the dotted identifier of the schema
+ * @flags: the flags for the schema
  * @attributes: (element-type utf8 Secret.SchemaAttributeType): the attribute names and types of those attributes
  *
  * Using this function is not normally necessary from C code. This is useful
@@ -145,9 +159,12 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute,
  * those attributes.
  *
  * Each key in the @attributes table should be a attribute name strings, and
- * the values in the table should be integers from the #SecretAttributeType
+ * the values in the table should be integers from the #SecretSchemaAttributeType
  * enumeration, representing the attribute type for each attribute name.
  *
+ * If @flags contains the %SECRET_SCHEMA_ALLOW_UNDEFINED flag, then attributes
+ * not listed in @attributes are permitted.
+ *
  * Returns: (transfer full): the new schema, which should be unreferenced with
  *          secret_schema_unref() when done
  */

library/secret-service.c

@@ -57,12 +57,11 @@
  * Certain actions on the Secret Service require user prompting to complete,
  * such as creating a collection, or unlocking a collection. When such a prompt
  * is necessary, then a #SecretPrompt object is created by this library, and
- * passed to the secret_service_prompt_async() method. In this way it is handled
+ * passed to the secret_service_prompt() method. In this way it is handled
  * automatically.
  *
- * In order to customize prompt handling, override the
+ * In order to customize prompt handling, override the <literal>prompt_async</literal>
- * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
+ * and <literal>prompt_finish</literal> virtual methods of the #SecretService class.
- * virtual methods of the #SecretService class.
  */
 
 /**
@@ -1410,7 +1409,7 @@ secret_service_ensure_collections_sync (SecretService *self,
  * This function is called by other parts of this library to handle prompts
  * for the various actions that can require prompting.
  *
- * Override the #SecretServiceClass::prompt_sync() virtual method
+ * Override the #SecretServiceClass <literal>prompt_sync</literal> virtual method
  * to change the behavior of the propmting. The default behavior is to simply
  * run secret_prompt_perform_sync() on the prompt.
  *
@@ -1448,7 +1447,7 @@ secret_service_prompt_sync (SecretService *self,
  * This function is called by other parts of this library to handle prompts
  * for the various actions that can require prompting.
  *
- * Override the #SecretService <literal>prompt_async()</literal> virtual method
+ * Override the #SecretServiceClass <literal>prompt_async</literal> virtual method
  * to change the behavior of the propmting. The default behavior is to simply
  * run secret_prompt_perform() on the prompt.
  */