[evolution-kolab] KolabMailAccess: API doc updates for source create/delete

[Christian Hilberg <chilberg src gnome org>]

commit 0f354340799a9105ce28f4e18bc40dc0720aa725
Author: Christian Hilberg <hilberg kernelconcepts de>
Date:   Thu Sep 20 11:04:30 2012 +0200

    KolabMailAccess: API doc updates for source create/delete

 src/libekolab/kolab-mail-access.c |   43 +++++++++++++++++++------------------
 1 files changed, 22 insertions(+), 21 deletions(-)
---
diff --git a/src/libekolab/kolab-mail-access.c b/src/libekolab/kolab-mail-access.c
index eaf1ba4..b061eea 100644
--- a/src/libekolab/kolab-mail-access.c
+++ b/src/libekolab/kolab-mail-access.c
@@ -3010,21 +3010,25 @@ kolab_mail_access_query_folder_info_online (KolabMailAccess *self,
  * kolab_mail_access_create_source:
  * @self: a #KolabMailAccess instance
  * @sourcename: the name of the source to create
- * @sourcetype: the Kolab type of the source to create
+ * @sourcetype: the Kolab type ID of the source to create
  * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
  * Creates a source (email, address book or calendar) of the given name and type. A source
  * needs to be created using this function prior to storing a #KolabMailHandle
- * into this source. If the @sourcename supplied already exists, the function
- * simply returns successfully.
+ * into this source, if it did not already exist on the server. If the @sourcename supplied
+ * already exists, the function simply returns successfully. The create function is agnostic
+ * of the folder type and the folder context #KolabMailAccess is currently configured for,
+ * so any folder type can be created by this function.
  *
  * #KolabMailAccess is required to be in online operational mode for this function.
  * This is to ensure the source could actually be created on the server before storing
- * PIM objects in it. This is to minimize chances that PIM objects are stored
+ * PIM objects into it. This is to minimize chances that PIM objects are stored
  * locally in a source for which no folder can be created on the server.
  *
  * Returns: TRUE on success, FALSE otherwise
+ *
+ * Since: 3.6
  */
 gboolean
 kolab_mail_access_create_source (KolabMailAccess *self,
@@ -3136,26 +3140,23 @@ kolab_mail_access_create_source (KolabMailAccess *self,
  * @cancellable: A cancellation stack
  * @err: a #GError object (or NULL)
  *
- * Deletes a source (address book or calendar) of the given name.
- * If the @sourcename supplied does not exist (within the current context),
- * the function returns with an error.
+ * Deletes a source (email, address book or calendar) of the given name.
+ * If the @sourcename supplied no longer exists on the server, the function
+ * simply returns successfully. The deletion function is agnostic of the folder
+ * type and the folder context #KolabMailAccess is currently configured for,
+ * so any folder can be deleted by this function.
  *
- * CAUTION: Deleting a source means deleting all PIM data within it!
- * A deletion transaction which has been triggered successfully CANNOT be
- * cancelled!
+ * The local #KolabMailSideCache and #KolabMailInfoDb data is not updated,
+ * since the cache reaper of the E-D-S source registry will clean up the
+ * entire cache directory associated with the deleted sourcename once the
+ * #ESource instance for the folder has been removed by the registry service.
  *
- * If #KolabMailAccess is in online operational mode, the source gets deleted on
- * the Kolab server right away. If that fails or if #KolabMailAccess is in offline
- * operational mode, the source gets marked for deletion in the local cache
- * and is not reported as existing from that moment on any longer. All locally
- * cached PIM data within this source will be lost, no matter the current
- * operational mode. At the next synchronization point, the source will be
- * deleted from the server. There is presently no way of aborting this
- * procedure, once it has been started.
+ * #KolabMailAccess is required to be in online operational mode for this function.
+ * This is to ensure the source could actually be deleted from the server.
  *
- * Returns: TRUE on success,
- *          FALSE if the @sourcename supplied does not exist or
- *                if offline deletion failed (both with @err set)
+ * Returns: TRUE on success, FALSE otherwise
+ *
+ * Since: 3.6
  */
 gboolean
 kolab_mail_access_delete_source (KolabMailAccess *self,