[libsecret] Fix up documentation

[Stefan Walter <stefw src gnome org>]

commit c1f860d45ff5a87f4e8205ae27c3066598d2a01a
Author: Stef Walter <stefw gnome org>
Date:   Fri Jul 6 10:21:04 2012 +0200

    Fix up documentation

 docs/reference/libsecret/libsecret-sections.txt |    1 +
 library/secret-collection.c                     |   18 +++++++-----------
 library/secret-item.c                           |   18 ++++++------------
 library/secret-methods.c                        |   10 ++++++++++
 library/secret-paths.c                          |    2 +-
 5 files changed, 25 insertions(+), 24 deletions(-)
---
diff --git a/docs/reference/libsecret/libsecret-sections.txt b/docs/reference/libsecret/libsecret-sections.txt
index bd45c41..f9bc9f5 100644
--- a/docs/reference/libsecret/libsecret-sections.txt
+++ b/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
diff --git a/library/secret-collection.c b/library/secret-collection.c
index df86730..057547f 100644
--- a/library/secret-collection.c
+++ b/library/secret-collection.c
@@ -58,12 +58,10 @@
 
 /**
  * SecretCollectionFlags:
- * @SECRET_COLLECTION_NONE: no flags for initializing the #SecretCollection
- * @SECRET_COLLECTION_LOAD_ITEMS: load items while initializing the
- *                                #SecretCollection
+ * @SECRET_COLLECTION_NONE: no flags
+ * @SECRET_COLLECTION_LOAD_ITEMS: items have or should be loaded
  *
- * Flags which determine which parts of the #SecretCollection proxy are initialized
- * during a secret_collection_new() or secret_collection_new_sync() operation.
+ * Flags which determine which parts of the #SecretCollection proxy are initialized.
  */
 
 /**
@@ -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
- * secret_collection_new() in order to ensure that the collections have been
- * loaded by the time you get the #SecretCollection proxy.
+ * For collections returned from secret_service_get_collections() the items
+ * will have already been loaded.
  *
  * 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
- * secret_collection_new_sync() in order to ensure that the items have been
- * loaded by the time you get the #SecretCollection proxy.
+ * For collections returned from secret_service_get_collections() the items
+ * will have already been loaded.
  *
  * This method may block indefinitely and should not be used in user interface
  * threads.
diff --git a/library/secret-item.c b/library/secret-item.c
index 910b652..cba4308 100644
--- a/library/secret-item.c
+++ b/library/secret-item.c
@@ -68,11 +68,10 @@
 
 /**
  * SecretItemFlags:
- * @SECRET_ITEM_NONE: no flags for initializing the #SecretItem
- * @SECRET_ITEM_LOAD_SECRET: load the secret when initializing the #SecretItem
+ * @SECRET_ITEM_NONE: no flags
+ * @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
- * during a secret_item_new() operation.
+ * Flags which determine which parts of the #SecretItem proxy are initialized.
  */
 
 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
- * pass the %SECRET_ITEM_LOAD_SECRET flag to secret_item_new().
+ * To load the secret call the secret_item_load_secret() method.
  *
  * 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
- * a secret item proxy by passing the %SECRET_ITEM_LOAD_SECRET flag to the
- * secret_item_new() method.
+ * other secret binary value.
  *
  * 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
- * a secret item proxy by passing the %SECRET_ITEM_LOAD_SECRET flag to the
- * secret_item_new_sync() method.
+ * other secret binary value.
  *
  * This function may block indefinetely. Use the asynchronous version
  * in user interface threads.
diff --git a/library/secret-methods.c b/library/secret-methods.c
index e9841ae..a7032a6 100644
--- a/library/secret-methods.c
+++ b/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;
diff --git a/library/secret-paths.c b/library/secret-paths.c
index 63bb603..ab22daf 100644
--- a/library/secret-paths.c
+++ b/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