Some documentation work..

8 files changed, 129 insertions, 56 deletions

diff --git a/extensions/storage-monitor.vala b/extensions/storage-monitor.vala
index f1c1eeed..37489e4c 100644
--- a/extensions/storage-monitor.vala
+++ b/extensions/storage-monitor.vala
@@ -331,7 +331,7 @@ namespace Zeitgeist
             add_storage_medium (get_volume_id (volume), icon_name,
                 volume.get_name ());
         }
-        
+
         private void on_volume_removed (Volume volume)
         {
             debug ("Volume removed");
@@ -344,7 +344,7 @@ namespace Zeitgeist
          * as a `best effort` since we can not always uniquely identify
          * volumes, especially audio- and data CDs are problematic.
          */
-        
+
         /*private string get_volume_id (Volume volume)
         {
             string volume_id;
@@ -447,7 +447,7 @@ namespace Zeitgeist
      *  Network Manager (requires 0.8 or later).
      * See http://projects.gnome.org/NetworkManager/developers/spec-08.html
      */
-    class NMNetworkMonitor : Object, NetworkMonitor
+    private class NMNetworkMonitor : Object, NetworkMonitor
     {
         private const string NM_BUS_NAME = "org.freedesktop.NetworkManager";
         private const string NM_IFACE = "org.freedesktop.NetworkManager";
@@ -494,7 +494,7 @@ namespace Zeitgeist
         }
     }
 
-    class ConnmanNetworkMonitor : Object, NetworkMonitor
+    private class ConnmanNetworkMonitor : Object, NetworkMonitor
     {
         private const string CM_BUS_NAME = "net.connman";
         private const string CM_IFACE = "net.connman.Manager";
diff --git a/libzeitgeist/datamodel.vala b/libzeitgeist/datamodel.vala
index a6f64cee..b5fb8801 100644
--- a/libzeitgeist/datamodel.vala
+++ b/libzeitgeist/datamodel.vala
@@ -24,12 +24,9 @@
 
 using Zeitgeist;
 
-/**
- * Data model for Zeitgeist (Event, Subject, TimeRange, ResultType, etc.)
- */
-
 namespace Zeitgeist
 {
+
     [DBus (name = "org.gnome.zeitgeist.DataModelError")]
     public errordomain DataModelError {
         INVALID_SIGNATURE,
@@ -52,33 +49,64 @@ namespace Zeitgeist
         return null;
     }
 
+    /**
+     * A light, immutable, encapsulation of an interval in time, marked by
+     * a beginning and an end.
+     */
     [CCode (type_signature = "(xx)")]
     public class TimeRange: Object
     {
         public int64 start { get; private set; }
         public int64 end { get; private set; }
 
+        /**
+         * @param start_msec starting timestamp in number of milliseconds
+         *        since the Unix Epoch
+         * @param end_msec ending timestamp in number of milliseconds
+         *        since the Unix Epoch
+         * @param a newly allocated ZeitgeistTimeRange. Free with
+         *        g_object_unref()
+         */
         public TimeRange (int64 start_msec, int64 end_msec)
         {
             start = start_msec;
             end = end_msec;
         }
 
+        /**
+         * @return a new time range starting from the beginning of the Unix
+         *         Epoch stretching to the end of time
+         */
         public TimeRange.anytime ()
         {
             this (0, int64.MAX);
         }
 
+        /**
+         * @return a new time range starting from the beggining of the
+         *         Unix Epoch ending a the moment of invocation
+         */
         public TimeRange.to_now ()
         {
             this (0, Timestamp.from_now ());
         }
 
+        /**
+         * @return a new time range starting from the moment of invocation
+         *         to the end of time
+         */
         public TimeRange.from_now ()
         {
             this (Timestamp.from_now (), int64.MAX);
         }
 
+        /**
+         * Create a #TimeRange from a variant.
+         *
+         * @param variant a variant representing a #TimeRange
+         * @return a new time range starting from the moment of invocation
+         *         to the end of time
+         */
         public TimeRange.from_variant (Variant variant)
             throws DataModelError
         {
@@ -93,11 +121,21 @@ namespace Zeitgeist
             this (start_msec, end_msec);
         }
 
+        /**
+         * @param a #TimeRange
+         * @return a new variant holding the time range
+         */
         public Variant to_variant ()
         {
             return new Variant ("(xx)", start, end);
         }
 
+        /**
+         * Check whether two time ranges are intersecting.
+         *
+         * @param time_range the second time range to compare with
+         * @return a new time range representing the intersection
+         */
         public TimeRange? intersect (TimeRange time_range)
         {
             var result = new TimeRange(0,0);
@@ -370,15 +408,54 @@ namespace Zeitgeist
         return (is_negated) ? !matches : matches;
     }
 
+    /**
+     * #Event objects abstract Zeitgeist events.
+     *
+     * The #Event class is one of the primary elements for communicating
+     * with the Zeitgeist daemon. #Events serve two purposes
+     * Unsurprisingly, they represent events that have happened, but they
+     * can also act as templates. See also #Subject.
+     *
+     * An event in the Zeitgeist world is characterized by two main
+     * properties. "What happened", also called the interpretation, and
+     * "How did it happen", also called the manifestation. Besides these
+     * properties, an event also has an actor which identifies the party
+     * responsible for triggering the event which in most cases will be
+     * an application. Lastly there is an event timestamp and an event ID.
+     * The timestamp is calculated as the number of milliseconds since the
+     * Unix epoch and the event ID is a number assigned to the event by
+     * the Zeitgeist engine when it's logged. These five properties are
+     * collectively known as the event metadata.
+     *
+     * An event must also describe what it happened to. For this we have
+     * event subjects. Most events have one subject, but they may also
+     * have more. The metadata of the subjects are recorded at the time
+     * of logging, and are encapsulated by the #Subject class. It's
+     * important to understand that it's just the subject metadata at the
+     * time of logging, not necessarily the subject metadata as it exists
+     * right now.
+     *
+     * In addition to the listed properties, events may also carry a free
+     * form binary payload. The usage of this is application specific and
+     * is generally useless unless you have some contextual information to
+     * figure out what's in it.
+     *
+     * A large part of the Zeitgeist query and monitoring API revolves
+     * around a concept of template matching. A query is simply a list of
+     * event templates that you want to look for in the log. An unset
+     * property on an event template indicates that anything is allowed in
+     * that field. If the property is set it indicates that the property
+     * must be an exact match, unless a special operator is used.
+     */
     public class Event : Object
     {
         public const string SIGNATURE = "asaasay";
 
         private static StringChunk url_store;
 
-        public uint32    id { get; set; }
-        public int64     timestamp { get; set; }
-        public string?   origin { get; set; }
+        public uint32  id { get; set; }
+        public int64   timestamp { get; set; }
+        public string? origin { get; set; }
 
         public string? actor
         {
diff --git a/libzeitgeist/index.vala b/libzeitgeist/index.vala
index f2ebb990..0c3d669d 100644
--- a/libzeitgeist/index.vala
+++ b/libzeitgeist/index.vala
@@ -77,25 +77,22 @@ public class Index : QueuedProxyWrapper
      * and/or set of event templates.
      *
      * The default boolean operator is %AND. Thus the query
-     * <emphasis>foo bar</emphasis> will be interpreted as
-     * <emphasis>foo AND bar</emphasis>. To exclude a term from the result
-     * set prepend it with a minus sign - eg <emphasis>foo -bar</emphasis>.
+     * //foo bar// will be interpreted as //foo AND bar//. To exclude a term
+     * from the result set prepend it with a minus sign - eg. //foo -bar//.
      * Phrase queries can be done by double quoting the string
-     * <emphasis>"foo is a bar"</emphasis>. You can truncate terms by appending
-     * a *.
+     * //"foo is a bar"//. You can truncate terms by appending a *.
      *
      * There are a few keys you can prefix to a term or phrase to search within
-     * a specific set of metadata. They are used like
-     * <emphasis>key:value</emphasis>. The keys <emphasis>name</emphasis> and
-     * <emphasis>title</emphasis> search strictly within the text field of the
-     * event subjects. The key <emphasis>app</emphasis> searches within the
-     * application name or description that is found in the actor attribute of
-     * the events. Lastly you can use the <emphasis>site</emphasis> key to search
-     * within the domain name of the subject URIs.
+     * a specific set of metadata. They are used like //key:value//. The keys
+     * //name// and //title// search strictly within the text field of the
+     * event subjects. The key //app// searches within the application name or
+     * description that is found in the actor attribute of the events. Lastly,
+     * you can use the //site// key to search within the domain name of subject
+     * URIs.
      *
-     * You can also control the results with the boolean operators
-     * <emphasis>AND</emphasis> and <emphasis>OR</emphasis> and you may
-     * use brackets, ( and ), to control the operator precedence.
+     * You can also control the results with the boolean operators //AND// and
+     * //OR// and you may use brackets, ( and ), to control the operator
+     * precedence.
      *
      * FIXME: how do we put documentation into _finish?
      * The total hit count of the query will be available via the returned
@@ -104,7 +101,6 @@ public class Index : QueuedProxyWrapper
      * which is limited by the @num_events parameter passed to
      * zeitgeist_index_search().
      *
-     * @param self The #ZeitgeistIndex you want to query
      * @param query The search string to send to Zeitgeist
      * @param time_range Restrict matched events to ones within this time
      *     range. If you are not interested in restricting the timerange pass
@@ -119,9 +115,6 @@ public class Index : QueuedProxyWrapper
      *     method to have the results ordered by relevancy calculated
      *     in relation to @query
      * @param cancellable A #GCancellable used to cancel the call or %NULL
-     * @param callback A #GAsyncReadyCallback to invoke when the search results
-     *     are ready
-     * @param user_data User data to pass back with @callback
      */
     public async ResultSet search (
         string query,
@@ -154,7 +147,6 @@ public class Index : QueuedProxyWrapper
      * See zeitgeist_index_search() for more details on how to create the
      * query.
      *
-     * @param self The #ZeitgeistIndex you want to query
      * @param query The search string to send to Zeitgeist
      * @param time_range Restrict matched events to ones within this time
      *     range. If you are not interested in restricting the timerange pass
@@ -171,9 +163,6 @@ public class Index : QueuedProxyWrapper
      *     have the results ordered by relevancy calculated in relation
      *     to "query"
      * @param cancellable A #GCancellable used to cancel the call or %NULL
-     * @param callback A #GAsyncReadyCallback to invoke when the searc
-     *     results are ready
-     * @param user_data User data to pass back with @callback
      */
     public async ResultSet search_with_relevancies (
         string query,
diff --git a/libzeitgeist/log.vala b/libzeitgeist/log.vala
index 8d50e002..437cdd48 100644
--- a/libzeitgeist/log.vala
+++ b/libzeitgeist/log.vala
@@ -269,10 +269,9 @@ public class Log : QueuedProxyWrapper
     * the value of the "is-connected" property must be TRUE (you can connect
     * to the "notify::is-connected" signal otherwise).
     *
-    * @param self A #ZeitgeistLog instance
     * @param major Location for the major version
     * @param minor Location for the minor version
-    * @param micro: Location for the micro version
+    * @param micro Location for the micro version
     */
     public void get_version (out int major, out int minor, out int micro) {
         major = minor = micro = 0;
diff --git a/libzeitgeist/mimetype.vala b/libzeitgeist/mimetype.vala
index c7922384..5bece6d5 100644
--- a/libzeitgeist/mimetype.vala
+++ b/libzeitgeist/mimetype.vala
@@ -112,7 +112,7 @@ namespace Zeitgeist
      *
      * FIXME: link to list of interpretations
      *
-     * @param mimetype A regular expression matching a certain range of
+     * @param mimetype_regex A regular expression matching a certain range of
      *     mimetypes. Eg. //text/.* // to match all //text// subtypes.
      * @param interpretation_uri A URI defining the subject interpretation
      *     type to associate with the matched MIME-types
@@ -174,7 +174,7 @@ namespace Zeitgeist
      * FIXME: link to list of manifestations
      *
      * @param uri_scheme A URI scheme such as //http:\/\///
-     * @param manifestation_uri A URI defining the subject manifestation type
+     * @param manifestation_type A URI defining the subject manifestation type
      *     to associate with "uri_scheme"
      */
     public void register_uri_scheme (string uri_scheme,
diff --git a/libzeitgeist/result-set.vala b/libzeitgeist/result-set.vala
index 43f9eaab..d89a95ba 100644
--- a/libzeitgeist/result-set.vala
+++ b/libzeitgeist/result-set.vala
@@ -49,8 +49,6 @@ public interface ResultSet : Object
      * size of the result set is always equal to the number of times you can call
      * zeitgeist_result_set_next().
      *
-     * @param self The #ZeitgeistResultSet to get the size of
-     *
      * @return The number of events held in the result set
      */
     public abstract uint size ();
@@ -65,8 +63,6 @@ public interface ResultSet : Object
      * zeitgeist_index_search() where you specify a subset of the hits to retrieve
      * the estimated match count will often be bigger than the result set size.
      *
-     * @param self The #ZeitgeistResultSet to get the number of estimated
-     *     matches on
      * @return The number of events that matched the query
      */
     public abstract uint estimated_matches ();
@@ -76,8 +72,6 @@ public interface ResultSet : Object
      * ensure that calls to this method will succeed you can call
      * zeitgeist_result_set_has_next().
      *
-     * @param self The #ZeitgeistResultSet to get an event from
-     *
      * @return The #ZeitgeistEvent at the current cursor position, or NULL
      *         if there are no events left.
      */
@@ -86,8 +80,6 @@ public interface ResultSet : Object
     /**
      * Check if a call to zeitgeist_result_set_next() will succeed.
      *
-     * @param self The #ZeitgeistResultSet to check
-     *
      * @return TRUE if and only if more events can be retrieved
      *         by calling zeitgeist_result_set_next()
      */
@@ -96,8 +88,6 @@ public interface ResultSet : Object
     /**
      * Get the current position of the cursor.
      *
-     * @param self The #ZeitgeistResultSet to check the cursor position for
-     *
      * @return The current position of the cursor
      */
     public abstract uint tell ();
@@ -105,7 +95,6 @@ public interface ResultSet : Object
     /**
      * Resets the result set to start iterating it again from scratch.
      *
-     * @param self The #ZeitgeistResultSet to reset
      */
     public abstract void reset ();
 
diff --git a/libzeitgeist/timestamp.vala b/libzeitgeist/timestamp.vala
index 462332a7..30aeadd2 100644
--- a/libzeitgeist/timestamp.vala
+++ b/libzeitgeist/timestamp.vala
@@ -67,7 +67,9 @@ namespace Zeitgeist.Timestamp
     public const int64 YEAR = 31556952000;
 
     /**
-     * ...
+     * Convert a #GTimeVal to the amount of milliseconds since the Unix Epoch
+     *
+     * @param timeval time to convert
      *
      * @return number of milliseconds since the Unix Epoch
      */
@@ -78,30 +80,32 @@ namespace Zeitgeist.Timestamp
     }
 
     /**
-     * ...
-     *
      * Write a Zeitgeist timestamp to a #GTimeVal instance. Note that Zeitgeist
      * uses only a millisecond resolution for where #GTimeVal uses a microsecond
      * resolution, meaning that the lower three digits of @tv.tv_usec will
      * be 0.
+     *
+     * @param timestamp to convert
+     *
+     * @return the equivalent #GTimeVal instance.
      */
     public TimeVal to_timeval (int64 timestamp)
     {
         TimeVal timeval = TimeVal();
-        timeval.tv_sec = (long) (timestamp/1000);
+        timeval.tv_sec = (long) (timestamp / 1000);
         timeval.tv_usec = (long) ((timestamp % 1000) * 1000);
         return timeval;
     }
 
     /**
-     * ...
+     * Return the current timestamp in milliseconds.
      *
      * @return the timestamp for the current system time, in milliseconds
      *         since the Unix Epoch
      */
     public int64 from_now ()
     {
-        return get_real_time ()/1000;
+        return get_real_time () / 1000;
     }
 
     /**
@@ -169,7 +173,10 @@ namespace Zeitgeist.Timestamp
     }
 
     /**
-     * Write a timestamp to a ''GDate'' structure
+     * Write a timestamp to a #GDate structure
+     *
+     * @param timestamp to convert
+     * @return #GDate initialized to the given timestamp
      */
     public Date to_date (int64 timestamp)
     {
diff --git a/libzeitgeist/utils.vala b/libzeitgeist/utils.vala
index c9032f3b..cc175721 100644
--- a/libzeitgeist/utils.vala
+++ b/libzeitgeist/utils.vala
@@ -118,6 +118,10 @@ namespace Zeitgeist
             return LOCAL_EXTENSIONS_PATH;
         }
 
+        /**
+         * @return Whether a in-memory SQLite database is in use (vs.
+         *         a file-based one).
+         */
         public bool using_in_memory_database ()
         {
             return get_database_file_path () == ":memory:";
@@ -139,6 +143,8 @@ namespace Zeitgeist
          * Check if the value starts with the negation operator. If it does,
          * remove the operator from the value and return true. Otherwise,
          * return false.
+         *
+         * @param val value to check
          */
         public static bool parse_negation (ref string val)
         {
@@ -154,6 +160,8 @@ namespace Zeitgeist
          * return false.
          *
          * Check for the negation operator before calling this function.
+         *
+         * @param val value to check
          */
         public static bool parse_noexpand (ref string val)
         {
@@ -168,6 +176,8 @@ namespace Zeitgeist
          * Check if the value ends with the wildcard character. If it does,
          * remove the wildcard character from the value and return true.
          * Otherwise, return false.
+         *
+         * @param val value to check
          */
         public static bool parse_wildcard (ref string val)
         {
@@ -181,6 +191,8 @@ namespace Zeitgeist
         /**
          * Return true if a string is empty (null or containing just a null
          * byte).
+         *
+         * @param s string to check
          */
         public static bool is_empty_string (string? s)
         {