Documentation and autotools fixes

 - Added a custom index page for the C documentation
 - Removed duplicate Vala documentation
 - Added missing documentation, titles, fixed links, etc.
 - Fixed autotools to updated the docs whenever needed
 - Fixed autotools to update the ontology files whenever needed
 - Updated AUTHORS, added content to README

16 files changed, 124 insertions, 53 deletions

diff --git a/AUTHORS b/AUTHORS
index f03f1fd9..c3b09b4d 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,9 +1,22 @@
-Seif Lotfy <seif@lotfy.com>
-Siegfried-Angel Gevatter Pujals <siegfried@gevatter.com>
-Michael Hruby <michal.mhr@gmail.com>
-Manish Sinha <manishsinha@ubuntu.com>
-Stefano Candori <stefano.candori@gmail.com>
+Main developers:
+ Michael Hruby <michal.mhr@gmail.com>
+ Seif Lotfy <seif@lotfy.com>
+ Siegfried-Angel Gevatter Pujals <siegfried@gevatter.com>
+
+Contributors:
+ Christian Dywan <christian@twotoasts.de>
+ Manish Sinha <manishsinha@ubuntu.com>
+ Marc-Antoine Perennou <Marc-Antoine@Perennou.com>
+ Moritz Neeb <nt4u@kpvn.de>
+ Stefano Candori <stefano.candori@gmail.com>
+ Trever Fischer <tdfischer@fedoraproject.org>
 
 From the Python implementation:
  Markus Korn <thekorn@gmx.de>
- Mikkel Kamstrup Erlandsen <mikkel.kamstrup@gmail.com
+ Mikkel Kamstrup Erlandsen <mikkel.kamstrup@gmail.com>
+
+Zeitgeist development has been sponsored by:
+ - Canonical Ltd.
+ - Collabora Ltd.
+ - GNOME Foundation
+ - Google (Summer of Code)
diff --git a/MAINTAINERS b/MAINTAINERS
index e45908e2..c2054f4c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1,4 +1,3 @@
 Seif Lotfy <seif@lotfy.com>
 Siegfried-Angel Gevatter Pujals <siegfried@gevatter.com>
-Manish Sinha <manishsinha@ubuntu.com>
 Michael Hruby <michal.mhr@gmail.com>
diff --git a/README b/README
index e69de29b..d5b48bcf 100644
--- a/README
+++ b/README
@@ -0,0 +1,31 @@
+========================== ZEITGEIST ==========================
+
+Zeitgeist is a service which logs the users's activities and
+events (files opened, websites visites, conversations held with
+other people, etc.) and makes relevant information available to
+other applications.
+
+See AUTHORS for a list of contributors.
+
+For a list of changes between releases, see NEWS; a detailed
+changelog is available in the Git repository at:
+ http://cgit.freedesktop.org/zeitgeist/zeitgeist/
+
+You can also find some additional development and testing tools
+in the Git repository.
+
+---------------------------------------------------------------
+
+CONTRIBUTING
+------------
+
+Feel free to contact us on dev@zeitgeist-project.com or via IRC
+in #zeitgeist on irc.freenode.net.
+
+Coding conventions:
+
+ - Generally following the GNOME / Vala guidelines.
+ - Indentation with 4 spaces.
+ - No indentation for namespaces (except for historic reasons).
+ - In libzeitgeist/, "protected" used for non-public API when
+   "private"/"internal" can't be used.
diff --git a/data/ontology2code b/data/ontology2code
index a5a230e2..9148c4d0 100755
--- a/data/ontology2code
+++ b/data/ontology2code
@@ -274,15 +274,14 @@ class ValaSerializer(GenericSerializer):
 
 	@staticmethod
 	def symbol_link(symbol):
-		return '%s_%s' % (symbol.namespace, symbol.name)
+		return '%s.%s' % (symbol.namespace, symbol.name)
 
 	@classmethod
 	def build_doc(cls, symbol, doc_prefix=""):
 		"""
 		Build a C-style docstring for gtk-doc processing.
 		"""
-		uri_link = '<ulink url="%s">%s</ulink>' % (symbol.uri,
-			symbol.uri.replace('#', '&num;'))
+		uri_link = '[[%s]]' % (symbol.uri)
 		doc = symbol.doc
 
 		# List children
@@ -293,9 +292,10 @@ class ValaSerializer(GenericSerializer):
 			doc += '\n\n Children: None'
 
 		# List parents
-		parents = ['#' + cls.symbol_link(parent) for parent in symbol.parents]
-		if parents and not parents in (['#INTERPRETATION'], ['#MANIFESTATION']):
-			doc += '\n\n Parents: %s' % ', '.join(parents)
+		parents = [cls.symbol_link(parent) for parent in symbol.parents]
+		if parents:
+			doc += '\n\n Parents: %s' % ', '.join('{@link %s}' % parent
+				for parent in parents)
 		else:
 			doc += '\n\n Parents: None'
 	
@@ -419,3 +419,5 @@ if __name__ == "__main__":
 		generator.generate_vala()
 	elif sys.argv[1] == '--dump-python':
 		generator.generate_python()
+
+# vim:noexpandtab:ts=4:sw=4
diff --git a/doc/libzeitgeist/Makefile.am b/doc/libzeitgeist/Makefile.am
index fe864ee6..e3c3668e 100644
--- a/doc/libzeitgeist/Makefile.am
+++ b/doc/libzeitgeist/Makefile.am
@@ -15,36 +15,34 @@ VALADOC_FLAGS = \
 	--pkg gio-unix-2.0 \
 	--pkg sqlite3 \
 	--basedir $(top_srcdir)/libzeitgeist \
-	--package-name libzeitgeist2 \
+	--package-name "zeitgeist-2.0" \
 	--package-version $(PACKAGE_VERSION) \
+	--no-protected \
 	$(FILES) \
 	$(NULL)
 
-valadoc:
+docs_vala: $(FILES)
 	$(VALADOC) \
-		-o valadoc \
+		-o $@ \
 		$(VALADOC_FLAGS) \
 		$(NULL)
 
-devhelp:
-	$(VALADOC) \
-		-o devhelp \
-		--doclet devhelp \
-		$(VALADOC_FLAGS) \
-		$(NULL)
-
-gtkdoc:
+# The output directory can't be called "gtkdoc" or it'll conflict
+# with the "--doclet" option (it only works if the directory doesn't
+# exist prior to invocation).
+docs_c: $(FILES) zeitgeist-gtkdoc-index.sgml
+	install -D zeitgeist-gtkdoc-index.sgml $@/zeitgeist-2.0-docs.xml
 	$(VALADOC) \
 		-X $(top_srcdir)/libzeitgeist/zeitgeist.h \
 		-X -l -X $(top_srcdir)/libzeitgeist/.libs/libzeitgeist-2.0.so \
-		-o gtkdoc \
+		-o $@ \
 		--doclet gtkdoc \
 		$(VALADOC_FLAGS) \
 		$(NULL)
 
 clean-local:
-	rm -rf valadoc devhelp gtkdoc
+	rm -rf docs_vala docs_c
 
-all: valadoc devhelp gtkdoc
+all: docs_vala docs_c
 
 endif
diff --git a/libzeitgeist/Makefile.am b/libzeitgeist/Makefile.am
index 15fc9941..884006d0 100644
--- a/libzeitgeist/Makefile.am
+++ b/libzeitgeist/Makefile.am
@@ -2,6 +2,10 @@ NULL =
 
 lib_LTLIBRARIES = libzeitgeist-2.0.la
 
+ONTOLOGY = \
+	$(wildcard $(top_srcdir)/data/ontology/*.trig) \
+	$(NULL)
+
 AM_CPPFLAGS = \
 	$(ZEITGEIST_CFLAGS) \
 	-include $(CONFIG_HEADER) \
@@ -67,8 +71,8 @@ DISTCLEANFILES = \
 	zeitgeist-2.0.vapi \
 	$(NULL)
 
-# FIXME: can we make this depend on $(ontology_trig_DATA)?
-ontology_vala.stamp: ontology.vala.in ontology-uris.vala.in
+ontology_vala.stamp: ontology.vala.in ontology-uris.vala.in \
+		$(ONTOLOGY) $(top_srcdir)/data/ontology2code
 	$(AM_V_GEN)$(top_srcdir)/data/ontology2code --vala
 	@touch "$@"
 
diff --git a/libzeitgeist/data-source-registry.vala b/libzeitgeist/data-source-registry.vala
index dbebcc3a..f3831655 100644
--- a/libzeitgeist/data-source-registry.vala
+++ b/libzeitgeist/data-source-registry.vala
@@ -18,15 +18,11 @@
  *
  */
 
-/**
- * Query the Zeitgeist Data-Source Registry extension
- */
-
 namespace Zeitgeist
 {
 
     [DBus (name = "org.gnome.zeitgeist.DataSourceRegistry")]
-    public interface RemoteRegistry: Object
+    protected interface RemoteRegistry: Object
     {
         [DBus (signature = "a(sssa(asaasay)bxb)")]
         public abstract async Variant get_data_sources (
@@ -49,6 +45,9 @@ namespace Zeitgeist
             [DBus (signature = "(sssa(asaasay)bxb)")] Variant data_source);
     }
 
+    /**
+     * Query the Zeitgeist Data-Source Registry extension
+     */
     public class DataSourceRegistry : QueuedProxyWrapper
     {
 
diff --git a/libzeitgeist/event.vala b/libzeitgeist/event.vala
index d77a9edb..9112c3d7 100644
--- a/libzeitgeist/event.vala
+++ b/libzeitgeist/event.vala
@@ -72,7 +72,7 @@ private bool check_field_match (string? property,
 }
 
 /**
- * #Event objects abstract Zeitgeist events.
+ * #Event objects abstract Zeitgeist events
  *
  * The #Event class is one of the primary elements for communicating
  * with the Zeitgeist daemon. #Events serve two purposes
diff --git a/libzeitgeist/log.vala b/libzeitgeist/log.vala
index 437cdd48..693b941c 100644
--- a/libzeitgeist/log.vala
+++ b/libzeitgeist/log.vala
@@ -21,14 +21,29 @@
  *
  */
 
+/**
+ * Zeitgeist is an activity-logging framework to enable the desktop of
+ * the future.
+ *
+ * Its main component is the Zeitgeist engine, a D-Bus service that logs
+ * any events other applications send to it. An event may be anything like:
+ *  - The user opened/created/modified/closed a file, or visited a website.
+ *  - The user received an e-mail, a phone call or an IM notification.
+ *  - Someone modified a remote (eg. Google Drive) document owned by the user.
+ *
+ * This information is then made available to other Zeitgeist-enabled
+ * applications over a powerful querying and monitoring API, and can be used
+ * and analyzed to create intelligent or adaptive interfaces.
+ *
+ * Zeitgeist also comes with a blacklist extension to make sure the user
+ * always stays in control of what information is logged.
+ */
 namespace Zeitgeist
 {
 
 /**
  * Primary access point for talking to the Zeitgeist daemon
  *
- * include: zeitgeist.h
- *
  * #ZeitgeistLog encapsulates the low level access to the Zeitgeist daemon.
  * You can use it to manage the log by inserting and deleting entries as well
  * as do queries on the logged data.
diff --git a/libzeitgeist/monitor.vala b/libzeitgeist/monitor.vala
index f6b783f7..5a2b898a 100644
--- a/libzeitgeist/monitor.vala
+++ b/libzeitgeist/monitor.vala
@@ -20,12 +20,13 @@
  *
  */
 
+namespace Zeitgeist
+{
+
 /**
  * Listens for updates to the Zeitgeist event log
  *
- * include: zeitgeist.h
- *
- * A #ZeitgeistMonitor listens for updates to the Zeitgeist event log
+ * A #Monitor listens for updates to the Zeitgeist event log
  * matching a given set of templates and with timestamps in some predefined
  * time range.
  *
@@ -33,10 +34,6 @@
  * zeitgeist_log_install_monitor(). The monitor will not emit any of the
  * ::events-added or ::events-deleted signals before this.
  */
-
-namespace Zeitgeist
-{
-
 public class Monitor : Object, RemoteMonitor
 {
 
diff --git a/libzeitgeist/ontology-uris.vala.in b/libzeitgeist/ontology-uris.vala.in
index 79ca408c..cbcb8098 100644
--- a/libzeitgeist/ontology-uris.vala.in
+++ b/libzeitgeist/ontology-uris.vala.in
@@ -1,6 +1,6 @@
 /* ontology-uris.vala
  *
- * Copyright © 2009-2011 The Zeitgeist Team
+ * Copyright © 2009-2012 The Zeitgeist Team
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
diff --git a/libzeitgeist/remote.vala b/libzeitgeist/remote.vala
index 979e6866..cccaa7ec 100644
--- a/libzeitgeist/remote.vala
+++ b/libzeitgeist/remote.vala
@@ -29,7 +29,7 @@ namespace Zeitgeist
     }
 
     [DBus (name = "org.gnome.zeitgeist.Log")]
-    public interface RemoteLog : Object
+    protected interface RemoteLog : Object
     {
 
         [DBus (signature = "(xx)")]
@@ -100,7 +100,7 @@ namespace Zeitgeist
     }
 
     [DBus (name = "org.gnome.zeitgeist.Monitor")]
-    public interface RemoteMonitor : Object
+    protected interface RemoteMonitor : Object
     {
 
         public async abstract void notify_insert (
@@ -116,7 +116,7 @@ namespace Zeitgeist
     }
 
     [DBus (name = "org.gnome.zeitgeist.Index")]
-    public interface RemoteSimpleIndexer : Object
+    protected interface RemoteSimpleIndexer : Object
     {
         public abstract async void search (
             string query_string,
@@ -138,7 +138,7 @@ namespace Zeitgeist
     /* FIXME: Remove this! Only here because of a bug
               in Vala (Vala Bug #661361) */
     [DBus (name = "org.freedesktop.NetworkManager")]
-    public interface NetworkManagerDBus : Object
+    protected interface NetworkManagerDBus : Object
     {
         [DBus (name = "state")]
         public abstract uint32 state () throws IOError;
@@ -148,7 +148,7 @@ namespace Zeitgeist
     /* FIXME: Remove this! Only here because of a bug
               in Vala (Vala Bug #661361) */
     [DBus (name = "net.connman.Manager")]
-    public interface ConnmanManagerDBus : Object
+    protected interface ConnmanManagerDBus : Object
     {
         public abstract string get_state () throws IOError;
         public signal void state_changed (string state);
diff --git a/libzeitgeist/subject.vala b/libzeitgeist/subject.vala
index 03de54c9..b6536b86 100644
--- a/libzeitgeist/subject.vala
+++ b/libzeitgeist/subject.vala
@@ -28,6 +28,13 @@ using Zeitgeist;
 namespace Zeitgeist
 {
 
+/**
+ * Subject objects abstract Zeitgeist subjects
+ *
+ * In Zeitgeist terminology, a //subject// is something (a file, web page,
+ * person, conversation, etc.) that was somehow involved or affected by
+ * a {@link Event}.
+ */
 public class Subject : Object
 {
     private static StringChunk url_store;
diff --git a/libzeitgeist/timerange.vala b/libzeitgeist/timerange.vala
index c9bf9842..4b0a6c54 100644
--- a/libzeitgeist/timerange.vala
+++ b/libzeitgeist/timerange.vala
@@ -28,6 +28,9 @@ namespace Zeitgeist
 {
 
 /**
+ * Immutable representation of an interval in time, marked by a
+ * beginning and an end
+ *
  * A light, immutable, encapsulation of an interval in time, marked by
  * a beginning and an end.
  */
diff --git a/libzeitgeist/utils.vala b/libzeitgeist/utils.vala
index 4534973e..31141982 100644
--- a/libzeitgeist/utils.vala
+++ b/libzeitgeist/utils.vala
@@ -194,7 +194,7 @@ namespace Zeitgeist
          *
          * @param s string to check
          */
-        internal bool is_empty_string (string? s)
+        public bool is_empty_string (string? s)
         {
             return s == null || s == "";
         }
diff --git a/python/Makefile.am b/python/Makefile.am
index cf2f1c46..7d160823 100644
--- a/python/Makefile.am
+++ b/python/Makefile.am
@@ -10,8 +10,11 @@ app_PYTHON = \
 	_ontology.py \
 	$(NULL)
 
-# FIXME: can we make this depend on $(ontology_trig_DATA)?
-_ontology.py:
+ONTOLOGY = \
+	$(wildcard $(top_srcdir)/data/ontology/*.trig) \
+	$(NULL)
+
+_ontology.py: $(ONTOLOGY) $(top_srcdir)/data/ontology2code
 	@echo -e "#\n# Auto-generated from .trig files. Do not edit.\n#" > $@
 	$(AM_V_GEN)$(top_srcdir)/data/ontology2code --dump-python >> $@