GNOME.org
 

[tracker] libtracker-extract: Documentation fixes

commit 735c9f8b8b66dd9d1221a1f380a111b8ab313cff
Author: Sam Thursfield <sam thursfield codethink co uk>
Date:   Thu Sep 15 12:00:53 2011 +0100

    libtracker-extract: Documentation fixes
    
    * Add TrackerExtractInfo section
    * Update compile instructions for 0.12
    * Include introspection annotations glossary (avoids parse errors)
    * Fix tracker_extract_get_metadata() example for 0.12
    * Fix miscellaneous variable name mismatches etc.

 .../libtracker-extract-docs.sgml                   |    5 ++
 .../libtracker-extract-sections.txt                |    7 +--
 docs/reference/libtracker-extract/overview.sgml    |   10 ++--
 src/libtracker-extract/tracker-data.h              |   54 ++++++++-----------
 src/libtracker-extract/tracker-extract-client.h    |    4 +-
 src/libtracker-extract/tracker-extract-info.c      |   18 ++++++-
 6 files changed, 54 insertions(+), 44 deletions(-)
---
diff --git a/docs/reference/libtracker-extract/libtracker-extract-docs.sgml b/docs/reference/libtracker-extract/libtracker-extract-docs.sgml
index 9111dc2..4a5091d 100644
--- a/docs/reference/libtracker-extract/libtracker-extract-docs.sgml
+++ b/docs/reference/libtracker-extract/libtracker-extract-docs.sgml
@@ -1,9 +1,11 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY tracker-overview SYSTEM "overview.sgml">
 <!ENTITY tracker-data SYSTEM "xml/tracker-data.xml">
+<!ENTITY tracker-extract-info SYSTEM "xml/tracker-extract-info.xml">
 <!ENTITY tracker-utils SYSTEM "xml/tracker-utils.xml">
 <!ENTITY tracker-xmp SYSTEM "xml/tracker-xmp.xml">
 <!ENTITY tracker-iptc SYSTEM "xml/tracker-iptc.xml">
@@ -36,6 +38,7 @@
     <chapter>
       <title>Core API</title>
       &tracker-data;
+      &tracker-extract-info;
       &tracker-utils;
     </chapter>
 
@@ -45,5 +48,7 @@
       &tracker-iptc;
       &tracker-exif;
     </chapter>
+
+    <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
   </part>
 </book>
diff --git a/docs/reference/libtracker-extract/libtracker-extract-sections.txt b/docs/reference/libtracker-extract/libtracker-extract-sections.txt
index b746599..d10d62f 100644
--- a/docs/reference/libtracker-extract/libtracker-extract-sections.txt
+++ b/docs/reference/libtracker-extract/libtracker-extract-sections.txt
@@ -17,10 +17,7 @@ tracker_iptc_read
 
 <SECTION>
 <FILE>tracker-data</FILE>
-TrackerExtractMimeFunc
-TrackerExtractDataFunc
-TrackerExtractData
-tracker_extract_get_data
+tracker_extract_get_metadata
 </SECTION>
 
 <SECTION>
@@ -65,4 +62,6 @@ tracker_extract_info_set_where_clause
 tracker_extract_info_get_file
 tracker_extract_info_get_mimetype
 tracker_extract_info_get_graph
+<SUBSECTION Standard>
+tracker_extract_info_get_type
 </SECTION>
diff --git a/docs/reference/libtracker-extract/overview.sgml b/docs/reference/libtracker-extract/overview.sgml
index a03c1a7..16d2078 100644
--- a/docs/reference/libtracker-extract/overview.sgml
+++ b/docs/reference/libtracker-extract/overview.sgml
@@ -29,11 +29,11 @@
       <application>pkg-config</application> is used (the actual output on
       your system may be different):
 <programlisting>
-$ pkg-config --cflags tracker-extract-0.10
--pthread -I/usr/include/tracker-0.10 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/tracker-0.10/libtracker-sparql
+$ pkg-config --cflags tracker-extract-0.12
+-pthread -I/usr/include/tracker-0.12 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/tracker-0.12/libtracker-sparql
 
-$ pkg-config --libs tracker-extract-0.10
--Wl,--export-dynamic -pthread -ltracker-extract-0.10 -ltracker-sparql-0.10 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
+$ pkg-config --libs tracker-extract-0.12
+-Wl,--export-dynamic -pthread -ltracker-extract-0.12 -ltracker-sparql-0.12 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
 
 </programlisting>
     </para>
@@ -43,7 +43,7 @@ $ pkg-config --libs tracker-extract-0.10
       (<emphasis>not single quotes</emphasis>), then its output will be
       substituted into the command line before execution:
 <programlisting>
- $ cc `pkg-config --cflags --libs tracker-extract-0.10` hello.c -o hello
+ $ cc `pkg-config --cflags --libs tracker-extract-0.12` hello.c -o hello
 </programlisting>
     </para>
 
diff --git a/src/libtracker-extract/tracker-data.h b/src/libtracker-extract/tracker-data.h
index 6dbe9c1..bdfe82b 100644
--- a/src/libtracker-extract/tracker-data.h
+++ b/src/libtracker-extract/tracker-data.h
@@ -51,22 +51,16 @@ G_BEGIN_DECLS
  * An example of how to write an extractor to retrieve PNG embedded
  * metadata.
  * <programlisting>
- *  /&ast; Set functions to use to extract different mime types. &ast;/
- *  static TrackerExtractData extract_data[] = {
- *          { "image/png",  extract_png },
- *          { "sketch/png", extract_png },
- *          { NULL, NULL }
- *  };
- *
  *  G_MODULE_EXPORT gboolean
- *  tracker_extract_get_metadata (const gchar          *uri,
- *                                const gchar          *mimetype,
- *                                TrackerSparqlBuilder *preupdate,
- *                                TrackerSparqlBuilder *metadata,
- *                                GString              *where)
+ *  tracker_extract_get_metadata (TrackerExtractInfo *info)
  *  {
+ *          GFile *file;
+ *          TrackerSparqlBuilder *metadata;
  *          gint height, width;
  *
+ *          file = tracker_extract_info_get_file (info);
+ *          metadata = tracker_extract_info_get_metadata_builder (info);
+ *
  *          /&ast; Do data extraction. &ast;/
  *          height = ...
  *          width = ...
@@ -82,8 +76,6 @@ G_BEGIN_DECLS
  *          tracker_sparql_builder_predicate (metadata, "nfo:height");
  *          tracker_sparql_builder_object_int64 (metadata, height);
  *
- *          g_free (filename);
- *
  *          /&ast; Were we successful or not? &ast;/
  *          return TRUE;
  *  }
@@ -102,13 +94,7 @@ gboolean tracker_extract_module_shutdown (void);
 
 /**
  * tracker_extract_get_metadata:
- * @uri: a string representing a URI.
- * @mimetype: mimetype for the element contained in URI
- * @preupdate: used to populate with data updates that
- *             are a prerequisite for the actual file
- *             metadata insertion.
- * @metadata: used to populate with file metadata predicate/object(s).
- * @where: used for optional WHERE patterns
+ * @info: a #TrackerExtractInfo object
  *
  * This function must be provided by ALL extractors. This is merely
  * the declaration of the function which must be written by each
@@ -117,24 +103,30 @@ gboolean tracker_extract_module_shutdown (void);
  * This is checked by tracker-extract by looking up the symbols for
  * each started plugin and making sure this function exists.
  *
- * The @metadata parameter is a #TrackerSparqlBuilder constructed
- * through tracker_sparql_builder_new_embedded_insert(), the subject
+ * The @info parameter contains required information for the
+ * extraction and a location to store the results. The
+ * tracker_extract_info_get_metadata_builder() function returns a
+ * #TrackerSparqlBuilder constructed through
+ * tracker_sparql_builder_new_embedded_insert(). The subject
  * is already set to be the file URN, so implementations of this
- * function should just provide predicate/object(s) pairs. the data
- * triples contained in there at the end of the function will be
+ * function should just provide predicate/object(s) pairs. The
+ * triples contained in this object at the end of the function will be
  * merged with further file information from miners.
  *
  * Whenever any of the inserted triples rely on entities that
  * should also be provided by this extractor (for example, album
  * or artist information from a song), such insertions should be
- * added to @preupdate, which is a #TrackerSparqlBuilder constructed.
- * through tracker_sparql_builder_new_update().
+ * added to the preupdate object returned by
+ * tracker_extract_info_get_preupdate_builder(). This is a
+ * #TrackerSparqlBuilder created through
+ * tracker_sparql_builder_new_update().
  *
- * NOTE: If upgrading from 0.10, this function is replacing the old
+ * NOTE: If upgrading from 0.10, this function replaces the old
  * function named tracker_extract_get_data() and has a few subtle
- * differences. First there is a return value for success. Second
- * there is also a @mimetype argument which should will be passed to
- * each extractor.
+ * differences. First, there is a return value for success and the
+ * parameters are contained in @info instead of being passed
+ * individually. Second, the extractor is passed the detected
+ * MIME type of the file being extracted.
  *
  * Returns: %TRUE if the extraction succeeded, %FALSE otherwise.
  *
diff --git a/src/libtracker-extract/tracker-extract-client.h b/src/libtracker-extract/tracker-extract-client.h
index b5b6270..169acff 100644
--- a/src/libtracker-extract/tracker-extract-client.h
+++ b/src/libtracker-extract/tracker-extract-client.h
@@ -36,11 +36,11 @@ void                 tracker_extract_client_get_metadata        (GFile
                                                                  GAsyncReadyCallback  callback,
                                                                  gpointer             user_data);
 
-TrackerExtractInfo * tracker_extract_client_get_metadata_finish (GFile               *uri,
+TrackerExtractInfo * tracker_extract_client_get_metadata_finish (GFile               *file,
                                                                  GAsyncResult        *res,
                                                                  GError             **error);
 
-void                 tracker_extract_client_cancel_for_prefix   (GFile               *uri);
+void                 tracker_extract_client_cancel_for_prefix   (GFile               *prefix);
 
 G_END_DECLS
 
diff --git a/src/libtracker-extract/tracker-extract-info.c b/src/libtracker-extract/tracker-extract-info.c
index 5696c5a..528e795 100644
--- a/src/libtracker-extract/tracker-extract-info.c
+++ b/src/libtracker-extract/tracker-extract-info.c
@@ -21,6 +21,20 @@
 
 #include "tracker-extract-info.h"
 
+/**
+ * SECTION:tracker-extract-info
+ * @title: TrackerExtractInfo
+ * @short_description: struct used to pass information to and from
+ *                     a Tracker extract module
+ * @stability: Stable
+ * @include: libtracker-extract/tracker-extract.h
+ *
+ * The #TrackerExtractInfo structure is used to pass information
+ * on the file being extracted to an extractor module and contains
+ * objects to hold the SPARQL updates generated by the extractor.
+ **/
+
+
 struct _TrackerExtractInfo
 {
 	TrackerSparqlBuilder *preupdate;
@@ -95,7 +109,7 @@ tracker_extract_info_ref (TrackerExtractInfo *info)
  * tracker_extract_info_unref:
  * @info: a #TrackerExtractInfo
  *
- * Decreases the reference count of @info, freeing all its associated resources.
+ * Decreases the reference count of @info, freeing all its associated resources
  * if it reaches 0.
  *
  * Since: 0.12
@@ -179,7 +193,7 @@ tracker_extract_info_get_graph (TrackerExtractInfo *info)
 
 /**
  * tracker_extract_info_get_preupdate_builder:
- * @info: a #TrackerSparqlBuilder
+ * @info: a #TrackerExtractInfo
  *
  * Returns a #TrackerSparqlBuilder containing any
  * separate updates that could apply to the file,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]