Add new documentation

1 files changed, 156 insertions, 13 deletions

diff --git a/libzeitgeist/log.vala b/libzeitgeist/log.vala
index 781fc582..68d0eac5 100644
--- a/libzeitgeist/log.vala
+++ b/libzeitgeist/log.vala
@@ -44,7 +44,7 @@ namespace Zeitgeist
 /**
  * Primary access point for talking to the Zeitgeist daemon
  *
- * #ZeitgeistLog encapsulates the low level access to the Zeitgeist daemon.
+ * {@link Log} 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.
  *
@@ -82,6 +82,15 @@ public class Log : QueuedProxyWrapper
             });
     }
 
+
+    /**
+     * Get a unique instance of #ZeitgeistLog, that you can share in your
+     * application without caring about memory management.
+     *
+     * See zeitgeist_log_new() for more information.
+     *
+     * @return ZeitgeistLog.
+     */
     public static Log get_default ()
     {
         if (default_instance == null)
@@ -105,18 +114,13 @@ public class Log : QueuedProxyWrapper
     protected override void on_connection_lost () {
     }
 
-    public async void insert_event_no_reply (Event event)
-        throws Error
-    {
-        yield insert_event (event);
-    }
-
-    public async void insert_events_no_reply (GenericArray<Event> events)
-        throws Error
-    {
-        yield insert_events (events);
-    }
-
+    /**
+    * Asynchronously send a set of events to the Zeitgeist daemon, requesting they
+    * be inserted into the log.
+    *
+    * @param event A {@link Event}
+    * @param cancellable:To cancel the operation or NULL
+    */
     public async Array<uint32> insert_event (Event event,
         Cancellable? cancellable=null) throws Error
     {
@@ -125,6 +129,14 @@ public class Log : QueuedProxyWrapper
         return yield insert_events (events, cancellable);
     }
 
+
+    /**
+    * Asynchronously send a set of events to the Zeitgeist daemon, requesting they
+    * be inserted into the log.
+    *
+    * @param events An {@link GenericArray} of {@link Event}
+    * @param cancellable To cancel the operation or NULL
+    */
     public async Array<uint32> insert_events (GenericArray<Event> events,
         Cancellable? cancellable=null) throws Error
     {
@@ -138,6 +150,64 @@ public class Log : QueuedProxyWrapper
         return result;
     }
 
+    /**
+    * Asynchronously send a set of events to the Zeitgeist daemon, requesting they
+    * be inserted into the log.
+    * This method is &quot;fire and forget&quot; and the caller will never know
+    * whether the events was successfully inserted or not.
+    *
+    * This method is exactly equivalent to calling zeitgeist_log_insert_event()
+    * with NULL set as @cancellable, @callback, and @user_data.
+    *
+    * @param event A {@link Event}
+    */
+    public async void insert_event_no_reply (Event event)
+        throws Error
+    {
+        yield insert_event (event);
+    }
+
+    /**
+    * Asynchronously send a set of events to the Zeitgeist daemon, requesting they
+    * be inserted into the log.
+    * This method is &quot;fire and forget&quot; and the caller will never know
+    * whether the events was successfully inserted or not.
+    *
+    * This method is exactly equivalent to calling zeitgeist_log_insert_event()
+    * with NULL set as @cancellable, @callback, and @user_data.
+    *
+    * @param events An {@link GenericArray} of {@link Event}
+    */
+    public async void insert_events_no_reply (GenericArray<Event> events)
+        throws Error
+    {
+        yield insert_events (events);
+    }
+
+    /**
+    * Send a query matching a collection of {@link Event} templates to the {@link Log}.
+    * The query will match if an event matches any of the templates. If an event
+    * template has more than one {@link Subject} the query will match if any one
+    * of the {@link Subject}s templates match.
+    *
+    * The query will be done via an asynchronous DBus call and this method will
+    * return immediately. The return value will be passed to callback as a list
+    * of {@link Event}s. This list must be the sole argument for the callback.
+    *
+    * If you need to do a query yielding a large (or unpredictable) result set
+    * and you only want to show some of the results at the same time (eg., by
+    * paging them), consider using {@link find_event_ids_for_templates}.
+    *
+    * In order to use this method there needs to be a mainloop runnning.
+    * Both Qt and GLib mainloops are supported.
+    *
+    * @param time_range {@link TimeRange} A time range in which the events should be considered in
+    * @param storage_state {@link StorageState} storage state
+    * @param event_templates An {@link GenericArray} of {@link Event}
+    * @param num_events int represteing the number of events that should be returned
+    * @param result_type {@link ResultType} how the events should be grouped and sorted
+    * @param cancellable To cancel the operation or NULL
+    */
     public async ResultSet find_events (
         TimeRange time_range,
         GenericArray<Event> event_templates,
@@ -153,6 +223,28 @@ public class Log : QueuedProxyWrapper
         return new SimpleResultSet (Events.from_variant (result));
     }
 
+
+    /**
+    * Send a query matching a collection of {@link Event} templates to the {@link Log}.
+    * The query will match if an event matches any of the templates. If an event
+    * template has more than one {@link Subject} the query will match if any one
+    * of the {@link Subject}s templates match.
+    *
+    * The query will be done via an asynchronous DBus call and this method will
+    * return immediately. The return value will be passed to callback as a list
+    * of intergers represrting {@link Event} id's.
+    * This list must be the sole argument for the callback.
+    *
+    * In order to use this method there needs to be a mainloop runnning.
+    * Both Qt and GLib mainloops are supported.
+    *
+    * @param time_range {@link TimeRange} A time range in which the events should be considered in
+    * @param storage_state {@link StorageState} storage state
+    * @param event_templates An {@link GenericArray} of {@link Event}
+    * @param num_events int represteing the number of events that should be returned
+    * @param result_type {@link ResultType} how the events should be grouped and sorted
+    * @param cancellable To cancel the operation or NULL
+    */
     public async uint32[] find_event_ids (
         TimeRange time_range,
         GenericArray<Event> event_templates,
@@ -167,6 +259,22 @@ public class Log : QueuedProxyWrapper
             num_events, result_type, cancellable);
     }
 
+    /**
+    * Look up a collection of {@link Event} in the {@link Log} given a collection
+    * of event ids. This is useful for looking up the event data for events found
+    * with the find_event_ids_* family of functions.
+    *
+    * Each {@link Evnet} which is not found in the {@link Log} is represented by
+    * NULL in the resulting collection. The query will be done via an asynchronous
+    * DBus call and this method will return immediately. The returned events will
+    * be passed to callback as a list of {@link Event}s, which must be the only
+    * argument of the function.
+    *
+    * In order to use this method there needs to be a mainloop runnning.
+    *
+    * @param Array<int> {@link Event} ids
+    * @param cancellable To cancel the operation or NULL
+    */
     public async GenericArray<Event> get_events (
         Array<uint32> event_ids,
         Cancellable? cancellable=null) throws Error
@@ -179,6 +287,21 @@ public class Log : QueuedProxyWrapper
         return Events.from_variant (result);
     }
 
+    /**
+    * Warning: This API is EXPERIMENTAL and is not fully supported yet.
+    *
+    * Get a list of URIs of subjects which frequently occur together with events
+    * matching event_templates. Possibly restricting to time_range or to URIs
+    * that occur as subject of events matching result_event_templates.
+    *
+    * @param time_range {@link TimeRange} A time range in which the events should be considered in
+    * @param storage_state {@link StorageState} storage state
+    * @param event_templates An {@link GenericArray} of {@link Event} describing the events to relate to
+    * @param result_templates An {@link GenericArray} of {@link Event} desrcibing the result to be returned
+    * @param num_events int represteing the number of events that should be returned
+    * @param result_type {@link ResultType} how the events should be grouped and sorted
+    * @param cancellable To cancel the operation or NULL
+    */
     public async string[] find_related_uris (
         TimeRange time_range,
         GenericArray<Event> event_templates,
@@ -195,6 +318,14 @@ public class Log : QueuedProxyWrapper
             storage_state, num_events, result_type, cancellable);
     }
 
+
+    /**
+    * Delete a collection of events from the zeitgeist log given their event ids.
+    *
+    * The deletion will be done asynchronously, and this method returns immediately.
+    *
+    * @param event_ids Array<uint32>
+    */
     public async TimeRange delete_events (Array<uint32> event_ids,
             Cancellable? cancellable=null) throws Error
     {
@@ -212,6 +343,13 @@ public class Log : QueuedProxyWrapper
         yield proxy.quit (cancellable);
     }
 
+    /**
+    *Install a monitor in the Zeitgeist engine that calls back when events matching event_templates are logged. The matching is done exactly as in the find_* family of methods and in Event.matches_template. Furthermore matched events must also have timestamps lying in time_range.
+    *
+    * To remove a monitor call remove_monitor() on the returned Monitor instance.
+    *
+    * @param monitor A {@link Monitor} to report back inserts and deletes
+    */
     public void install_monitor (Monitor monitor) throws Error
     {
         // FIXME
@@ -250,6 +388,11 @@ public class Log : QueuedProxyWrapper
             Events.to_variant (monitor.get_templates ()));
     }
 
+    /**
+    * Remove a monitor from Zeitgeist engine that calls back when events matching event_templates are logged.
+    *
+    * @param monitor A {@link Monitor} to report back inserts and deletes
+    */
     public async void remove_monitor (Monitor monitor) throws Error
     {
         yield wait_for_proxy ();