[evolution-kolab/ek-wip-porting] src: GtkDoc comment fixes

[Christian Hilberg <chilberg src gnome org>]

commit 37200da4e40d7b5faa6f61a807206c2d47a62c91
Author: Christian Hilberg <hilberg kernelconcepts de>
Date:   Tue Dec 13 12:20:50 2011 +0100

    src: GtkDoc comment fixes
    
    * reflect API changes (due to porting) in
      GtkDoc docstrings
    * minor spelling/wording fixups
    * fixed ordering of function arg docs
      according to the respective prototypes

 src/addressbook/kolab-util-contact-cache.c |   29 ++++++++++++++++-----------
 src/calendar/kolab-util-calendar-cache.c   |    8 +++---
 src/libekolab/kolab-mail-access.c          |   29 ++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 16 deletions(-)
---
diff --git a/src/addressbook/kolab-util-contact-cache.c b/src/addressbook/kolab-util-contact-cache.c
index 94b090d..4e6a0d8 100644
--- a/src/addressbook/kolab-util-contact-cache.c
+++ b/src/addressbook/kolab-util-contact-cache.c
@@ -35,9 +35,9 @@
 /*----------------------------------------------------------------------------*/
 
 EContact*
-kolab_util_contact_cache_get_object (EBookBackendCache *cache, 
-                                     KolabMailAccess *koma, 
-                                     const gchar *uri, 
+kolab_util_contact_cache_get_object (EBookBackendCache *cache,
+                                     KolabMailAccess *koma,
+                                     const gchar *uri,
                                      const gchar *uid,
                                      gboolean bulk,
                                      GCancellable *cancellable,
@@ -122,17 +122,18 @@ kolab_util_contact_cache_update_object (EBookBackendCache *cache,
  * kolab_util_contact_cache_assure_uid_on_econtact:
  * @cache: An EBookBackendCache.
  * @koma: A KolabMailAccess instance.
- * @uri: An EContact uri string.
  * @econtact: An EContact.
+ * @uri: An EContact uri string.
  * @bulk: Whether or not this is a mass operation.
+ * @cancellable: A cancellation stack.
  * @error: GError placeholder.
  *
  * Sets a new uid to econtact and assures that it is not yet used in @koma.
  *
  * Returns: On Success TRUE is returned.
  */
-gboolean 
-kolab_util_contact_cache_assure_uid_on_econtact (EBookBackendCache *cache, 
+gboolean
+kolab_util_contact_cache_assure_uid_on_econtact (EBookBackendCache *cache,
                                                  KolabMailAccess *koma,
                                                  EContact *econtact,
                                                  const gchar *uri,
@@ -176,7 +177,7 @@ kolab_util_contact_cache_assure_uid_on_econtact (EBookBackendCache *cache,
 		}
 		if (tmp_contact == NULL) {
 			e_contact_set (econtact, E_CONTACT_UID, (gconstpointer) uid);
-			g_free (uid); 
+			g_free (uid);
 			break;
 		}
 		g_object_unref (tmp_contact);
@@ -193,9 +194,13 @@ kolab_util_contact_cache_assure_uid_on_econtact (EBookBackendCache *cache,
  * @koma: A KolabMailAccess object.
  * @query: The query string associated with the update operation.
  * @uri: The URI string for access to the @koma object.
+ * @cancellable: A cancellation stack.
+ * @error: A GError placeholder.
  *
  * Retrieves the changed and not yet cached objects and puts them into the
- * @cache. 
+ * @cache.
+ *
+ * Returns: TRUE on success.
  */
 gboolean
 kolab_util_contact_cache_update_on_query (EBookBackendCache *cache,
@@ -208,7 +213,7 @@ kolab_util_contact_cache_update_on_query (EBookBackendCache *cache,
 	GList *changed_uids = NULL;
 	gchar *sourcename = NULL;
 	GError *tmp_error = NULL;
-	
+
 	g_debug ("%s()[%u] called.", __func__, __LINE__);
 	sourcename = kolab_util_backend_get_relative_path_from_uri (uri);
 
@@ -217,7 +222,7 @@ kolab_util_contact_cache_update_on_query (EBookBackendCache *cache,
 	/* query may be NULL */
 	g_assert (uri != NULL);
 	/* cancellable may be NULL */
-	g_return_val_if_fail (error == NULL || *error == NULL, FALSE);	
+	g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
 
 	/* First task: Update the BackendCache in case of changes */
 	changed_uids = kolab_mail_access_query_changed_uids (koma,
@@ -261,8 +266,8 @@ kolab_util_contact_cache_get_contacts (EBookBackendCache *cache,
 	/* query may be NULL */
 	g_assert (uri != NULL);
 	/* cancellable may be NULL */
-	g_return_val_if_fail (error == NULL || *error == NULL, NULL);	
-	
+	g_return_val_if_fail (error == NULL || *error == NULL, NULL);
+
 	/* get list of Kolab UIDs */
 	uid_list = kolab_mail_access_query_uids (koma, sourcename, query, &tmp_error);
 	if (tmp_error != NULL) {
diff --git a/src/calendar/kolab-util-calendar-cache.c b/src/calendar/kolab-util-calendar-cache.c
index 4c4a67b..4015f97 100644
--- a/src/calendar/kolab-util-calendar-cache.c
+++ b/src/calendar/kolab-util-calendar-cache.c
@@ -49,15 +49,15 @@ G_DEFINE_TYPE (KolabUtilCalendarCache, kolab_util_calendar_cache, G_TYPE_OBJECT)
 
 /**
  * kolab_util_calendar_cache_get_tz:
+ * @cache: A Cache.
  * @comp: An ECalComponent (Some calendar entry).
- * @cache: An Cache.
- *
- * Returns: An ECalComponent containing a timezone or NULL if none is found.
  *.
  * The tzid of the ECalComponent DTSTART property is used to extract timezone
  * information from the supplied backend cache. The ECalComponent returned
  * should be freed, using g_object_unref (), once no longer needed. Note:
  * Events may not provide a timezone/TZID (like UTC)!
+ *
+ * Returns: An ECalComponent containing a timezone or NULL if none is found..
  */
 ECalComponent*
 kolab_util_calendar_cache_get_tz (ECalBackendCache *cache,
@@ -127,7 +127,7 @@ kolab_util_calendar_cache_get_tz (ECalBackendCache *cache,
 
 /**
  * kolab_util_calendar_cache_get_object:
- * @cal_cache: An Cache.
+ * @cal_cache: A Cache.
  * @koma: A KolabMailAccess object.
  * @uri: An ECalComponent uri string.
  * @uid: The uid to search for.
diff --git a/src/libekolab/kolab-mail-access.c b/src/libekolab/kolab-mail-access.c
index cafd779..b2c55fc 100644
--- a/src/libekolab/kolab-mail-access.c
+++ b/src/libekolab/kolab-mail-access.c
@@ -1714,6 +1714,7 @@ kolab_mail_access_get_settings_handler (KolabMailAccess *self)
 /**
  * kolab_mail_access_bringup:
  * @self: a #KolabMailAccess instance
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Gets the #KolabMailAccess object into operational (offline) mode,
@@ -1759,6 +1760,7 @@ kolab_mail_access_bringup (KolabMailAccess *self,
 /**
  * kolab_mail_access_shutdown:
  * @self: a #KolabMailAccess instance
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Shuts down the #KolabMailAccess object from any operational mode,
@@ -1807,6 +1809,7 @@ kolab_mail_access_shutdown (KolabMailAccess *self,
  * kolab_mail_access_set_opmode:
  * @self: a #KolabMailAccess instance
  * @opmode: The operational mode to switch to (see #KolabMailAccessOpmodeID)
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Sets the operational mode for the object. To set an operational mode, an
@@ -2008,6 +2011,7 @@ kolab_mail_access_query_uids (KolabMailAccess *self,
  * @self: a #KolabMailAccess instance
  * @sourcename: the name of an address book or calendar (or NULL)
  * @sexp: an EDS search expression string (or NULL)
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Aggregates a list of UID strings known to #KolabMailAccess for which
@@ -2096,6 +2100,7 @@ kolab_mail_access_query_changed_uids (KolabMailAccess *self,
  * @self: a #KolabMailAccess instance
  * @uid: the UID to get the #KolabMailHandle for
  * @sourcename: the name of an address book or calendar (or NULL)
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Gets the #KolabMailHandle representing the PIM email associated with @uid.
@@ -2206,6 +2211,7 @@ kolab_mail_access_get_handle (KolabMailAccess *self,
  * @self: a #KolabMailAccess instance
  * @kmailhandle: the #KolabMailHandle to store
  * @sourcename: the name of an address book or calendar (or NULL)
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Persistently stores the the PIM email data represented by #KolabMailHandle.
@@ -2362,6 +2368,7 @@ kolab_mail_access_store_handle (KolabMailAccess *self,
  * @self: a #KolabMailAccess instance
  * @kmailhandle: the #KolabMailHandle to retrieve PIM data for
  * @bulk: Whether or not this is a mass operation
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Retrieves the actual PIM data for a #KolabMailHandle. The PIM data is read
@@ -2511,6 +2518,7 @@ kolab_mail_access_retrieve_handle (KolabMailAccess *self,
  * kolab_mail_access_delete_handle:
  * @self: a #KolabMailAccess instance
  * @kmailhandle: the #KolabMailHandle to delete
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Deletes the PIM data associated with this #KolabMailHandle. The handle does
@@ -2609,6 +2617,7 @@ kolab_mail_access_delete_handle (KolabMailAccess *self,
  * @self: a #KolabMailAccess instance
  * @uid: the UID of the #KolabMailHandle to delete
  * @sourcename: the name of the source to delete an object from
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Looks up a #KolabMailHandle by it's @uid and deletes the PIM data
@@ -2789,6 +2798,7 @@ kolab_mail_access_query_sources (KolabMailAccess *self,
  * kolab_mail_access_create_source:
  * @self: a #KolabMailAccess instance
  * @sourcename: the name of the source to create
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Creates a source (address book or calendar) of the given name. A source
@@ -2868,6 +2878,7 @@ kolab_mail_access_create_source (KolabMailAccess *self,
  * kolab_mail_access_delete_source:
  * @self: a #KolabMailAccess instance
  * @sourcename: the name of the source to delete
+ * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Deletes a source (address book or calendar) of the given name.
@@ -2949,6 +2960,24 @@ kolab_mail_access_delete_source (KolabMailAccess *self,
 	return TRUE;
 }
 
+/**
+ * kolab_mail_access_delete_source:
+ * @self: a #KolabMailAccess instance
+ * @sourcename: the name of the source to delete
+ * @err: a #GError object (or NULL)
+ *
+ * Whether or not a free/busy generation trigger needs to be
+ * sent to the Kolab server for a given source. A trigger is
+ * needed in any event of a change to an event folder (other
+ * folders do not need to be triggered since they do not provide
+ * free/busy information). Sending the trigger may have been
+ * delayed due to offline operation. When going online, triggers
+ * for event folders which have seen offline changes need to
+ * be sent.
+ *
+ * Returns: TRUE if a trigger needs to be sent for a given source,
+ *          FALSE otherwise
+ */
 gboolean
 kolab_mail_access_source_fbtrigger_needed (KolabMailAccess *self,
                                            const gchar *sourcename,