diff options
author | Sébastien Wilmet <swilmet@gnome.org> | 2016-05-01 13:25:49 +0200 |
---|---|---|
committer | Sébastien Wilmet <swilmet@gnome.org> | 2016-05-01 14:04:45 +0200 |
commit | 38b73d4f20b0fe033a4422745fbfe87e6b5522c0 (patch) | |
tree | 2b00d533b4219682a68e4f2b1214bdb6eb7ac4b5 | |
parent | 568cfa2aecc3e4f079541ce4889c2d545a3ca339 (diff) | |
download | gtksourceview-wip/metadata.tar.gz |
File: better document metadata APIwip/metadata
-rw-r--r-- | gtksourceview/gtksourcefile.c | 14 | ||||
-rw-r--r-- | gtksourceview/gtksourcefileloader.c | 37 |
2 files changed, 41 insertions, 10 deletions
diff --git a/gtksourceview/gtksourcefile.c b/gtksourceview/gtksourcefile.c index aaec0e64..9193c17c 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 ad994f4c..521dc687 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 */ |