[tracker] libtracker-miner: Finished documenting public APIs

[Martyn James Russell <mr src gnome org>]

commit 7ee5c308920b768f050e51ca644140c0c0e7bdce
Author: Martyn Russell <martyn lanedo com>
Date:   Mon Dec 15 13:13:19 2014 +0000

    libtracker-miner: Finished documenting public APIs
    
    Only 2 left, mainly because they're a NOP or don't work currently and need
    fixing.

 src/libtracker-miner/tracker-decorator.c    |   10 ++--
 src/libtracker-miner/tracker-media-art.c    |   12 ++++-
 src/libtracker-miner/tracker-miner-fs.c     |   68 +++++++++++++++++++++++++--
 src/libtracker-miner/tracker-miner-object.c |    6 +-
 src/libtracker-miner/tracker-thumbnailer.c  |   15 ++++++
 5 files changed, 95 insertions(+), 16 deletions(-)
---
diff --git a/src/libtracker-miner/tracker-decorator.c b/src/libtracker-miner/tracker-decorator.c
index 8991e97..b8978d8 100644
--- a/src/libtracker-miner/tracker-decorator.c
+++ b/src/libtracker-miner/tracker-decorator.c
@@ -34,7 +34,8 @@
  * @include: libtracker-miner/tracker-miner.h
  * @title: TrackerDecorator
  * @see_also: #TrackerDecoratorFS
- * #TrackerDecorator watches for signal updates based on file changes
+ *
+ * #TrackerDecorator watches for signal updates based on content changes
  * in the database. When new files are added initially, only simple
  * metadata exists, for example, name, size, mtime, etc. The
  * #TrackerDecorator queues files for extended metadata extraction
@@ -102,11 +103,10 @@ static void   tracker_decorator_initable_iface_init (GInitableIface   *iface);
 /**
  * tracker_decorator_error_quark:
  *
- * Quarks are used as the domain for a #GError. For all errors relating
- * to @TrackerDecorator, you can compare the domain to the return
- * value of this function.
+ * Gives the caller the #GQuark used to identify #TrackerDecorator errors
+ * in #GError structures. The #GQuark is used as the domain for the error.
  *
- * Returns: the @GQuark used for #GErrors related to @TrackerDecorator implementations.
+ * Returns: the #GQuark used for the domain of a #GError.
  *
  * Since: 0.18.
  **/
diff --git a/src/libtracker-miner/tracker-media-art.c b/src/libtracker-miner/tracker-media-art.c
index 1be85c2..c0559e9 100644
--- a/src/libtracker-miner/tracker-media-art.c
+++ b/src/libtracker-miner/tracker-media-art.c
@@ -159,6 +159,7 @@ on_error:
        }
 #endif /* HAVE_LIBMEDIAART */
 }
+
 /**
  * tracker_media_art_queue_remove:
  * @uri: URI of the file
@@ -214,9 +215,15 @@ on_timer_destroy (gpointer data)
 }
 
 /**
- * tracker_media_art_queue_execute:
+ * tracker_media_art_queue_empty:
+ * @connection: a #TrackerSparqlConnection
+ *
+ * Using @connection, find all media art associated with content in
+ * Tracker (so as not to remove media art for other processes) and
+ * remove caches for that media art.
  *
- * Process all stored media art requests.
+ * Note, this highly depends on built in support for libmediaart. If
+ * there is no support, this API does nothing.
  *
  * Since: 0.10.4
  */
@@ -224,7 +231,6 @@ void
 tracker_media_art_queue_empty (TrackerSparqlConnection *connection)
 {
        if (had_any && timer_id == 0) {
-
                timer_id = g_timeout_add_seconds_full (G_PRIORITY_LOW,
                                                       1800 /* Half an hour worth of seconds*/,
                                                       on_timer_callback,
diff --git a/src/libtracker-miner/tracker-miner-fs.c b/src/libtracker-miner/tracker-miner-fs.c
index ba4d360..28842e3 100644
--- a/src/libtracker-miner/tracker-miner-fs.c
+++ b/src/libtracker-miner/tracker-miner-fs.c
@@ -356,6 +356,16 @@ static GQuark quark_file_iri = 0;
 static GInitableIface* miner_fs_initable_parent_iface;
 static guint signals[LAST_SIGNAL] = { 0, };
 
+/**
+ * tracker_miner_fs_error_quark:
+ *
+ * Gives the caller the #GQuark used to identify #TrackerMinerFS errors
+ * in #GError structures. The #GQuark is used as the domain for the error.
+ *
+ * Returns: the #GQuark used for the domain of a #GError.
+ *
+ * Since: 1.2.
+ **/
 G_DEFINE_QUARK (TrackerMinerFSError, tracker_miner_fs_error)
 
 G_DEFINE_ABSTRACT_TYPE_WITH_CODE (TrackerMinerFS, tracker_miner_fs, TRACKER_TYPE_MINER,
@@ -3957,7 +3967,7 @@ tracker_miner_fs_force_recheck (TrackerMinerFS *fs)
  * could be changed outside between startup and shutdown of the
  * process using this API.
  *
- * The default if not set directly is that @mtime_checking is #TRUE.
+ * The default if not set directly is that @mtime_checking is %TRUE.
  *
  * Since: 0.10
  **/
@@ -3974,8 +3984,13 @@ tracker_miner_fs_set_mtime_checking (TrackerMinerFS *fs,
  * tracker_miner_fs_get_mtime_checking:
  * @fs: a #TrackerMinerFS
  *
- * Returns: #TRUE if mtime checks for directories against the database
- * are done when @fs crawls the file system, otherwise #FALSE.
+ * Returns a boolean used to identify if file modification time checks
+ * are performed when processing content. This may be set to %FALSE if
+ * working prodominently with cloud data where you can't perform these
+ * checks. By default and for local file systems, this is enabled.
+ *
+ * Returns: %TRUE if mtime checks for directories against the database
+ * are done when @fs crawls the file system, otherwise %FALSE.
  *
  * Since: 0.10
  **/
@@ -4018,6 +4033,30 @@ tracker_miner_fs_force_mtime_checking (TrackerMinerFS *fs,
                                   flags);
 }
 
+/**
+ * tracker_miner_fs_set_initial_crawling:
+ * @fs: a #TrackerMinerFS
+ * @do_initial_crawling: a #gboolean
+ *
+ * Tells the @fs that crawling the #TrackerIndexingTree should happen
+ * initially. This is actually required to set up file system monitor
+ * using technologies like inotify, etc.
+ *
+ * Setting this to #FALSE can dramatically improve the start up the
+ * crawling of the @fs.
+ *
+ * The down side is that using this consistently means that some files
+ * on the disk may be out of date with files in the database.
+ *
+ * The main purpose of this function is for systems where a @fs is
+ * running the entire time and where it is very unlikely that a file
+ * could be changed outside between startup and shutdown of the
+ * process using this API.
+ *
+ * The default if not set directly is that @do_initial_crawling is %TRUE.
+ *
+ * Since: 0.10
+ **/
 void
 tracker_miner_fs_set_initial_crawling (TrackerMinerFS *fs,
                                        gboolean        do_initial_crawling)
@@ -4027,6 +4066,20 @@ tracker_miner_fs_set_initial_crawling (TrackerMinerFS *fs,
        fs->priv->initial_crawling = do_initial_crawling;
 }
 
+/**
+ * tracker_miner_fs_get_initial_crawling:
+ * @fs: a #TrackerMinerFS
+ *
+ * Returns a boolean which indicates if the indexing tree is crawled
+ * upon start up or not. This may be set to %FALSE if working
+ * prodominently with cloud data where you can't perform these checks.
+ * By default and for local file systems, this is enabled.
+ *
+ * Returns: %TRUE if a file system structure is crawled for new
+ * updates on start up, otherwise %FALSE.
+ *
+ * Since: 0.10
+ **/
 gboolean
 tracker_miner_fs_get_initial_crawling (TrackerMinerFS *fs)
 {
@@ -4039,8 +4092,13 @@ tracker_miner_fs_get_initial_crawling (TrackerMinerFS *fs)
  * tracker_miner_fs_has_items_to_process:
  * @fs: a #TrackerMinerFS
  *
- * Returns: #TRUE if there are items to process in the internal
- * queues, otherwise #FALSE.
+ * The @fs keeps many priority queus for content it is processing.
+ * This function returns %TRUE if the sum of all (or any) priority
+ * queues is more than 0. This includes items deleted, created,
+ * updated, moved or being written back.
+ *
+ * Returns: %TRUE if there are items to process in the internal
+ * queues, otherwise %FALSE.
  *
  * Since: 0.10
  **/
diff --git a/src/libtracker-miner/tracker-miner-object.c b/src/libtracker-miner/tracker-miner-object.c
index 470f84f..360ac7c 100644
--- a/src/libtracker-miner/tracker-miner-object.c
+++ b/src/libtracker-miner/tracker-miner-object.c
@@ -215,10 +215,10 @@ static void       on_tracker_store_disappeared (GDBusConnection        *connecti
 /**
  * tracker_miner_error_quark:
  *
- * Gives the caller the #GQuark used to identify miner errors in
- * GError structures.
+ * Gives the caller the #GQuark used to identify #TrackerMiner errors
+ * in #GError structures. The #GQuark is used as the domain for the error.
  *
- * Returns: the error #GQuark
+ * Returns: the #GQuark used for the domain of a #GError.
  *
  * Since: 0.8
  **/
diff --git a/src/libtracker-miner/tracker-thumbnailer.c b/src/libtracker-miner/tracker-thumbnailer.c
index 2af4d8b..c95bacc 100644
--- a/src/libtracker-miner/tracker-thumbnailer.c
+++ b/src/libtracker-miner/tracker-thumbnailer.c
@@ -256,6 +256,21 @@ tracker_thumbnailer_init (TrackerThumbnailer *thumbnailer)
 {
 }
 
+/**
+ * tracker_thumbnailer_new:
+ *
+ * Creates a new #TrackerThumbnailer object that can be used to signal
+ * the system's thumbnailing daemon(s) via D-Bus to add or remove
+ * content that needs thumbnailing.
+ *
+ * For example, when mounting a USB thumb drive, content may not have
+ * thumbnails and this object allows the content of that thumb drive
+ * to be queued for processing.
+ *
+ * Returns: %TRUE if successfully stored to be reported, %FALSE otherwise.
+ *
+ * Since: 0.18.
+ */
 TrackerThumbnailer *
 tracker_thumbnailer_new (void)
 {