[tracker] Fill in missing libtracker-miner docs.
- From: Carlos Garnacho <carlosg src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [tracker] Fill in missing libtracker-miner docs.
- Date: Mon, 5 Oct 2009 14:33:35 +0000 (UTC)
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]