GNOME.org
 

[tracker] Fill in missing libtracker-miner docs.

commit df178b3852807b0277d2c135f8540c6013478121
Author: Carlos Garnacho <carlos lanedo com>
Date:   Mon Oct 5 16:29:52 2009 +0200

    Fill in missing libtracker-miner docs.

 .../libtracker-miner/libtracker-miner-sections.txt |    4 -
 .../libtracker-miner/tmpl/tracker-miner-fs.sgml    |   69 ++--------------
 .../tmpl/tracker-miner-manager.sgml                |   54 -------------
 .../libtracker-miner/tmpl/tracker-miner.sgml       |   83 ++-----------------
 src/libtracker-miner/tracker-miner-fs.c            |   11 +++
 src/libtracker-miner/tracker-miner-fs.h            |   32 +++++++-
 src/libtracker-miner/tracker-miner-manager.c       |   10 +++
 src/libtracker-miner/tracker-miner.c               |   27 ++++++-
 src/libtracker-miner/tracker-miner.h               |   18 ++++-
 9 files changed, 108 insertions(+), 200 deletions(-)
---
diff --git a/docs/reference/libtracker-miner/libtracker-miner-sections.txt b/docs/reference/libtracker-miner/libtracker-miner-sections.txt
index ec64de9..e308b79 100644
--- a/docs/reference/libtracker-miner/libtracker-miner-sections.txt
+++ b/docs/reference/libtracker-miner/libtracker-miner-sections.txt
@@ -2,7 +2,6 @@
 <SECTION>
 <FILE>tracker-miner</FILE>
 <TITLE>Tracker Miner</TITLE>
-TrackerMiner
 TrackerMinerClass
 tracker_miner_error_quark
 tracker_miner_start
@@ -20,7 +19,6 @@ tracker_miner_resume
 <SECTION>
 <FILE>tracker-miner-fs</FILE>
 <TITLE>Tracker Filesystem Miner</TITLE>
-TrackerMinerFS
 TrackerMinerFSClass
 TrackerMinerFSDoneCb
 tracker_miner_fs_add_directory
@@ -33,8 +31,6 @@ tracker_miner_fs_get_throttle
 <SECTION>
 <FILE>tracker-miner-manager</FILE>
 <TITLE>Tracker Miner Manager</TITLE>
-TrackerMinerManager
-TrackerMinerManagerClass
 tracker_miner_manager_new
 tracker_miner_manager_get_running
 tracker_miner_manager_get_available
diff --git a/docs/reference/libtracker-miner/tmpl/tracker-miner-fs.sgml b/docs/reference/libtracker-miner/tmpl/tracker-miner-fs.sgml
index 2370c4d..ce7e551 100644
--- a/docs/reference/libtracker-miner/tmpl/tracker-miner-fs.sgml
+++ b/docs/reference/libtracker-miner/tmpl/tracker-miner-fs.sgml
@@ -17,71 +17,18 @@ Tracker Filesystem Miner
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### TYPEDEF TrackerMinerFS ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL TrackerMinerFS::check-directory ##### -->
-<para>
-
-</para>
-
- trackerminerfs: the object which received the signal.
- arg1: 
- Returns: 
-
-<!-- ##### SIGNAL TrackerMinerFS::check-directory-contents ##### -->
-<para>
-
-</para>
-
- trackerminerfs: the object which received the signal.
- arg1: 
- arg2: 
- Returns: 
-
-<!-- ##### SIGNAL TrackerMinerFS::check-file ##### -->
-<para>
-
-</para>
-
- trackerminerfs: the object which received the signal.
- arg1: 
- Returns: 
-
-<!-- ##### SIGNAL TrackerMinerFS::finished ##### -->
-<para>
-
-</para>
-
- trackerminerfs: the object which received the signal.
- arg1: 
- arg2: 
- arg3: 
- arg4: 
- arg5: 
-
-<!-- ##### SIGNAL TrackerMinerFS::monitor-directory ##### -->
-<para>
-
-</para>
-
- trackerminerfs: the object which received the signal.
- arg1: 
- Returns: 
-
-<!-- ##### ARG TrackerMinerFS:throttle ##### -->
-<para>
-
-</para>
-
-<!-- ##### TYPEDEF TrackerMinerFSClass ##### -->
+<!-- ##### STRUCT TrackerMinerFSClass ##### -->
 <para>
 
 </para>
 
+ parent: 
+ check_file: 
+ check_directory: 
+ check_directory_contents: 
+ process_file: 
+ monitor_directory: 
+ finished: 
 
 <!-- ##### USER_FUNCTION TrackerMinerFSDoneCb ##### -->
 <para>
diff --git a/docs/reference/libtracker-miner/tmpl/tracker-miner-manager.sgml b/docs/reference/libtracker-miner/tmpl/tracker-miner-manager.sgml
index 7de904c..cea12bc 100644
--- a/docs/reference/libtracker-miner/tmpl/tracker-miner-manager.sgml
+++ b/docs/reference/libtracker-miner/tmpl/tracker-miner-manager.sgml
@@ -17,60 +17,6 @@ Tracker Miner Manager
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### TYPEDEF TrackerMinerManager ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL TrackerMinerManager::miner-activated ##### -->
-<para>
-
-</para>
-
- trackerminermanager: the object which received the signal.
- arg1: 
-
-<!-- ##### SIGNAL TrackerMinerManager::miner-deactivated ##### -->
-<para>
-
-</para>
-
- trackerminermanager: the object which received the signal.
- arg1: 
-
-<!-- ##### SIGNAL TrackerMinerManager::miner-paused ##### -->
-<para>
-
-</para>
-
- trackerminermanager: the object which received the signal.
- arg1: 
-
-<!-- ##### SIGNAL TrackerMinerManager::miner-progress ##### -->
-<para>
-
-</para>
-
- trackerminermanager: the object which received the signal.
- arg1: 
- arg2: 
- arg3: 
-
-<!-- ##### SIGNAL TrackerMinerManager::miner-resumed ##### -->
-<para>
-
-</para>
-
- trackerminermanager: the object which received the signal.
- arg1: 
-
-<!-- ##### TYPEDEF TrackerMinerManagerClass ##### -->
-<para>
-
-</para>
-
-
 <!-- ##### FUNCTION tracker_miner_manager_new ##### -->
 <para>
 
diff --git a/docs/reference/libtracker-miner/tmpl/tracker-miner.sgml b/docs/reference/libtracker-miner/tmpl/tracker-miner.sgml
index 7f8ba45..1415507 100644
--- a/docs/reference/libtracker-miner/tmpl/tracker-miner.sgml
+++ b/docs/reference/libtracker-miner/tmpl/tracker-miner.sgml
@@ -17,84 +17,19 @@ Tracker Miner
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### TYPEDEF TrackerMiner ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL TrackerMiner::error ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
- arg1: 
-
-<!-- ##### SIGNAL TrackerMiner::paused ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
-
-<!-- ##### SIGNAL TrackerMiner::progress ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
- arg1: 
- arg2: 
-
-<!-- ##### SIGNAL TrackerMiner::resumed ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
-
-<!-- ##### SIGNAL TrackerMiner::started ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
-
-<!-- ##### SIGNAL TrackerMiner::stopped ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
-
-<!-- ##### SIGNAL TrackerMiner::terminated ##### -->
-<para>
-
-</para>
-
- trackerminer: the object which received the signal.
-
-<!-- ##### ARG TrackerMiner:name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG TrackerMiner:progress ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG TrackerMiner:status ##### -->
-<para>
-
-</para>
-
-<!-- ##### TYPEDEF TrackerMinerClass ##### -->
+<!-- ##### STRUCT TrackerMinerClass ##### -->
 <para>
 
 </para>
 
+ parent_class: 
+ started: 
+ stopped: 
+ paused: 
+ resumed: 
+ terminated: 
+ progress: 
+ error: 
 
 <!-- ##### FUNCTION tracker_miner_error_quark ##### -->
 <para>
diff --git a/src/libtracker-miner/tracker-miner-fs.c b/src/libtracker-miner/tracker-miner-fs.c
index 301ccde..2af8c87 100644
--- a/src/libtracker-miner/tracker-miner-fs.c
+++ b/src/libtracker-miner/tracker-miner-fs.c
@@ -28,6 +28,17 @@
 #include "tracker-monitor.h"
 #include "tracker-utils.h"
 
+/**
+ * SECTION:tracker-miner-fs
+ * @short_description: Abstract base class for filesystem miners
+ * @include: libtracker-miner/tracker-miner-fs.h
+ *
+ * #TrackerMinerFS is an abstract base class for miners that collect data
+ * from the filesystem, all the filesystem crawling and monitoring is
+ * abstracted away, leaving to implementations the decisions of what
+ * directories/files should it process, and the actual data extraction.
+ **/
+
 #define TRACKER_MINER_FS_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), TRACKER_TYPE_MINER_FS, TrackerMinerFSPrivate))
 
 typedef struct {
diff --git a/src/libtracker-miner/tracker-miner-fs.h b/src/libtracker-miner/tracker-miner-fs.h
index 5b1c1bd..6f266f9 100644
--- a/src/libtracker-miner/tracker-miner-fs.h
+++ b/src/libtracker-miner/tracker-miner-fs.h
@@ -38,9 +38,21 @@ G_BEGIN_DECLS
 #define TRACKER_MINER_FS_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_MINER_FS, TrackerMinerFSClass))
 
 typedef struct TrackerMinerFS        TrackerMinerFS;
-typedef struct TrackerMinerFSClass   TrackerMinerFSClass;
 typedef struct TrackerMinerFSPrivate TrackerMinerFSPrivate;
 
+/**
+ * TrackerMinerFSDoneCb:
+ * @fs: The #TrackerMinerFS
+ * @file: The #GFile corresponding to the asynchronous call
+ * @builder: a #TrackerSparqlBuilder to collect data
+ * @error: #GError with the extraction error, or %NULL if none
+ * @user_data: passed user data to the asynchronous call
+ *
+ * This callback is passed for each inspected #GFile in the
+ * TrackerMinerFS::process_file() vmethod, it's the implementation
+ * responsibility to call it as soon as all metadata extraction has
+ * been performed on @file.
+ **/
 typedef void (* TrackerMinerFSDoneCb) (TrackerMinerFS       *fs,
 				       GFile                *file,
 				       TrackerSparqlBuilder *builder,
@@ -52,7 +64,21 @@ struct TrackerMinerFS {
 	TrackerMinerFSPrivate *private;
 };
 
-struct TrackerMinerFSClass {
+/**
+ * TrackerMinerFSClass:
+ * @parent: parent object class
+ * @check_file: Called when a file should be checked for further processing
+ * @check_directory: Called when a directory should be checked for further processing
+ * @check_directory_contents: Called when a directory should be checked for further processing, based on the directory contents.
+ * @process_file: Called when the metadata associated to a file is requested.
+ * @monitor_directory: Called to check whether a directory should be modified.
+ * @finished: Called when all processing has been performed.
+ *
+ * Prototype for the abstract class, @check_file, @check_directory, @check_directory_contents,
+ * @process_file and @monitor_directory must be implemented in the deriving class in order to
+ * actually extract data.
+ **/
+typedef struct {
 	TrackerMinerClass parent;
 
 	gboolean (* check_file)            (TrackerMinerFS       *fs,
@@ -71,7 +97,7 @@ struct TrackerMinerFSClass {
 	gboolean (* monitor_directory)     (TrackerMinerFS       *fs,
 					    GFile                *file);
 	void     (* finished)              (TrackerMinerFS       *fs);
-};
+} TrackerMinerFSClass;
 
 GType    tracker_miner_fs_get_type         (void) G_GNUC_CONST;
 
diff --git a/src/libtracker-miner/tracker-miner-manager.c b/src/libtracker-miner/tracker-miner-manager.c
index 2c11f7b..e7d72e2 100644
--- a/src/libtracker-miner/tracker-miner-manager.c
+++ b/src/libtracker-miner/tracker-miner-manager.c
@@ -30,6 +30,16 @@
 #include "tracker-miner-client.h"
 #include "tracker-miner-dbus.h"
 
+/**
+ * SECTION:tracker-miner-manager
+ * @short_description: External control and monitoring of miners
+ * @include: libtracker-miner/tracker-miner-manager.h
+ *
+ * #TrackerMinerManager keeps track of available miners, their current
+ * progress/status, and also allows basic external control on them, such
+ * as pausing or resuming data processing.
+ **/
+
 #define TRACKER_MINER_MANAGER_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), TRACKER_TYPE_MINER_MANAGER, TrackerMinerManagerPrivate))
 
 #define DESKTOP_ENTRY_GROUP "Desktop Entry"
diff --git a/src/libtracker-miner/tracker-miner.c b/src/libtracker-miner/tracker-miner.c
index d7825e0..a85ac9b 100644
--- a/src/libtracker-miner/tracker-miner.c
+++ b/src/libtracker-miner/tracker-miner.c
@@ -30,6 +30,18 @@
 #include "tracker-miner-dbus.h"
 #include "tracker-miner-glue.h"
 
+/**
+ * SECTION:tracker-miner
+ * @short_description: Abstract base class for data miners
+ * @include: libtracker-miner/tracker-miner.h
+ *
+ * #TrackerMiner is an abstract base class to help developing data miners
+ * for tracker-store, being an abstract class it doesn't do much by itself,
+ * but provides the basic signaling and operation control so the miners
+ * implementing this class are properly recognized by Tracker, and can be
+ * controlled properly by external means such as #TrackerMinerManager.
+ **/
+
 #define TRACKER_MINER_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), TRACKER_TYPE_MINER, TrackerMinerPrivate))
 
 struct TrackerMinerPrivate {
@@ -185,7 +197,7 @@ tracker_miner_class_init (TrackerMinerClass *klass)
 	/**
 	 * TrackerMiner::progress:
 	 * @miner: the #TrackerMiner
-	 * @status: 
+	 * @status: miner status
 	 * @progress: a #gdouble indicating miner progress, from 0 to 1.
 	 *
 	 * the ::progress signal will be emitted by TrackerMiner implementations
@@ -823,6 +835,19 @@ tracker_miner_commit (TrackerMiner *miner)
 	return TRUE;
 }
 
+/**
+ * tracker_miner_pause:
+ * @miner: a #TrackerMiner
+ * @application: application name
+ * @reason: reason to pause
+ * @error: return location for errors
+ *
+ * Asks @miner to pause. On success the cookie ID is returned,
+ * this is what must be used in tracker_miner_resume() to resume
+ * operations. On failure @error will be set and -1 will be returned.
+ *
+ * Returns: The pause cookie ID.
+ **/
 gint
 tracker_miner_pause (TrackerMiner  *miner,
 		     const gchar   *application,
diff --git a/src/libtracker-miner/tracker-miner.h b/src/libtracker-miner/tracker-miner.h
index 542aac7..937c7be 100644
--- a/src/libtracker-miner/tracker-miner.h
+++ b/src/libtracker-miner/tracker-miner.h
@@ -37,7 +37,6 @@ G_BEGIN_DECLS
 #define TRACKER_MINER_ERROR	       tracker_miner_error_quark()
 
 typedef struct TrackerMiner TrackerMiner;
-typedef struct TrackerMinerClass TrackerMinerClass;
 typedef struct TrackerMinerPrivate TrackerMinerPrivate;
 
 struct TrackerMiner {
@@ -45,7 +44,20 @@ struct TrackerMiner {
         TrackerMinerPrivate *private;
 };
 
-struct TrackerMinerClass {
+/**
+ * TrackerMinerClass:
+ * @parent_class: parent object class.
+ * @started: Called when the miner is told to start collecting data.
+ * @stopped: Called when the miner is told to stop collecting data.
+ * @paused: Called when the miner is told to pause.
+ * @resumed: Called when the miner is told to resume activity.
+ * @terminated: terminated.
+ * @progress: progress.
+ * @error: error.
+ *
+ * Virtual methods left to implement.
+ **/
+typedef struct {
         GObjectClass parent_class;
 
         /* signals */
@@ -63,7 +75,7 @@ struct TrackerMinerClass {
 
 	void (* error)      (TrackerMiner *miner,
 			     GError       *error);
-};
+} TrackerMinerClass;
 
 GType          tracker_miner_get_type       (void) G_GNUC_CONST;
 GQuark	       tracker_miner_error_quark    (void);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]