[evolution-data-server] Libedataserver: Fixing gtk-doc comments and adding gtk-doc section headers

[Tristan Van Berkom <tvb src gnome org>]

commit 8b533530acc7a0a8cbe1092d3a05d5a9ba4c6ba2
Author: Tristan Van Berkom <tristan upstairslabs com>
Date:   Fri Dec 6 15:00:11 2013 +0900

    Libedataserver: Fixing gtk-doc comments and adding gtk-doc section headers

 libedataserver/e-cancellable-locks.c |    2 +-
 libedataserver/e-client.c            |   65 ++++++++++++++++++++++++++++-----
 libedataserver/e-collator.c          |   10 +++---
 libedataserver/e-operation-pool.c    |    6 ++--
 libedataserver/e-sexp.c              |    4 +-
 5 files changed, 66 insertions(+), 21 deletions(-)
---
diff --git a/libedataserver/e-cancellable-locks.c b/libedataserver/e-cancellable-locks.c
index 6b5e793..d78ca9c 100644
--- a/libedataserver/e-cancellable-locks.c
+++ b/libedataserver/e-cancellable-locks.c
@@ -24,7 +24,7 @@
 #include "e-cancellable-locks.h"
 
 /**
- * SECTION: e-cancellable-locks
+ * SECTION:e-cancellable-locks
  * @title: Cancellable Locks
  * @short_description: locks, which can listen for a #GCancellable during lock call
  *
diff --git a/libedataserver/e-client.c b/libedataserver/e-client.c
index 4308f08..1bf8788 100644
--- a/libedataserver/e-client.c
+++ b/libedataserver/e-client.c
@@ -27,6 +27,16 @@
  *      and kill e-client-private.h.  Would simplify things.  --mbarnes
  */
 
+
+/**
+ * SECTION: e-client
+ * @include: libedataserver/libedataserver.h
+ * @short_description: Base class for client handles
+ *
+ * This class provides some base functionality for clients
+ * such as #EBookClient and #ECalClient.
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -781,16 +791,27 @@ e_client_class_init (EClientClass *class)
        class->refresh = client_refresh;
        class->refresh_finish = client_refresh_finish;
 
+       /**
+        * EClient:capabilities:
+        *
+        * The capabilities of this client
+        */
        g_object_class_install_property (
                object_class,
                PROP_CAPABILITIES,
                g_param_spec_pointer (
                        "capabilities",
-                       NULL,
-                       NULL,
+                       "Capabilities",
+                       "The capabilities of this client",
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:main-context:
+        *
+        * The main loop context in which notifications for
+        * this client will be delivered.
+        */
        g_object_class_install_property (
                object_class,
                PROP_MAIN_CONTEXT,
@@ -803,46 +824,70 @@ e_client_class_init (EClientClass *class)
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:online:
+        *
+        * Whether this client's backing data is online.
+        */
        g_object_class_install_property (
                object_class,
                PROP_ONLINE,
                g_param_spec_boolean (
                        "online",
-                       NULL,
-                       NULL,
+                       "Online",
+                       "Whether this client is online",
                        FALSE,
                        G_PARAM_READWRITE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:opened:
+        *
+        * Whether this client is open and ready to use.
+        *
+        * Deprecated: 3.8: This property is no longer relevant and
+        * will always be %TRUE after successfully creating any concrete
+        * type of #EClient.
+        */
        g_object_class_install_property (
                object_class,
                PROP_OPENED,
                g_param_spec_boolean (
                        "opened",
-                       NULL,
-                       NULL,
+                       "Opened",
+                       "Whether this client is open and ready to use",
                        FALSE,
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:readonly:
+        *
+        * Whether this client's backing data is readonly.
+        */
        g_object_class_install_property (
                object_class,
                PROP_READONLY,
                g_param_spec_boolean (
                        "readonly",
-                       NULL,
-                       NULL,
+                       "Read only",
+                       "Whether this client's backing data is readonly",
                        FALSE,
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:source:
+        *
+        * The #ESource for which this client was created.
+        */
        g_object_class_install_property (
                object_class,
                PROP_SOURCE,
                g_param_spec_object (
                        "source",
-                       NULL,
-                       NULL,
+                       "Source",
+                       "The ESource for which this client was created",
                        E_TYPE_SOURCE,
                        G_PARAM_READWRITE |
                        G_PARAM_CONSTRUCT_ONLY |
diff --git a/libedataserver/e-collator.c b/libedataserver/e-collator.c
index 05b01ec..38db7db 100644
--- a/libedataserver/e-collator.c
+++ b/libedataserver/e-collator.c
@@ -285,7 +285,7 @@ convert_to_ustring (const gchar  *string,
 /**
  * e_collator_new:
  * @locale: The locale under which to sort
- * @error: (allow none): A location to store a #GError from the #E_COLLATOR_ERROR domain
+ * @error: (allow-none): A location to store a #GError from the #E_COLLATOR_ERROR domain
  *
  * Creates a new #ECollator for the given @locale,
  * the returned collator should be freed with e_collator_unref().
@@ -445,7 +445,7 @@ e_collator_unref (ECollator *collator)
  * e_collator_generate_key:
  * @collator: An #ECollator
  * @str: The string to generate a collation key for
- * @error: (allow none): A location to store a #GError from the #E_COLLATOR_ERROR domain
+ * @error: (allow-none): A location to store a #GError from the #E_COLLATOR_ERROR domain
  *
  * Generates a collation key for @str, the result of comparing
  * two collation keys with strcmp() will be the same result
@@ -577,10 +577,10 @@ e_collator_generate_key_for_index (ECollator       *collator,
 /**
  * e_collator_collate:
  * @collator: An #ECollator
- * @str_a: (allow none): A string to compare
- * @str_b: (allow none): The string to compare with @str_a
+ * @str_a: (allow-none): A string to compare
+ * @str_b: (allow-none): The string to compare with @str_a
  * @result: (out): A location to store the comparison result
- * @error: (allow none): A location to store a #GError from the #E_COLLATOR_ERROR domain
+ * @error: (allow-none): A location to store a #GError from the #E_COLLATOR_ERROR domain
  *
  * Compares @str_a with @str_b, the order of strings is determined by the parameters of @collator.
  *
diff --git a/libedataserver/e-operation-pool.c b/libedataserver/e-operation-pool.c
index 3672271..a85fd94 100644
--- a/libedataserver/e-operation-pool.c
+++ b/libedataserver/e-operation-pool.c
@@ -31,9 +31,9 @@ struct _EOperationPool {
 
 /**
  * e_operation_pool_new: (skip)
- * @max_threads:
- * @thread_func:
- * @user_data:
+ * @max_threads: Maximum number of threads for this pool
+ * @thread_func: Function to run for a given thread
+ * @user_data: The user data to pass to @thread_func
  *
  * FIXME: Document me.
  *
diff --git a/libedataserver/e-sexp.c b/libedataserver/e-sexp.c
index d661362..133cc1e 100644
--- a/libedataserver/e-sexp.c
+++ b/libedataserver/e-sexp.c
@@ -1745,8 +1745,8 @@ e_sexp_evaluate_occur_times (ESExp *f,
 
 /**
  * e_sexp_encode_bool:
- * @s:
- * @state:
+ * @s: A #GString to append to
+ * @state: The boolean value
  *
  * Encode a bool into an s-expression @s.  Bools are
  * encoded using #t #f syntax.