Fix up documentation

docs/reference/libsecret/libsecret-sections.txt

@@ -127,6 +127,7 @@ secret_password_free
 <SECTION>
 <FILE>secret-schema</FILE>
 <INCLUDE>secret/secret.h</INCLUDE>
+SECRET_SCHEMA_NOTE
 SecretSchema
 SecretSchemaFlags
 SecretSchemaAttribute

library/secret-collection.c

@@ -58,12 +58,10 @@
 
 /**
  * SecretCollectionFlags:
- * @SECRET_COLLECTION_NONE: no flags for initializing the #SecretCollection
+ * @SECRET_COLLECTION_NONE: no flags
- * @SECRET_COLLECTION_LOAD_ITEMS: load items while initializing the
+ * @SECRET_COLLECTION_LOAD_ITEMS: items have or should be loaded
- *                                #SecretCollection
  *
- * Flags which determine which parts of the #SecretCollection proxy are initialized
+ * Flags which determine which parts of the #SecretCollection proxy are initialized.
- * during a secret_collection_new() or secret_collection_new_sync() operation.
  */
 
 /**
@@ -773,9 +771,8 @@ on_load_item (GObject *source,
  * in the Secret Service. This affects the result of
  * secret_collection_get_items().
  *
- * You can also pass the %SECRET_COLLECTION_LOAD_ITEMS to
+ * For collections returned from secret_service_get_collections() the items
- * secret_collection_new() in order to ensure that the collections have been
+ * will have already been loaded.
- * loaded by the time you get the #SecretCollection proxy.
  *
  * This method will return immediately and complete asynchronously.
  */
@@ -866,9 +863,8 @@ secret_collection_load_items_finish (SecretCollection *self,
  * in the Secret Service. This affects the result of
  * secret_collection_get_items().
  *
- * You can also pass the %SECRET_COLLECTION_LOAD_ITEMS to
+ * For collections returned from secret_service_get_collections() the items
- * secret_collection_new_sync() in order to ensure that the items have been
+ * will have already been loaded.
- * loaded by the time you get the #SecretCollection proxy.
  *
  * This method may block indefinitely and should not be used in user interface
  * threads.

library/secret-item.c

@@ -68,11 +68,10 @@
 
 /**
  * SecretItemFlags:
- * @SECRET_ITEM_NONE: no flags for initializing the #SecretItem
+ * @SECRET_ITEM_NONE: no flags
- * @SECRET_ITEM_LOAD_SECRET: load the secret when initializing the #SecretItem
+ * @SECRET_ITEM_LOAD_SECRET: a secret has been (or should be) loaded for #SecretItem
  *
- * Flags which determine which parts of the #SecretItem proxy are initialized
+ * Flags which determine which parts of the #SecretItem proxy are initialized.
- * during a secret_item_new() operation.
  */
 
 enum {
@@ -1072,8 +1071,7 @@ secret_item_get_service (SecretItem *self)
  * 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 secret_item_load_secret() method. You can also
+ * To load the secret call the secret_item_load_secret() method.
- * pass the %SECRET_ITEM_LOAD_SECRET flag to secret_item_new().
  *
  * Returns: (transfer full) (allow-none): the secret value which should be
  *          released with secret_value_unref(), or %NULL
@@ -1185,9 +1183,7 @@ on_load_ensure_session (GObject *source,
  * Load the secret value of this item.
  *
  * Each item has a single secret which might be a password or some
- * other secret binary value. You can load the secret value on creation of
+ * other secret binary value.
- * a secret item proxy by passing the %SECRET_ITEM_LOAD_SECRET flag to the
- * secret_item_new() method.
  *
  * This function will fail if the secret item is locked.
  *
@@ -1257,9 +1253,7 @@ secret_item_load_secret_finish (SecretItem *self,
  * Load the secret value of this item.
  *
  * Each item has a single secret which might be a password or some
- * other secret binary value. You can load the secret value on creation of
+ * other secret binary value.
- * a secret item proxy by passing the %SECRET_ITEM_LOAD_SECRET flag to the
- * secret_item_new_sync() method.
  *
  * This function may block indefinetely. Use the asynchronous version
  * in user interface threads.

library/secret-methods.c

@@ -24,6 +24,16 @@
 #include "secret-types.h"
 #include "secret-value.h"
 
+/**
+ * SecretSearchFlags:
+ * @SECRET_SEARCH_NONE: no flags
+ * @SECRET_SEARCH_ALL: all the items matching the search will be returned, instead of just the first one
+ * @SECRET_SEARCH_UNLOCK: unlock locked items while searching
+ * @SECRET_SEARCH_LOAD_SECRETS: while searching load secrets for items that are not locked
+ *
+ * Various flags to be used with secret_service_search() and secret_service_search_sync().
+ */
+
 typedef struct {
 	SecretService *service;
 	GCancellable *cancellable;

library/secret-paths.c

@@ -662,7 +662,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self,
  * Get the secret value for an secret item stored in the service.
  *
  * The item is represented by its D-Bus object path. If you already have a
- * #SecretItem proxy object, use use secret_item_get_secret_sync() to more simply
+ * #SecretItem proxy object, use use secret_item_load_secret_sync() to more simply
  * get its secret value.
  *
  * This method may block indefinitely and should not be used in user interface