[tracker/direct-access: 146/158] libtracker-sparql: Setup initial gtk-doc documentation



commit e1f35b023c611b1ebdd016104a0219e8e1d97d7b
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Tue Aug 3 10:30:26 2010 +0200

    libtracker-sparql: Setup initial gtk-doc documentation
    
      * Includes Utilities and TrackerSparqlBuilder documentation

 configure.ac                                       |    2 +
 docs/reference/Makefile.am                         |    1 +
 docs/reference/libtracker-sparql/Makefile.am       |   64 ++++
 .../libtracker-sparql/libtracker-sparql-docs.sgml  |   46 +++
 .../libtracker-sparql-sections.txt                 |   63 ++++
 .../libtracker-sparql/libtracker-sparql.types      |    1 +
 .../libtracker-sparql/tmpl/tracker-misc.sgml       |   51 +++
 .../tmpl/tracker-sparql-builder.sgml               |  391 ++++++++++++++++++++
 docs/reference/libtracker-sparql/version.xml.in    |    1 +
 src/libtracker-sparql/tracker-builder.vala         |    1 +
 src/libtracker-sparql/tracker-uri.c                |   16 +-
 src/libtracker-sparql/tracker-utils.vala           |   10 +
 12 files changed, 639 insertions(+), 8 deletions(-)
---
diff --git a/configure.ac b/configure.ac
index 891e486..6587aa9 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1853,6 +1853,8 @@ AC_CONFIG_FILES([
 	docs/reference/Makefile
 	docs/reference/libtracker-client/Makefile
 	docs/reference/libtracker-client/version.xml
+	docs/reference/libtracker-sparql/Makefile
+	docs/reference/libtracker-sparql/version.xml
 	docs/reference/libtracker-extract/Makefile
 	docs/reference/libtracker-extract/version.xml
 	docs/reference/libtracker-miner/Makefile
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 9c6431f..c46b220 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -1,6 +1,7 @@
 include $(top_srcdir)/Makefile.decl
 
 SUBDIRS = 			\
+	libtracker-sparql	\
 	libtracker-client	\
 	libtracker-extract	\
 	libtracker-miner	\
diff --git a/docs/reference/libtracker-sparql/Makefile.am b/docs/reference/libtracker-sparql/Makefile.am
new file mode 100644
index 0000000..532e82b
--- /dev/null
+++ b/docs/reference/libtracker-sparql/Makefile.am
@@ -0,0 +1,64 @@
+include $(top_srcdir)/Makefile.decl
+
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module.
+DOC_MODULE = libtracker-sparql
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE = libtracker-sparql-docs.sgml
+
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=--deprecated-guards="TRACKER_DISABLE_DEPRECATED"
+
+# Extra options to pass to gtkdoc-scangobj
+# SCANGOBJ_OPTIONS=--type-init-func="gtk_type_init(0)"
+
+# The directory containing the source code. Relative to $(srcdir)
+DOC_SOURCE_DIR = ../../../src/libtracker-sparql
+
+# Used for dependencies
+HFILE_GLOB = $(top_srcdir)/src/libtracker-sparql/*.h
+CFILE_GLOB = $(top_srcdir)/src/libtracker-sparql/*.c
+
+# Header files to ignore when scanning
+IGNORE_HFILES =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
+INCLUDES = 								\
+	-DTRACKER_COMPILATION						\
+	-I$(top_srcdir)/src						\
+	$(GLIB2_CFLAGS)							\
+	$(GIO_CFLAGS)							\
+	$(DBUS_CFLAGS)
+
+GTKDOC_LIBS =								\
+	$(top_builddir)/src/libtracker-sparql/libtracker-sparql- TRACKER_API_VERSION@.la \
+	$(top_builddir)/src/libtracker-common/libtracker-common.la	\
+	$(DBUS_LIBS)							\
+	$(GIO_LIBS)							\
+	$(GLIB2_LIBS)
+
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS = --sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=--path="$(abs_builddir)"
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
+content_files =	version.xml
+
+expand_content_files =
+
+# Images to copy into HTML directory
+HTML_IMAGES =
+
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS =
+
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+EXTRA_DIST += version.xml.in
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
new file mode 100644
index 0000000..f6b2439
--- /dev/null
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -0,0 +1,46 @@
+<?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 tracker SYSTEM "xml/tracker.xml"-->
+<!--!ENTITY tracker-cancel SYSTEM "xml/tracker_cancel.xml"-->
+<!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
+<!--!ENTITY tracker-statistics SYSTEM "xml/tracker_statistics.xml"-->
+<!--!ENTITY tracker-resources SYSTEM "xml/tracker_resources.xml"-->
+<!--!ENTITY tracker-search SYSTEM "xml/tracker_search.xml"-->
+<!ENTITY tracker-sparql-builder SYSTEM "xml/tracker-sparql-builder.xml">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+  <bookinfo>
+    <title>Tracker Sparql Library Reference Manual</title>
+    <releaseinfo>for libtracker-sparql &version;</releaseinfo>
+  </bookinfo>
+
+  <part id="libtracker-sparql">
+    <title>Overview</title>
+    <partintro>
+      <para>
+        The libtracker-sparql library BLA BLA BLA...
+      </para>
+      <para>
+      </para>
+    </partintro>
+  </part>
+
+    <chapter>
+      <title>General</title>
+<!--      &tracker; -->
+<!--      &tracker-cancel; -->
+      &tracker-misc;
+    </chapter>
+    <!--chapter>
+      <title>Querying</title>
+      &tracker-statistics;
+      &tracker-resources;
+      &tracker-search;
+    </chapter-->
+    <chapter>
+      <title>Building Queries</title>
+      &tracker-sparql-builder;
+    </chapter>
+</book>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
new file mode 100644
index 0000000..b675a6c
--- /dev/null
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -0,0 +1,63 @@
+
+<SECTION>
+<FILE>tracker-misc</FILE>
+<TITLE>Utilities</TITLE>
+tracker_sparql_escape_string
+tracker_sparql_escape_uri_printf
+tracker_sparql_escape_uri_vprintf
+</SECTION>
+
+<SECTION>
+<FILE>tracker-sparql-builder</FILE>
+<TITLE>TrackerSparqlBuilder</TITLE>
+TrackerSparqlBuilder
+TrackerSparqlBuilderState
+tracker_sparql_builder_new
+tracker_sparql_builder_new_embedded_insert
+tracker_sparql_builder_new_update
+tracker_sparql_builder_get_state
+tracker_sparql_builder_get_result
+tracker_sparql_builder_get_length
+tracker_sparql_builder_append
+tracker_sparql_builder_prepend
+tracker_sparql_builder_insert_open
+tracker_sparql_builder_insert_silent_open
+tracker_sparql_builder_insert_close
+tracker_sparql_builder_where_open
+tracker_sparql_builder_where_close
+tracker_sparql_builder_delete_open
+tracker_sparql_builder_delete_close
+tracker_sparql_builder_drop_graph
+tracker_sparql_builder_subject_variable
+tracker_sparql_builder_subject_iri
+tracker_sparql_builder_subject
+tracker_sparql_builder_predicate_iri
+tracker_sparql_builder_predicate
+tracker_sparql_builder_object_iri
+tracker_sparql_builder_object
+tracker_sparql_builder_object_string
+tracker_sparql_builder_object_boolean
+tracker_sparql_builder_object_int64
+tracker_sparql_builder_object_date
+tracker_sparql_builder_object_double
+tracker_sparql_builder_object_variable
+tracker_sparql_builder_object_blank_open
+tracker_sparql_builder_object_blank_close
+tracker_sparql_builder_object_unvalidated
+<SUBSECTION Standard>
+TrackerSparqlBuilderClass
+TRACKER_SPARQL_BUILDER
+TRACKER_SPARQL_IS_BUILDER
+TRACKER_SPARQL_TYPE_BUILDER
+tracker_sparql_builder_get_type
+TRACKER_SPARQL_BUILDER_CLASS
+TRACKER_SPARQL_IS_BUILDER_CLASS
+TRACKER_SPARQL_BUILDER_GET_CLASS
+TRACKER_SPARQL_BUILDER_TYPE_STATE
+tracker_sparql_builder_state_get_type
+<SUBSECTION Private>
+TrackerSparqlBuilderPrivate
+tracker_sparql_builder_construct
+tracker_sparql_builder_construct_embedded_insert
+tracker_sparql_builder_construct_update
+</SECTION>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql.types b/docs/reference/libtracker-sparql/libtracker-sparql.types
new file mode 100644
index 0000000..0c5128c
--- /dev/null
+++ b/docs/reference/libtracker-sparql/libtracker-sparql.types
@@ -0,0 +1 @@
+tracker_sparql_builder_get_type
\ No newline at end of file
diff --git a/docs/reference/libtracker-sparql/tmpl/tracker-misc.sgml b/docs/reference/libtracker-sparql/tmpl/tracker-misc.sgml
new file mode 100644
index 0000000..162035f
--- /dev/null
+++ b/docs/reference/libtracker-sparql/tmpl/tracker-misc.sgml
@@ -0,0 +1,51 @@
+<!-- ##### SECTION Title ##### -->
+Utilities
+
+<!-- ##### SECTION Short_Description ##### -->
+General purpose utilities provided by the library
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+The libtracker-sparql utilities help in the creation of proper SPARQL queries.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### FUNCTION tracker_sparql_escape_string ##### -->
+<para>
+
+</para>
+
+ literal: 
+ Returns: 
+
+
+<!-- ##### FUNCTION tracker_sparql_escape_uri_printf ##### -->
+<para>
+
+</para>
+
+ format: 
+ Varargs: 
+ Returns: 
+
+
+<!-- ##### FUNCTION tracker_sparql_escape_uri_vprintf ##### -->
+<para>
+
+</para>
+
+ format: 
+ args: 
+ Returns: 
+
+
diff --git a/docs/reference/libtracker-sparql/tmpl/tracker-sparql-builder.sgml b/docs/reference/libtracker-sparql/tmpl/tracker-sparql-builder.sgml
new file mode 100644
index 0000000..01a0c27
--- /dev/null
+++ b/docs/reference/libtracker-sparql/tmpl/tracker-sparql-builder.sgml
@@ -0,0 +1,391 @@
+<!-- ##### SECTION Title ##### -->
+TrackerSparqlBuilder
+
+<!-- ##### SECTION Short_Description ##### -->
+
+Creating insertion/update SPARQL queries.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+#TrackerSparqlBuilder is an object what will gather a set of
+subject/predicate/object triples, together with an optional WHERE clause,
+in order to create a query that may be issued to tracker-store.
+</para>
+
+<para>
+When using #TrackerSparqlBuilder, note that you may append several predicates
+for the same subject, and several objects for the same predicate.
+</para>
+
+<example id="example-sparql-builder">
+  <title>Using TrackerSparqlBuilder</title>
+  <programlisting>
+  TrackerSparqlBuilder *builder;
+  const gchar *iri = "urn:example:0001";
+  gchar *query_str;
+&nbsp;&nbsp;
+  /* Create builder */
+  builder = tracker_sparql_builder_new_update ();
+&nbsp;&nbsp;
+  /* Drop previous data */
+  tracker_sparql_builder_drop_graph (builder, iri);
+&nbsp;&nbsp;
+  /* Insert new data */
+  tracker_sparql_builder_insert_open (builder, iri);
+&nbsp;&nbsp;
+  tracker_sparql_builder_subject_iri (builder, iri);
+&nbsp;&nbsp;
+  tracker_sparql_builder_predicate (builder, "a");
+  tracker_sparql_builder_object (builder, "nie:DataObject");
+  tracker_sparql_builder_object (builder, "nfo:FileDataObject");
+&nbsp;&nbsp;
+  tracker_sparql_builder_predicate (builder, "nfo:fileLastModified");
+  tracker_sparql_builder_object_date (builder, time (NULL));
+&nbsp;&nbsp;
+  tracker_sparql_builder_insert_close (builder);
+&nbsp;&nbsp;
+  /* Get query as string */
+  query_str = tracker_sparql_builder_get_result (builder);
+  </programlisting>
+</example>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### STRUCT TrackerSparqlBuilder ##### -->
+<para>
+The <structname>TrackerSparqlBuilder</structname> object represents an
+insertion/update SPARQL query.
+</para>
+
+
+<!-- ##### ARG TrackerSparqlBuilder:length ##### -->
+<para>
+Number of objects added to the #TrackerSparqlBuilder.
+</para>
+
+<!-- ##### ARG TrackerSparqlBuilder:result ##### -->
+<para>
+String containing the constructed SPARQL in the #TrackerSparqlBuilder.
+</para>
+
+<!-- ##### ARG TrackerSparqlBuilder:state ##### -->
+<para>
+Current state of the #TrackerSparqlBuilder.
+</para>
+
+<!-- ##### ENUM TrackerSparqlBuilderState ##### -->
+<para>
+Enumeration with the possible states of the SPARQL Builder
+</para>
+
+ TRACKER_SPARQL_BUILDER_STATE_UPDATE: Builder is generating an UPDATE
+ TRACKER_SPARQL_BUILDER_STATE_INSERT: Builder is generating an INSERT
+ TRACKER_SPARQL_BUILDER_STATE_DELETE: Builder is generating a DELETE
+ TRACKER_SPARQL_BUILDER_STATE_SUBJECT: Builder is generating the subject of the query
+ TRACKER_SPARQL_BUILDER_STATE_PREDICATE: Builder is generating the predicate of the query
+ TRACKER_SPARQL_BUILDER_STATE_OBJECT: Builder is generating the object of the query
+ TRACKER_SPARQL_BUILDER_STATE_BLANK: Builder is generating a blank node subject
+ TRACKER_SPARQL_BUILDER_STATE_WHERE: Builder is generating the WHERE clause contents
+ TRACKER_SPARQL_BUILDER_STATE_EMBEDDED_INSERT: Builder is generating an embedded INSERT
+
+<!-- ##### FUNCTION tracker_sparql_builder_new ##### -->
+<para>
+Creates a stateless #TrackerSparqlBuilder.
+</para>
+
+ void: 
+ Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_new_embedded_insert ##### -->
+<para>
+Creates a #TrackerSparqlBuilder ready to be embedded in another query. In embedded
+inserts, the subject is implied (responsibility of the embedder), so only calls to
+append predicates and objects for the given subject are allowed.
+</para>
+
+ void: 
+ Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_new_update ##### -->
+<para>
+Creates an empty #TrackerSparqlBuilder for an update query.
+</para>
+
+ void: 
+ Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_get_state ##### -->
+<para>
+Returns the current state of @self
+</para>
+
+ self: a #TrackerSparqlBuilder
+ Returns: a #TrackerSparqlBuilderState defining the current state of @self
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_get_result ##### -->
+<para>
+Returns the constructed SPARQL query as a string.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ Returns: the created SPARQL query. The string is contained in the
+#TrackerSparqlBuilder object, and should not be freed by the caller.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_get_length ##### -->
+<para>
+Returns the number of objects added to @self.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ Returns: the number of objects contained.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_append ##### -->
+<para>
+Appends raw, unvalidated content to @self.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ raw: raw content to append.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_prepend ##### -->
+<para>
+Prepends raw, unvalidated content to @self.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ raw: raw content to prepend.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_insert_open ##### -->
+<para>
+Opens an insertion statement.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ graph: graph name, or %NULL.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_insert_silent_open ##### -->
+<para>
+Opens an silent insertion statement.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ graph: graph name, or %NULL.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_insert_close ##### -->
+<para>
+Closes an insertion statement opened with tracker_sparql_builder_insert_open().
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_where_open ##### -->
+<para>
+Opens a WHERE clause. Data triples may be appended then to narrow the scope
+to which the update query applies.
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_where_close ##### -->
+<para>
+Closes a WHERE clause opened through tracker_sparql_builder_where_open().
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_delete_open ##### -->
+<para>
+Opens a DELETE clause. Data triples may be appended in order to prepare
+a query to delete them.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ graph: graph name, or %NULL.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_delete_close ##### -->
+<para>
+Closes a DELETE clause opened through tracker_sparql_builder_delete_close().
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_drop_graph ##### -->
+<para>
+Appends a DROP GRAPH clause.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: a graph name.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_subject_variable ##### -->
+<para>
+Appends a subject as a SPARQL variable, such as "?urn".
+</para>
+
+ self: a #TrackerSparqlBuilder
+ var_name: variable name, without leading '?'
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_subject_iri ##### -->
+<para>
+Appends a subject as an IRI, such as "&lt;urn:file:1234-5678&gt;". IRIs
+univocally identify a resource in tracker-store.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: IRI name, without leading and trailing greater/less than symbols.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_subject ##### -->
+<para>
+Appends a subject.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ s: subject string
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_predicate_iri ##### -->
+<para>
+Appends a predicate as an IRI.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: IRI name, without leading and trailing greater/less than symbols.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_predicate ##### -->
+<para>
+Appends a predicate for the previously appended subject.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ s: predicate string
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_iri ##### -->
+<para>
+Appends an object as an IRI.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: IRI name, without leading and trailing greater/less than symbols.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object ##### -->
+<para>
+Appends a free-form object for the previously appended subject and predicate.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ s: object string
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_string ##### -->
+<para>
+Appends an object formatted as an string. @literal will be escaped and surrounded
+by double quotes.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: string object
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_boolean ##### -->
+<para>
+Appends a #gboolean value as an object.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: boolean object
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_int64 ##### -->
+<para>
+Appends a #gint64 as an object.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: object as gint64
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_date ##### -->
+<para>
+Appends a time_t as an object. @literal will be converted to a
+string in the date format used by tracker-store.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: object as time_t
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_double ##### -->
+<para>
+Appends a #gdouble as an object.
+</para>
+
+ self: a TrackerSparqlBuilder
+ literal: object as #gdouble
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_variable ##### -->
+<para>
+Appends an object as a SparQL variable, such as "?urn".
+</para>
+
+ self: a #TrackerSparqlBuilder
+ var_name: variable name, without leading '?'
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_blank_open ##### -->
+<para>
+Opens an anonymous blank node. In insertions this can be used to create
+anonymous nodes for not previously known data without the need of a
+separate insertion.
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_blank_close ##### -->
+<para>
+Closes an anomymous blank node opened with tracker_sparql_builder_object_blank_open()
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_unvalidated ##### -->
+<para>
+Appends a string not validated as UTF-8 as an object.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ value: possibly UTF-8 invalid string.
+
+
diff --git a/docs/reference/libtracker-sparql/version.xml.in b/docs/reference/libtracker-sparql/version.xml.in
new file mode 100644
index 0000000..c7e1225
--- /dev/null
+++ b/docs/reference/libtracker-sparql/version.xml.in
@@ -0,0 +1 @@
+ TRACKER_VERSION@
diff --git a/src/libtracker-sparql/tracker-builder.vala b/src/libtracker-sparql/tracker-builder.vala
index 92486c0..bde2a22 100644
--- a/src/libtracker-sparql/tracker-builder.vala
+++ b/src/libtracker-sparql/tracker-builder.vala
@@ -18,6 +18,7 @@
  */
 
 public class Tracker.Sparql.Builder : Object {
+
 	public enum State {
 		UPDATE,
 		INSERT,
diff --git a/src/libtracker-sparql/tracker-uri.c b/src/libtracker-sparql/tracker-uri.c
index 709f34f..b3f07ec 100644
--- a/src/libtracker-sparql/tracker-uri.c
+++ b/src/libtracker-sparql/tracker-uri.c
@@ -137,10 +137,10 @@ find_conversion (const char  *format,
  *
  * The result is escaped using g_uri_escape_string().
  *
- * Returns: a newly-allocated string holding the result which should
- * be freed with g_free() when finished with.
+ * Returns: a newly-allocated string holding the result.
+ *  The returned string should be freed with g_free() when no longer needed.
  *
- * Since: 0.8
+ * Since: 0.9
  */
 gchar *
 tracker_sparql_escape_uri_vprintf (const gchar *format,
@@ -240,12 +240,12 @@ cleanup:
  * @Varargs: the parameters to insert into the format string
  *
  * Calls tracker_sparql_escpae_uri_vprintf() with the @Varargs supplied.
-
- * Returns: a newly-allocated string holding the result which should
- * be freed with g_free() when finished with.
  *
- * Since: 0.8
- **/
+ * Returns: a newly-allocated string holding the result.
+ *  The returned string should be freed with g_free() when no longer needed.
+ *
+ * Since: 0.9
+ */
 gchar *
 tracker_sparql_escape_uri_printf (const gchar *format, ...)
 {
diff --git a/src/libtracker-sparql/tracker-utils.vala b/src/libtracker-sparql/tracker-utils.vala
index 5c3af49..5faacac 100644
--- a/src/libtracker-sparql/tracker-utils.vala
+++ b/src/libtracker-sparql/tracker-utils.vala
@@ -21,6 +21,16 @@
 public extern string tracker_sparql_escape_uri_vprintf (string format, va_list args);
 public extern string tracker_sparql_escape_uri_printf (string format, ...);
 
+
+/**
+ * tracker_sparql_escape_string:
+ * @literal: a string to escape
+ *
+ * Escapes a string so that it can be used in a SPARQL query.
+ *
+ * Returns: a newly-allocated string with the escaped version of @literal.
+ *  The returned string should be freed with g_free() when no longer needed.
+ */
 public string tracker_sparql_escape_string (string literal) {
 	StringBuilder str = new StringBuilder ();
 	char *p = literal;



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]