[gtksourceview/wip/metadata] File: better document metadata API

[Sébastien Wilmet <swilmet src gnome org>]

commit 38b73d4f20b0fe033a4422745fbfe87e6b5522c0
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun May 1 13:25:49 2016 +0200

    File: better document metadata API

 gtksourceview/gtksourcefile.c       |   14 +++++++++---
 gtksourceview/gtksourcefileloader.c |   37 +++++++++++++++++++++++++++++-----
 2 files changed, 41 insertions(+), 10 deletions(-)
---
diff --git a/gtksourceview/gtksourcefile.c b/gtksourceview/gtksourcefile.c
index aaec0e6..9193c17 100644
--- a/gtksourceview/gtksourcefile.c
+++ b/gtksourceview/gtksourcefile.c
@@ -679,9 +679,12 @@ gtk_source_file_is_readonly (GtkSourceFile *file)
  * @file: a #GtkSourceFile.
  * @key: the name of the metadata.
  *
- * Gets a metadata.
+ * Gets the value of a metadata. The metadata must have been loaded with a
+ * #GtkSourceFileLoader or previously set with gtk_source_file_set_metadata(),
+ * otherwise this function returns %NULL.
  *
- * Returns: (nullable): the value of the metadata, or %NULL. Free with g_free().
+ * Returns: (nullable): the value of the metadata, or %NULL if the metadata
+ *   doesn't exist. Free with g_free().
  * Since: 3.22
  */
 gchar *
@@ -712,8 +715,11 @@ gtk_source_file_get_metadata (GtkSourceFile *file,
  * @key: the name of the metadata.
  * @value: (nullable): the value of the metadata, or %NULL to unset.
  *
- * Sets a metadata. It's preferable that @key starts with a namespace, to not
- * get metadata conflicts between applications.
+ * Sets the value of a metadata. It's preferable that @key starts with a
+ * namespace, to not get metadata conflicts between applications.
+ *
+ * The new metadata value is just stored in the #GtkSourceFile object in memory.
+ * To save the metadata on disk, you need to use a #GtkSourceFileSaver.
  *
  * Since: 3.22
  */
diff --git a/gtksourceview/gtksourcefileloader.c b/gtksourceview/gtksourcefileloader.c
index ad994f4..521dc68 100644
--- a/gtksourceview/gtksourcefileloader.c
+++ b/gtksourceview/gtksourcefileloader.c
@@ -42,7 +42,8 @@
  * @See_also: #GtkSourceFile, #GtkSourceFileSaver
  *
  * A #GtkSourceFileLoader object permits to load the contents of a #GFile or a
- * #GInputStream into a #GtkSourceBuffer.
+ * #GInputStream into a #GtkSourceBuffer. It can also load the metadata of a
+ * #GFile.
  *
  * A file loader should be used only for one load operation, including errors
  * handling. If an error occurs, you can reconfigure the loader and relaunch the
@@ -59,6 +60,18 @@
  * saved somewhere (for example if you load from stdin), then you should
  * probably call gtk_text_buffer_set_modified() with %TRUE after calling
  * gtk_source_file_loader_load_finish().
+ *
+ * # Metadata
+ *
+ * By default, gtk_source_file_loader_load_async() loads also the metadata from
+ * the #GFile. The metadata cannot be loaded from a #GInputStream. If loaded
+ * successfully, the metadata is stored in the #GtkSourceFile and can be
+ * accessed with gtk_source_file_get_metadata().
+ *
+ * If the %GTK_SOURCE_FILE_LOADER_FLAGS_DO_NOT_LOAD_METADATA flag is set,
+ * gtk_source_file_loader_load_async() will not load the metadata. The metadata
+ * can be loaded independently with gtk_source_file_loader_load_metadata() or
+ * gtk_source_file_loader_load_metadata_async().
  */
 
 #if 0
@@ -1113,8 +1126,13 @@ gtk_source_file_loader_get_flags (GtkSourceFileLoader *loader)
  * @user_data: user data to pass to @callback.
  *
  * Loads asynchronously the file or input stream contents into the
- * #GtkSourceBuffer. See the #GAsyncResult documentation to know how to use this
- * function.
+ * #GtkSourceBuffer.
+ *
+ * Since version 3.22, by default this function also loads the #GFile metadata.
+ * This can be turned off with the
+ * %GTK_SOURCE_FILE_LOADER_FLAGS_DO_NOT_LOAD_METADATA flag.
+ *
+ * See the #GAsyncResult documentation to know how to use this function.
  *
  * Since: 3.14
  */
@@ -1318,7 +1336,10 @@ gtk_source_file_loader_load_finish (GtkSourceFileLoader  *loader,
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @error: location to a %NULL #GError, or %NULL.
  *
- * Loads synchronously the metadata.
+ * Loads synchronously the #GFile metadata.
+ *
+ * This function ignores whether the
+ * %GTK_SOURCE_FILE_LOADER_FLAGS_DO_NOT_LOAD_METADATA flag is set.
  *
  * Returns: whether the metadata was loaded successfully.
  * Since: 3.22
@@ -1399,8 +1420,12 @@ load_metadata_async_cb (GFile        *location,
  *   satisfied.
  * @user_data: user data to pass to @callback.
  *
- * Loads asynchronously the metadata. See the #GAsyncResult documentation to
- * know how to use this function.
+ * Loads asynchronously the #GFile metadata.
+ *
+ * This function ignores whether the
+ * %GTK_SOURCE_FILE_LOADER_FLAGS_DO_NOT_LOAD_METADATA flag is set.
+ *
+ * See the #GAsyncResult documentation to know how to use this function.
  *
  * Since: 3.22
  */