Update documentations

5 files changed, 268 insertions, 152 deletions

diff --git a/libzeitgeist/enumerations.vala b/libzeitgeist/enumerations.vala
index 54c20178..438f91b2 100644
--- a/libzeitgeist/enumerations.vala
+++ b/libzeitgeist/enumerations.vala
@@ -1,12 +1,12 @@
 /* enumerations.vala
  *
  * Copyright © 2011-2012 Collabora Ltd.
- *             By Seif Lotfy <seif@lotfy.com>
- *             By Siegfried-Angel Gevatter Pujals <siegfried@gevatter.com>
+ *          By Seif Lotfy <seif@lotfy.com>
+ *          By Siegfried-Angel Gevatter Pujals <siegfried@gevatter.com>
  * Copyright © 2011 Manish Sinha <manishsinha@ubuntu.com>
  * Copyright © 2011 Michal Hruby <michal.mhr@gmail.com>
  * Copyright © 2012 Canonical Ltd.
- *             By Siegfried-A. Gevatter <siegfried.gevatter@collabora.co.uk>
+ *          By Siegfried-A. Gevatter <siegfried.gevatter@collabora.co.uk>
  *
  * 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
@@ -28,149 +28,186 @@ using Zeitgeist;
 namespace Zeitgeist
 {
 
+/**
+ * Errors which can be thrown when asynchronously querying for {@link Event}s.
+ */
 [DBus (name = "org.gnome.zeitgeist.DataModelError")]
 public errordomain DataModelError {
+    /**
+     * Signature sent over DBus is invalid.
+     */
     INVALID_SIGNATURE,
+    /**
+     * {@link Event} is NULL.
+     */
     NULL_EVENT,
+    /**
+     * Query return too many {@link Event}s.
+     */
     TOO_MANY_RESULTS
 }
 
+/**
+ * ZeitgeistResultType
+ *
+ * Used to control how the query results are grouped and sorted.
+ * See zeitgeist_log_find_events(), zeitgeist_log_find_event_ids(), and
+ * zeitgeist_index_search().
+ */
+
 public enum ResultType
 {
-    MOST_RECENT_EVENTS                   = 0,  //   All events with the most
-                                               // recent events first
-    LEAST_RECENT_EVENTS                  = 1,  //   All events with the oldest
-                                               // ones first
-    MOST_RECENT_SUBJECTS                 = 2,  //   One event for each subject
-                                               // only, ordered with the
-                                               // most recent events first
-    LEAST_RECENT_SUBJECTS                = 3,  //   One event for each subject
-                                               // only, ordered with oldest
-                                               // events first
-    MOST_POPULAR_SUBJECTS                = 4,  //   One event for each subject
-                                               // only, ordered by the
-                                               // popularity of the subject
-    LEAST_POPULAR_SUBJECTS               = 5,  //   One event for each subject
-                                               // only, ordered ascendingly
-                                               // by popularity of the
-                                               // subject
-    MOST_POPULAR_ACTOR                   = 6,  //   The last event of each
-                                               // different actor ordered
-                                               // by the popularity of the
-                                               // actor
-    LEAST_POPULAR_ACTOR                  = 7,  //   The last event of each
-                                               // different actor, ordered
-                                               // ascendingly by the
-                                               // popularity of the actor
-    MOST_RECENT_ACTOR                    = 8,  //   The actor that has been used
-                                               // to most recently
-    LEAST_RECENT_ACTOR                   = 9,  //   The actor that has been used
-                                               // to least recently
-    MOST_RECENT_ORIGIN                   = 10, //   The last event of each
-                                               // different subject origin.
-    LEAST_RECENT_ORIGIN                  = 11, //   The last event of each
-                                               // different subject origin,
-                                               // ordered by least
-                                               // recently used first
-    MOST_POPULAR_ORIGIN                  = 12, //   The last event of each
-                                               // different subject origin,
-                                               // ordered by the
-                                               // popularity of the origins
-    LEAST_POPULAR_ORIGIN                 = 13, //   The last event of each
-                                               // different subject origin,
-                                               // ordered ascendingly by
-                                               // the popularity of the
-                                               // origin
-    OLDEST_ACTOR                         = 14, //   The first event of each
-                                               // different actor
-    MOST_RECENT_SUBJECT_INTERPRETATION   = 15, //   One event for each subject
-                                               // interpretation only,
-                                               // ordered with the most
-                                               // recent events first
-    LEAST_RECENT_SUBJECT_INTERPRETATION  = 16, //   One event for each subject
-                                               // interpretation only,
-                                               // ordered with the least
-                                               // recent events first
-    MOST_POPULAR_SUBJECT_INTERPRETATION  = 17, //   One event for each subject
-                                               // interpretation only,
-                                               // ordered by the popularity
-                                               // of the subject
-                                               // interpretation
-    LEAST_POPULAR_SUBJECT_INTERPRETATION = 18, //   One event for each subject
-                                               // interpretation only,
-                                               // ordered ascendingly by
-                                               // popularity of the subject
-                                               // interpretation
-    MOST_RECENT_MIMETYPE                 = 19, //   One event for each mimetype
-                                               // only ordered with the
-                                               // most recent events first
-    LEAST_RECENT_MIMETYPE                = 20, //   One event for each mimetype
-                                               // only ordered with the
-                                               // least recent events first
-    MOST_POPULAR_MIMETYPE                = 21, //   One event for each mimetype
-                                               // only ordered by the
-                                               // popularity of the mimetype
-    LEAST_POPULAR_MIMETYPE               = 22, //   One event for each mimetype
-                                               // only ordered ascendingly
-                                               // by popularity of the
-                                               // mimetype
-    MOST_RECENT_CURRENT_URI              = 23, //   One event for each subject
-                                               // only by current_uri
-                                               // instead of uri ordered
-                                               // with the most recent
-                                               // events first
-    LEAST_RECENT_CURRENT_URI             = 24, // One event for each subject
-                                               // only by current_uri
-                                               // instead of uri ordered
-                                               // with oldest events first
-    MOST_POPULAR_CURRENT_URI             = 25, //   One event for each subject
-                                               // only by current_uri
-                                               // instead of uri ordered
-                                               // by the popularity of the
-                                               // subject
-    LEAST_POPULAR_CURRENT_URI            = 26, //   One event for each subject
-                                               // only by current_uri
-                                               // instead of uri
-                                               // ordered ascendingly by
-                                               // popularity of the subject
-    MOST_RECENT_EVENT_ORIGIN             = 27, //   The last event of each
-                                               // different origin
-    LEAST_RECENT_EVENT_ORIGIN            = 28, //   The last event of each
-                                               // different origin, ordered
-                                               // by least recently used
-                                               // first
-    MOST_POPULAR_EVENT_ORIGIN            = 29, //   The last event of each
-                                               // different origin ordered
-                                               // by the popularity of the
-                                               // origins
-    LEAST_POPULAR_EVENT_ORIGIN           = 30, //   The last event of each
-                                               // different origin, ordered
-                                               // ascendingly by the
-                                               // popularity of the origin
-    MOST_RECENT_CURRENT_ORIGIN           = 31, //   The last event of each
-                                               // different subject origin.
-    LEAST_RECENT_CURRENT_ORIGIN          = 32, //   The last event of each
-                                               // different subject origin,
-                                               // ordered by least
-                                               // recently used first
-    MOST_POPULAR_CURRENT_ORIGIN          = 33, //   The last event of each
-                                               // different subject origin,
-                                               // ordered by the
-                                               // popularity of the origins
-    LEAST_POPULAR_CURRENT_ORIGIN         = 34, //   The last event of each
-                                               // different subject origin,
-                                               // ordered ascendingly by
-                                               // the popularity of the
-                                               // origin
-    RELEVANCY                            = 100;//   Only allowed on
-                                               // zeitgeist_index_search().
-                                               // Events are sorted by query
-                                               // relevancy
+    /**
+     * All events with the most recent events first
+     */
+    MOST_RECENT_EVENTS                   = 0,
+    /**
+     * All events with the oldest
+     */
+    LEAST_RECENT_EVENTS                  = 1,
+    /**
+     * One event for each subject only, ordered with the most recent events first
+     */
+    MOST_RECENT_SUBJECTS                 = 2,
+    /**
+     * One event for each subject, only, ordered with oldest events first
+     */
+    LEAST_RECENT_SUBJECTS                = 3,
+    /**
+     * One event for each subject only, ordered by the popularity of the subject
+     */
+    MOST_POPULAR_SUBJECTS                = 4,
+    /**
+     * One event for each subject only, ordered ascendingly by popularity of the subject
+     */
+    LEAST_POPULAR_SUBJECTS               = 5,
+    /**
+     * The last event of each different actor ordered by the popularity of the actor
+     */
+    MOST_POPULAR_ACTOR                   = 6,
+    /**
+     * The last event of each different actor, ordered ascendingly by the popularity of the actor
+     */
+    LEAST_POPULAR_ACTOR                  = 7,
+    /**
+     * The actor that has been used to most recently
+     */
+    MOST_RECENT_ACTOR                    = 8,
+    /**
+     * The actor that has been used to least recently
+     */
+    LEAST_RECENT_ACTOR                   = 9,
+    /**
+     * The last event of each different subject origin.
+     */
+    MOST_RECENT_ORIGIN                   = 10,
+    /**
+     * The last event of each different subject origin, ordered by least recently used first
+     */
+    LEAST_RECENT_ORIGIN                  = 11,
+    /**
+     * The last event of each different subject origin, ordered by the popularity of the origins
+     */
+    MOST_POPULAR_ORIGIN                  = 12,
+    /**
+     * The last event of each different subject origin, ordered ascendingly by the popularity of the origin
+     */
+    LEAST_POPULAR_ORIGIN                 = 13,
+    /**
+     * The first event of each different actor
+     */
+    OLDEST_ACTOR                         = 14,
+    /**
+     * One event for each subject interpretation only, ordered with the most recent events first
+     */
+    MOST_RECENT_SUBJECT_INTERPRETATION   = 15,
+    /**
+     * One event for each subject interpretation only, ordered with the least recent events first
+     */
+    LEAST_RECENT_SUBJECT_INTERPRETATION  = 16,
+    /**
+     * One event for each subject interpretation only, ordered by the popularity of the subject interpretation
+     */
+    MOST_POPULAR_SUBJECT_INTERPRETATION  = 17,
+    /**
+     * One event for each subject interpretation only, ordered ascendingly by popularity of the subject interpretation
+     */
+    LEAST_POPULAR_SUBJECT_INTERPRETATION = 18,
+    /**
+     * One event for each mimetype only ordered with the most recent events first
+     */
+    MOST_RECENT_MIMETYPE                 = 19,
+    /**
+     * One event for each mimetype only ordered with the least recent events first
+     */
+    LEAST_RECENT_MIMETYPE                = 20,
+    /**
+     * One event for each mimetype only ordered by the popularity of the mimetype
+     */
+    MOST_POPULAR_MIMETYPE                = 21,
+    /**
+     * One event for each mimetype only ordered ascendingly by popularity of the mimetype
+     */
+    LEAST_POPULAR_MIMETYPE               = 22,
+    /**
+     * One event for each subject only by current_uri instead of uri ordered with the most recent events first
+     */
+    MOST_RECENT_CURRENT_URI              = 23,
+    /**
+     *  One event for each subject only by current_uri instead of uri ordered with oldest events first
+     */
+    LEAST_RECENT_CURRENT_URI             = 24,
+    /**
+     * One event for each subject only by current_uri instead of uri ordered by the popularity of the subject
+     */
+    MOST_POPULAR_CURRENT_URI             = 25,
+    /**
+     * One event for each subject only by current_uri instead of uri ordered ascendingly by popularity of the subject
+     */
+    LEAST_POPULAR_CURRENT_URI            = 26,
+    /**
+     * The last event of each different origin
+     */
+    MOST_RECENT_EVENT_ORIGIN             = 27,
+    /**
+     * The last event of each different origin, ordered by least recently used first
+     */
+    LEAST_RECENT_EVENT_ORIGIN            = 28,
+    /**
+     * The last event of each different origin ordered by the popularity of the origins
+     */
+    MOST_POPULAR_EVENT_ORIGIN            = 29,
+    /**
+     * The last event of each different origin, ordered ascendingly by the popularity of the origin
+     */
+    LEAST_POPULAR_EVENT_ORIGIN           = 30,
+    /**
+     * The last event of each different subject origin.
+     */
+    MOST_RECENT_CURRENT_ORIGIN           = 31,
+    /**
+     * The last event of each different subject origin, ordered by least recently used first
+     */
+    LEAST_RECENT_CURRENT_ORIGIN          = 32,
+    /**
+     * The last event of each different subject origin, ordered by the popularity of the origins
+     */
+    MOST_POPULAR_CURRENT_ORIGIN          = 33,
+    /**
+     * The last event of each different subject origin, ordered ascendingly by the popularity of the origin
+     */
+    LEAST_POPULAR_CURRENT_ORIGIN         = 34,
+    /**
+     * Only allowed on zeitgeist_index_search(). Events are sorted by query relevancy
+     */
+    RELEVANCY                            = 100;
 
-     /*
-     * Returns true if the results for the given result_type will be sorted
+    /**
+     * @param result_type A {@link ResultType}
+     *
+     * @return true if the results for the given result_type will be sorted
      * ascendantly by date, false if they'll be sorted descendingly.
-     **/
+     */
     public static bool is_sort_order_asc (ResultType result_type)
     {
         switch (result_type)
@@ -229,8 +266,14 @@ public enum ResultType
  */
 public enum RelevantResultType
 {
-    RECENT  = 0, // All uris with the most recent uri first
-    RELATED = 1, // All uris with the most related one first
+    /**
+     * All uris with the most recent uri first
+     */
+    RECENT  = 0,
+    /**
+     * All uris with the most related one first
+     */
+    RELATED = 1,
 }
 
 /**
@@ -244,11 +287,18 @@ public enum RelevantResultType
  */
 public enum StorageState
 {
-    NOT_AVAILABLE   = 0, // The storage medium of the events
-                         // subjects must not be available to the user
-    AVAILABLE       = 1, // The storage medium of all event subjects
-                         // must be immediately available to the user
-    ANY             = 2  // The event subjects may or may not be available
+    /**
+     * The storage medium of the events subjects must not be available to the user
+     */
+    NOT_AVAILABLE   = 0,
+    /**
+     * The storage medium of all event subjects must be immediately available to the user
+     */
+    AVAILABLE       = 1,
+    /**
+     * The event subjects may or may not be available
+     */
+    ANY             = 2
 }
 
 }
diff --git a/libzeitgeist/index.vala b/libzeitgeist/index.vala
index 31667f55..c4e9e211 100644
--- a/libzeitgeist/index.vala
+++ b/libzeitgeist/index.vala
@@ -164,6 +164,9 @@ public class Index : QueuedProxyWrapper
      *     have the results ordered by relevancy calculated in relation
      *     to "query"
      * @param cancellable a {@link GLib.Cancellable} to cancel the operation or %NULL
+     *
+     * @param relevancies numeric relevancies of the events returned by result_set
+     * @return {@link ResultSet} result_set.
      */
     public async ResultSet search_with_relevancies (
         string query,
diff --git a/libzeitgeist/remote.vala b/libzeitgeist/remote.vala
index 20127e4e..fe253e29 100644
--- a/libzeitgeist/remote.vala
+++ b/libzeitgeist/remote.vala
@@ -21,10 +21,25 @@
 
 namespace Zeitgeist
 {
+    /**
+     * Version struct consisting of the following fields:
+     * - major
+     * - minor
+     * - minus
+     */
     public struct VersionStruct
     {
+        /**
+         * Major version number.
+         */
         int major;
+        /**
+         * Minor version number.
+         */
         int minor;
+        /**
+         * Micro version number.
+         */
         int micro;
     }
 
diff --git a/libzeitgeist/subject.vala b/libzeitgeist/subject.vala
index b6536b86..3e425d3e 100644
--- a/libzeitgeist/subject.vala
+++ b/libzeitgeist/subject.vala
@@ -73,6 +73,21 @@ public class Subject : Object
         url_store = new StringChunk (4096);
     }
 
+    /** 
+     * Create a new Subject structure with predefined data
+     * @param uri The URI or URL of the subject
+     * @param interpretation The interpretation type of the subject.
+     * @param manifestation The manifestation type of the subject.
+     * @param mimetype The mimetype of the subject. Eg. <emphasis>text/plain</emphasis>
+     * @param origin The origin of the subject.
+     * @param text A small textual representation of the subject suitable for display
+     * @param storage String identifier for the storage medium the subject is on.
+     *
+     * @return A newly create {@link Subject} instance. The returned subject will
+     *          have a floating reference which will be consumed if you pass the
+     *          event to any of the methods provided by this library (like
+     *          adding it to an event).
+     */
     public Subject.full (string? uri=null,
         string? interpretation=null, string? manifestation=null,
         string? mimetype=null, string? origin=null, string? text=null,
@@ -87,6 +102,24 @@ public class Subject : Object
         this.storage = storage;
     }
 
+    /** 
+     * Create a new Subject structure to describe a move event
+     *
+     * @param source_uri The URI or URL of the subject
+     * @param source_origin The URI or URL of the subject
+     * @param destination_uri The URI or URL of the subject
+     * @param destination_origin The URI or URL of the subject
+     * @param interpretation The interpretation type of the subject.
+     * @param manifestation The manifestation type of the subject.
+     * @param mimetype The mimetype of the subject. Eg. <emphasis>text/plain</emphasis>
+     * @param text A small textual representation of the subject suitable for display
+     * @param storage String identifier for the storage medium the subject is on.
+     *
+     * @return A newly create {@link Subject} instance. The returned subject will
+     *          have a floating reference which will be consumed if you pass the
+     *          event to any of the methods provided by this library (like
+     *          adding it to an event).
+     */
     public Subject.move_event (
         string? source_uri=null, string? source_origin=null,
         string? destination_uri=null, string? destination_origin=null,
@@ -104,6 +137,17 @@ public class Subject : Object
         this.storage = storage;
     }
 
+    
+    /** 
+     * Create a new Subject structure from predefined {@link GLib.Variant} data
+     *
+     * @param subject_variant A {@link GLib.Variant} decscribing the subject data.
+     *
+     * @return A newly create {@link Subject} instance. The returned subject will
+     *          have a floating reference which will be consumed if you pass the
+     *          event to any of the methods provided by this library (like
+     *          adding it to an event).
+     */
     public Subject.from_variant (Variant subject_variant)
         throws DataModelError
     {
@@ -156,14 +200,15 @@ public class Subject : Object
         */
     }
 
+    /**
+     * @return true if this Subject matches *subject_template*. Empty
+     * fields in the template are treated as wildcards.
+     * Interpretations and manifestations are also matched if they are
+     * children of the types specified in `subject_template`.
+     * @param template_subject a {@link Subject}
+    */
     public bool matches_template (Subject template_subject)
     {
-        /**
-        Return True if this Subject matches *subject_template*. Empty
-        fields in the template are treated as wildcards.
-        Interpretations and manifestations are also matched if they are
-        children of the types specified in `subject_template`.
-        */
         if (!check_field_match (this.uri, template_subject.uri, false, true))
             return false;
         if (!check_field_match (this.current_uri, template_subject.current_uri, false, true))
diff --git a/libzeitgeist/utils.vala b/libzeitgeist/utils.vala
index 69a8e493..61e0b1b8 100644
--- a/libzeitgeist/utils.vala
+++ b/libzeitgeist/utils.vala
@@ -22,12 +22,11 @@
  *
  */
 
-/**
- * Utility functions. FOR INTERNAL USE ONLY
- */
-
 namespace Zeitgeist
 {
+    /**
+     * Utility functions. FOR INTERNAL USE ONLY
+     */
     namespace Utils
     {
         // Paths
@@ -86,6 +85,10 @@ namespace Zeitgeist
             return DATABASE_FILE_PATH;
         }
 
+        /**
+         * Sets the filepath of the database.
+         * @param path a {@link string}
+         */
         public void set_database_file_path (string path) {
             DATABASE_FILE_PATH = path;
         }