[tepl] Metadata docs: write API docs

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

commit 4c87fc2b0ffae15d7752ddc6209d5761ff79acbf
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Apr 17 20:38:56 2020 +0200

    Metadata docs: write API docs

 docs/reference/tepl-docs.xml     |  1 +
 docs/reference/tepl-sections.txt | 23 +++++++++++++
 tepl/tepl-metadata-store.c       | 71 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+)
---
diff --git a/docs/reference/tepl-docs.xml b/docs/reference/tepl-docs.xml
index 3a00cdb..dea48e0 100644
--- a/docs/reference/tepl-docs.xml
+++ b/docs/reference/tepl-docs.xml
@@ -51,6 +51,7 @@
 
     <chapter id="file-metadata">
       <title>File Metadata</title>
+      <xi:include href="xml/file-metadata.xml"/>
       <xi:include href="xml/metadata-store.xml"/>
     </chapter>
 
diff --git a/docs/reference/tepl-sections.txt b/docs/reference/tepl-sections.txt
index eb65833..d1b1554 100644
--- a/docs/reference/tepl-sections.txt
+++ b/docs/reference/tepl-sections.txt
@@ -189,6 +189,24 @@ tepl_file_loader_error_get_type
 tepl_file_loader_error_quark
 </SECTION>
 
+<SECTION>
+<FILE>file-metadata</FILE>
+TeplFileMetadata
+tepl_file_metadata_new
+tepl_file_metadata_get
+tepl_file_metadata_set
+<SUBSECTION Standard>
+TEPL_FILE_METADATA
+TEPL_FILE_METADATA_CLASS
+TEPL_FILE_METADATA_GET_CLASS
+TEPL_IS_FILE_METADATA
+TEPL_IS_FILE_METADATA_CLASS
+TEPL_TYPE_FILE_METADATA
+TeplFileMetadataClass
+TeplFileMetadataPrivate
+tepl_file_metadata_get_type
+</SECTION>
+
 <SECTION>
 <FILE>file-saver</FILE>
 TeplFileSaver
@@ -294,6 +312,11 @@ tepl_menu_shell_append_edit_actions
 <FILE>metadata-store</FILE>
 TeplMetadataStore
 tepl_metadata_store_get_singleton
+tepl_metadata_store_trim
+tepl_metadata_store_load
+tepl_metadata_store_save
+tepl_metadata_store_load_file_metadata
+tepl_metadata_store_save_file_metadata
 <SUBSECTION Standard>
 TEPL_IS_METADATA_STORE
 TEPL_IS_METADATA_STORE_CLASS
diff --git a/tepl/tepl-metadata-store.c b/tepl/tepl-metadata-store.c
index f1cc515..524acd0 100644
--- a/tepl/tepl-metadata-store.c
+++ b/tepl/tepl-metadata-store.c
@@ -25,6 +25,10 @@
  * SECTION:metadata-store
  * @Title: TeplMetadataStore
  * @Short_description: To store file metadata on disk
+ *
+ * #TeplMetadataStore permits to store file metadata on disk. It serves both as
+ * an easier replacement for GVfs metadata, and to have metadata support on
+ * platforms that don't support GVfs metadata.
  */
 
 /* This code is inspired by TeplMetadataManager, which was itself a modified
@@ -124,6 +128,23 @@ _tepl_metadata_store_unref_singleton (void)
         */
 }
 
+/**
+ * tepl_metadata_store_trim:
+ * @store: the #TeplMetadataStore.
+ * @max_number_of_locations: the maximum size, or -1 for the default value.
+ *
+ * The purpose of having a maximum size is to avoid that the store file grows
+ * indefinitely.
+ *
+ * @max_number_of_locations is the maximum number of #GFile locations for which
+ * metadata are kept. This function discards the least recently accessed
+ * metadata if needed.
+ *
+ * If @max_number_of_locations is -1, a default internal value is used that
+ * should fit most applications' needs.
+ *
+ * Since: 5.0
+ */
 void
 tepl_metadata_store_trim (TeplMetadataStore *store,
                          gint               max_number_of_locations)
@@ -169,6 +190,20 @@ tepl_metadata_store_trim (TeplMetadataStore *store,
        }
 }
 
+/**
+ * tepl_metadata_store_load:
+ * @store: the #TeplMetadataStore.
+ * @from_file: the store file.
+ * @error: location to a %NULL #GError, or %NULL.
+ *
+ * Loads synchronously the metadata from @from_file into @store.
+ *
+ * A good moment to call this function is on application startup, see the
+ * #GApplication::startup signal.
+ *
+ * Returns: whether the operation was successful.
+ * Since: 5.0
+ */
 gboolean
 tepl_metadata_store_load (TeplMetadataStore  *store,
                          GFile              *from_file,
@@ -208,6 +243,22 @@ to_string (TeplMetadataStore *store)
        return g_string_free_to_bytes (string);
 }
 
+/**
+ * tepl_metadata_store_save:
+ * @store: the #TeplMetadataStore.
+ * @to_file: the store file.
+ * @trim: if %TRUE, tepl_metadata_store_trim() is called with -1.
+ * @error: location to a %NULL #GError, or %NULL.
+ *
+ * Saves synchronously the metadata from @store to @to_file. The parent
+ * directories of @to_file are created if needed.
+ *
+ * A good moment to call this function is on application shutdown, see the
+ * #GApplication::shutdown signal.
+ *
+ * Returns: whether the operation was successful.
+ * Since: 5.0
+ */
 gboolean
 tepl_metadata_store_save (TeplMetadataStore  *store,
                          GFile              *to_file,
@@ -257,6 +308,16 @@ tepl_metadata_store_save (TeplMetadataStore  *store,
        return ok;
 }
 
+/**
+ * tepl_metadata_store_load_file_metadata:
+ * @store: the #TeplMetadataStore.
+ * @location: a #GFile.
+ * @file_metadata: a #TeplFileMetadata.
+ *
+ * Copies the metadata stored in @store for @location into @file_metadata.
+ *
+ * Since: 5.0
+ */
 void
 tepl_metadata_store_load_file_metadata (TeplMetadataStore *store,
                                        GFile             *location,
@@ -276,6 +337,16 @@ tepl_metadata_store_load_file_metadata (TeplMetadataStore *store,
        }
 }
 
+/**
+ * tepl_metadata_store_save_file_metadata:
+ * @store: the #TeplMetadataStore.
+ * @location: a #GFile.
+ * @file_metadata: a #TeplFileMetadata.
+ *
+ * Copies the metadata from @file_metadata into @store for @location.
+ *
+ * Since: 5.0
+ */
 void
 tepl_metadata_store_save_file_metadata (TeplMetadataStore *store,
                                        GFile             *location,