[evolution-data-server] edataserver: GIR annotation fixes

[Philip Withnall <pwithnall src gnome org>]

commit 874cfbd0c6dbb130489c27e9b50e51d8da6da398
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Jun 18 16:12:36 2012 +0100

    edataserver: GIR annotation fixes
    
    Various documentation comment fixes, annotation additions, and the addition
    of libsoup as a GIR include since it appears in some proxy API.

 libedataserver/Makefile.am                 |    2 +-
 libedataserver/e-categories.c              |    7 +-
 libedataserver/e-client.c                  |   59 +++++----
 libedataserver/e-credentials.c             |    5 +-
 libedataserver/e-data-server-util.c        |   35 +++---
 libedataserver/e-gdbus-templates.c         |  192 ++++++++++++++++++++++++++--
 libedataserver/e-list.c                    |    5 +
 libedataserver/e-memory.c                  |    4 +-
 libedataserver/e-operation-pool.c          |    5 +-
 libedataserver/e-source-extension.c        |    2 +-
 libedataserver/e-source-mail-composition.c |   10 +-
 libedataserver/e-source-mail-signature.c   |    2 +-
 libedataserver/e-source-registry.c         |   20 ++--
 13 files changed, 267 insertions(+), 81 deletions(-)
---
diff --git a/libedataserver/Makefile.am b/libedataserver/Makefile.am
index 87fcfd9..6e89f88 100644
--- a/libedataserver/Makefile.am
+++ b/libedataserver/Makefile.am
@@ -204,7 +204,7 @@ introspection_sources = \
 	$(libedataserver_1_2_la_SOURCES))
 
 EDataServer-1.2.gir: libedataserver-1.2.la
-EDataServer_1_2_gir_INCLUDES = GObject-2.0 libxml2-2.0 Gio-2.0
+EDataServer_1_2_gir_INCLUDES = GObject-2.0 libxml2-2.0 Gio-2.0 Soup-2.4
 EDataServer_1_2_gir_CFLAGS = -I$(top_srcdir) -I$(top_builddir) -DLIBEDATASERVER_COMPILATION $(E_DATA_SERVER_CFLAGS) $(CAMEL_CFLAGS) $(SOUP_CFLAGS)
 EDataServer_1_2_gir_LIBS = libedataserver-1.2.la $(top_builddir)/camel/libcamel-1.2.la
 EDataServer_1_2_gir_FILES = $(introspection_sources)
diff --git a/libedataserver/e-categories.c b/libedataserver/e-categories.c
index 5d9b8c8..07e1c6c 100644
--- a/libedataserver/e-categories.c
+++ b/libedataserver/e-categories.c
@@ -490,9 +490,10 @@ initialize_categories (void)
  *
  * Returns a sorted list of all the category names currently configured.
  *
- * Returns: (transfer container): a sorted GList containing the names of the
- * categories.The list should be freed using g_list_free, but the names of
- * the categories should not be touched at all, they are internal strings.
+ * Returns: (transfer container) (element-type utf8): a sorted GList containing
+ * the names of the categories.The list should be freed using g_list_free(), but
+ * the names of the categories should not be touched at all, they are internal
+ * strings.
  */
 GList *
 e_categories_get_list (void)
diff --git a/libedataserver/e-client.c b/libedataserver/e-client.c
index 904a339..5f409ae 100644
--- a/libedataserver/e-client.c
+++ b/libedataserver/e-client.c
@@ -76,7 +76,7 @@ static guint signals[LAST_SIGNAL];
 
 G_DEFINE_ABSTRACT_TYPE (EClient, e_client, G_TYPE_OBJECT)
 
-/**
+/*
  * Well-known client backend properties, which are common for each #EClient:
  * @CLIENT_BACKEND_PROPERTY_OPENED: Is set to "TRUE" or "FALSE" depending
  *   whether the backend is fully opened.
@@ -92,7 +92,7 @@ G_DEFINE_ABSTRACT_TYPE (EClient, e_client, G_TYPE_OBJECT)
  *   of	capabilities supported by the backend. Preferred method of retreiving
  *   and working with capabilities is e_client_get_capabilities() and
  *   e_client_check_capability().
- **/
+ */
 
 GQuark
 e_client_error_quark (void)
@@ -1456,14 +1456,14 @@ e_client_refresh_sync (EClient *client,
 
 /**
  * e_client_util_slist_to_strv:
- * @strings: a #GSList of strings (const gchar *)
+ * @strings: (element-type utf8): a #GSList of strings (const gchar *)
  *
- * Convert list of strings into NULL-terminates array of strings.
+ * Convert a list of strings into a %NULL-terminated array of strings.
  *
- * Returns: (transfer full): Newly allocated NULL-terminated array of strings.
- * Returned pointer should be freed with g_strfreev().
+ * Returns: (transfer full): Newly allocated %NULL-terminated array of strings.
+ * The returned pointer should be freed with g_strfreev().
  *
- * Note: Pair function for this is e_client_util_strv_to_slist().
+ * Note: Paired function for this is e_client_util_strv_to_slist().
  *
  * Since: 3.2
  **/
@@ -1475,14 +1475,15 @@ e_client_util_slist_to_strv (const GSList *strings)
 
 /**
  * e_client_util_strv_to_slist:
- * @strv: a NULL-terminated array of strings (const gchar *)
+ * @strv: a %NULL-terminated array of strings (const gchar *)
  *
- * Convert NULL-terminated array of strings to a list of strings.
+ * Convert a %NULL-terminated array of strings to a list of strings.
  *
- * Returns: (transfer full): Newly allocated #GSList of newly allocated strings.
- * Returned pointer should be freed with e_client_util_free_string_slist().
+ * Returns: (transfer full) (element-type utf8): Newly allocated #GSList of
+ * newly allocated strings. The returned pointer should be freed with
+ * e_client_util_free_string_slist().
  *
- * Note: Pair function for this is e_client_util_slist_to_strv().
+ * Note: Paired function for this is e_client_util_slist_to_strv().
  *
  * Since: 3.2
  **/
@@ -1494,13 +1495,13 @@ e_client_util_strv_to_slist (const gchar * const *strv)
 
 /**
  * e_client_util_copy_string_slist:
- * @copy_to: Where to copy; can be NULL
- * @strings: GSList of strings to be copied
+ * @copy_to: (element-type utf8) (allow-none): Where to copy; may be %NULL
+ * @strings: (element-type utf8): #GSList of strings to be copied
  *
- * Copies GSList of strings at the end of @copy_to.
+ * Copies the #GSList of strings to the end of @copy_to.
  *
- * Returns: (transfer full): New head of @copy_to.
- * Returned pointer can be freed with e_client_util_free_string_slist().
+ * Returns: (transfer full) (element-type utf8): New head of @copy_to.
+ * The returned pointer can be freed with e_client_util_free_string_slist().
  *
  * Since: 3.2
  **/
@@ -1513,13 +1514,13 @@ e_client_util_copy_string_slist (GSList *copy_to,
 
 /**
  * e_client_util_copy_object_slist:
- * @copy_to: Where to copy; can be NULL
- * @objects: GSList of GObject-s to be copied
+ * @copy_to: (element-type GObject) (allow-none): Where to copy; may be %NULL
+ * @objects: (element-type GObject): #GSList of #GObject<!-- -->s to be copied
  *
- * Copies GSList of GObject-s at the end of @copy_to.
+ * Copies a #GSList of #GObject<!-- -->s to the end of @copy_to.
  *
- * Returns: (transfer full): New head of @copy_to.
- * Returned pointer can be freed with e_client_util_free_object_slist().
+ * Returns: (transfer full) (element-type GObject): New head of @copy_to.
+ * The returned pointer can be freed with e_client_util_free_object_slist().
  *
  * Since: 3.2
  **/
@@ -1532,7 +1533,7 @@ e_client_util_copy_object_slist (GSList *copy_to,
 
 /**
  * e_client_util_free_string_slist:
- * @strings: a #GSList of strings (gchar *)
+ * @strings: (element-type utf8): a #GSList of strings (gchar *)
  *
  * Frees memory previously allocated by e_client_util_strv_to_slist().
  *
@@ -1546,10 +1547,10 @@ e_client_util_free_string_slist (GSList *strings)
 
 /**
  * e_client_util_free_object_slist:
- * @objects: a #GSList of #GObject-s
+ * @objects: (element-type GObject): a #GSList of #GObject<!-- -->s
  *
- * Calls g_object_unref() on each member of @objects and then frees
- * also @objects itself.
+ * Calls g_object_unref() on each member of @objects and then frees @objects
+ * itself.
  *
  * Since: 3.2
  **/
@@ -1565,9 +1566,9 @@ e_client_util_free_object_slist (GSList *objects)
  *
  * Parses comma-separated list of values into #GSList.
  *
- * Returns: (transfer full): Newly allocated #GSList of newly allocated strings
- * corresponding to values parsed from @strings.
- * Free returned pointer with e_client_util_free_string_slist().
+ * Returns: (transfer full) (element-type utf8): Newly allocated #GSList of
+ * newly allocated strings corresponding to values parsed from @strings.
+ * Free the returned pointer with e_client_util_free_string_slist().
  *
  * Since: 3.2
  **/
diff --git a/libedataserver/e-credentials.c b/libedataserver/e-credentials.c
index f2cfb62..c357949 100644
--- a/libedataserver/e-credentials.c
+++ b/libedataserver/e-credentials.c
@@ -215,7 +215,7 @@ add_to_array_cb (gpointer key,
  * newly allocated string then this should be freed with g_strfreev() when no
  * longer needed.
  *
- * Returns: a %NULL-terminated array of key/value strings
+ * Returns: (transfer full): a %NULL-terminated array of key/value strings
  *
  * Since: 3.2
  **/
@@ -561,7 +561,8 @@ gather_key_names (gpointer key,
  * The key names are internal credentials values and should not be modified
  * or freed.  Free the list with g_slist_free() when no longer needed.
  *
- * Returns: a newly-allocated #GSList of key names
+ * Returns: (transfer container) (element-type utf8): a newly-allocated #GSList
+ * of key names
  *
  * Since: 3.2
  **/
diff --git a/libedataserver/e-data-server-util.c b/libedataserver/e-data-server-util.c
index 37f2bf7..e18831d 100644
--- a/libedataserver/e-data-server-util.c
+++ b/libedataserver/e-data-server-util.c
@@ -827,11 +827,11 @@ e_filename_mkdir_encoded (const gchar *basepath,
 
 /**
  * e_util_slist_to_strv:
- * @strings: a #GSList of strings (const gchar *)
+ * @strings: (element-type utf8): a #GSList of strings (const gchar *)
  *
  * Convert list of strings into NULL-terminates array of strings.
  *
- * Returns: (transfer full): Newly allocated NULL-terminated array of strings.
+ * Returns: (transfer full): Newly allocated %NULL-terminated array of strings.
  * Returned pointer should be freed with g_strfreev().
  *
  * Note: Pair function for this is e_util_strv_to_slist().
@@ -865,8 +865,9 @@ e_util_slist_to_strv (const GSList *strings)
  *
  * Convert NULL-terminated array of strings to a list of strings.
  *
- * Returns: (transfer full): Newly allocated #GSList of newly allocated strings.
- * Returned pointer should be freed with e_util_free_string_slist().
+ * Returns: (transfer full) (element-type utf8): Newly allocated #GSList of
+ * newly allocated strings. The returned pointer should be freed with
+ * e_util_free_string_slist().
  *
  * Note: Pair function for this is e_util_slist_to_strv().
  *
@@ -890,12 +891,12 @@ e_util_strv_to_slist (const gchar * const *strv)
 
 /**
  * e_util_copy_string_slist:
- * @copy_to: Where to copy; can be NULL
- * @strings: GSList of strings to be copied
+ * @copy_to: (element-type utf8) (allow-none): Where to copy; can be %NULL
+ * @strings: (element-type utf8): #GSList of strings to be copied
  *
- * Copies GSList of strings at the end of @copy_to.
+ * Copies #GSList of strings at the end of @copy_to.
  *
- * Returns: (transfer full): New head of @copy_to.
+ * Returns: (transfer full) (element-type utf8): New head of @copy_to.
  * Returned pointer can be freed with e_util_free_string_slist().
  *
  * Since: 3.4
@@ -920,12 +921,12 @@ e_util_copy_string_slist (GSList *copy_to,
 
 /**
  * e_util_copy_object_slist:
- * @copy_to: Where to copy; can be NULL
- * @objects: GSList of GObject-s to be copied
+ * @copy_to: (element-type GObject) (allow-none): Where to copy; can be %NULL
+ * @objects: (element-type GObject): #GSList of #GObject<!-- -->s to be copied
  *
- * Copies GSList of GObject-s at the end of @copy_to.
+ * Copies #GSList of #GObject<!-- -->s at the end of @copy_to.
  *
- * Returns: (transfer full): New head of @copy_to.
+ * Returns: (transfer full) (element-type GObject): New head of @copy_to.
  * Returned pointer can be freed with e_util_free_object_slist().
  *
  * Since: 3.4
@@ -950,7 +951,7 @@ e_util_copy_object_slist (GSList *copy_to,
 
 /**
  * e_util_free_string_slist:
- * @strings: a #GSList of strings (gchar *)
+ * @strings: (element-type utf8): a #GSList of strings (gchar *)
  *
  * Frees memory previously allocated by e_util_strv_to_slist().
  *
@@ -964,7 +965,7 @@ e_util_free_string_slist (GSList *strings)
 
 /**
  * e_util_free_object_slist:
- * @objects: a #GSList of #GObject-s
+ * @objects: (element-type GObject): a #GSList of #GObject<!-- -->s
  *
  * Calls g_object_unref() on each member of @objects and then frees
  * also @objects itself.
@@ -979,9 +980,9 @@ e_util_free_object_slist (GSList *objects)
 
 /**
  * e_util_free_nullable_object_slist:
- * @objects: a #GSList of nullable #GObject-s
+ * @objects: (element-type GObject): a #GSList of nullable #GObject<!-- -->s
  *
- * Calls g_object_unref() on each member of @objects if non-NULL and then frees
+ * Calls g_object_unref() on each member of @objects if non-%NULL and then frees
  * also @objects itself.
  *
  * Since: 3.6
@@ -1316,7 +1317,7 @@ e_async_closure_new (void)
  * This function can be called repeatedly on the same #EAsyncClosure to
  * easily string together multiple asynchronous operations.
  *
- * Returns: a #GAsyncResult
+ * Returns: (transfer none): a #GAsyncResult which is owned by the closure
  *
  * Since: 3.6
  **/
diff --git a/libedataserver/e-gdbus-templates.c b/libedataserver/e-gdbus-templates.c
index 4e937ae..60306be 100644
--- a/libedataserver/e-gdbus-templates.c
+++ b/libedataserver/e-gdbus-templates.c
@@ -712,10 +712,17 @@ e_gdbus_async_op_keeper_default_init (EGdbusAsyncOpKeeperInterface *iface)
 {
 }
 
-/* Created hash table of pending async operations. This can be freed
- * with g_hash_table_destroy () in dispose. Interface asks for this
- * ponter by call of e_gdbus_async_op_keeper_create_pending_ops ().
-*/
+/**
+ * e_gdbus_async_op_keeper_create_pending_ops:
+ * @object: a #EGdbusAsyncOpKeeper
+ *
+ * Create a hash table of pending async operations. This can be freed
+ * with g_hash_table_unref() in dispose. The interface asks for this
+ * pointer by calling e_gdbus_async_op_keeper_create_pending_ops().
+ *
+ * Returns: (transfer full) (element-type gpointer gpointer): hash table of
+ * pending async operations; free with g_hash_table_unref()
+ */
 GHashTable *
 e_gdbus_async_op_keeper_create_pending_ops (EGdbusAsyncOpKeeper *object)
 {
@@ -725,18 +732,24 @@ e_gdbus_async_op_keeper_create_pending_ops (EGdbusAsyncOpKeeper *object)
 	return g_hash_table_new (g_direct_hash, g_direct_equal);
 }
 
-/* Returns hash table of pending async operations previously created
- * by e_gdbus_async_op_keeper_create_pending_ops ().
-*/
+/**
+ * e_gdbus_async_op_keeper_get_pending_ops:
+ * @object: a #EGdbusAsyncOpKeeper
+ *
+ * Get the hash table of pending async operations previously created
+ * by e_gdbus_async_op_keeper_create_pending_ops().
+ *
+ * Returns: (transfer none): hash table of pending async operations
+ */
 GHashTable *
 e_gdbus_async_op_keeper_get_pending_ops (EGdbusAsyncOpKeeper *object)
 {
 	EGdbusAsyncOpKeeperInterface *iface;
 
-	g_return_val_if_fail (E_IS_GDBUS_ASYNC_OP_KEEPER (object), 0);
+	g_return_val_if_fail (E_IS_GDBUS_ASYNC_OP_KEEPER (object), NULL);
 
 	iface = E_GDBUS_ASYNC_OP_KEEPER_GET_IFACE (object);
-	g_return_val_if_fail (iface->get_pending_ops != NULL, 0);
+	g_return_val_if_fail (iface->get_pending_ops != NULL, NULL);
 
 	return iface->get_pending_ops (object);
 }
@@ -1508,6 +1521,17 @@ e_gdbus_proxy_call_sync_void__void (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_VOID, NULL, E_GDBUS_TYPE_VOID, NULL);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_void__boolean:
+ * @proxy:
+ * @out_boolean:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_void__boolean (GDBusProxy *proxy,
                                        gboolean *out_boolean,
@@ -1524,6 +1548,17 @@ e_gdbus_proxy_call_sync_void__boolean (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_VOID, NULL, E_GDBUS_TYPE_BOOLEAN, out_boolean);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_void__string:
+ * @proxy:
+ * @out_string:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_void__string (GDBusProxy *proxy,
                                       gchar **out_string,
@@ -1540,6 +1575,17 @@ e_gdbus_proxy_call_sync_void__string (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_VOID, NULL, E_GDBUS_TYPE_STRING, out_string);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_void__strv:
+ * @proxy:
+ * @out_strv:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_void__strv (GDBusProxy *proxy,
                                     gchar ***out_strv,
@@ -1556,6 +1602,17 @@ e_gdbus_proxy_call_sync_void__strv (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_VOID, NULL, E_GDBUS_TYPE_STRV, out_strv);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_void__uint:
+ * @proxy:
+ * @out_uint:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_void__uint (GDBusProxy *proxy,
                                     guint *out_uint,
@@ -1587,6 +1644,17 @@ e_gdbus_proxy_call_sync_boolean__void (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_BOOLEAN, &in_boolean, E_GDBUS_TYPE_VOID, NULL);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_string__void:
+ * @proxy:
+ * @in_string:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_string__void (GDBusProxy *proxy,
                                       const gchar *in_string,
@@ -1619,6 +1687,17 @@ e_gdbus_proxy_call_sync_strv__void (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_STRV, in_strv, E_GDBUS_TYPE_VOID, NULL);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_uint__void:
+ * @proxy:
+ * @in_uint:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_uint__void (GDBusProxy *proxy,
                                     guint in_uint,
@@ -1652,6 +1731,16 @@ e_gdbus_proxy_call_sync_string__string (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_STRING, in_string, E_GDBUS_TYPE_STRING, out_string);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_string__strv:
+ * @proxy:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_string__strv (GDBusProxy *proxy,
                                       const gchar *in_string,
@@ -1688,6 +1777,18 @@ e_gdbus_proxy_call_sync_strv__string (GDBusProxy *proxy,
 	return e_gdbus_proxy_call_sync (proxy, cancellable, error, start_func, finish_func, E_GDBUS_TYPE_STRV, in_strv, E_GDBUS_TYPE_STRING, out_string);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_strv__strv:
+ * @proxy:
+ * @in_strv:
+ * @out_strv:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_call_sync_strv__strv (GDBusProxy *proxy,
                                     const gchar * const *in_strv,
@@ -1969,6 +2070,16 @@ proxy_method_call_sync (const gchar *method_name,
 	return process_result (G_STRFUNC, out_type, out_value, g_dbus_proxy_call_sync (G_DBUS_PROXY (proxy), method_name, params, G_DBUS_CALL_FLAGS_NONE, e_data_server_util_get_dbus_call_timeout (), cancellable, error));
 }
 
+/**
+ * e_gdbus_proxy_call_sync_void__void:
+ * @proxy:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_method_call_sync_void__void (const gchar *method_name,
                                            GDBusProxy *proxy,
@@ -1978,6 +2089,17 @@ e_gdbus_proxy_method_call_sync_void__void (const gchar *method_name,
 	return proxy_method_call_sync (method_name, E_GDBUS_TYPE_VOID, NULL, E_GDBUS_TYPE_VOID, NULL, proxy, cancellable, error);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_boolean__void:
+ * @proxy:
+ * @in_boolean:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_method_call_sync_boolean__void (const gchar *method_name,
                                               GDBusProxy *proxy,
@@ -1998,6 +2120,17 @@ e_gdbus_proxy_method_call_sync_string__void (const gchar *method_name,
 	return proxy_method_call_sync (method_name, E_GDBUS_TYPE_STRING, in_string, E_GDBUS_TYPE_VOID, NULL, proxy, cancellable, error);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_strv__void:
+ * @proxy:
+ * @in_strv:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_method_call_sync_strv__void (const gchar *method_name,
                                            GDBusProxy *proxy,
@@ -2018,6 +2151,18 @@ e_gdbus_proxy_method_call_sync_uint__void (const gchar *method_name,
 	return proxy_method_call_sync (method_name, E_GDBUS_TYPE_UINT, &in_uint, E_GDBUS_TYPE_VOID, NULL, proxy, cancellable, error);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_string__string:
+ * @proxy:
+ * @in_string:
+ * @out_string:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_method_call_sync_string__string (const gchar *method_name,
                                                GDBusProxy *proxy,
@@ -2029,6 +2174,18 @@ e_gdbus_proxy_method_call_sync_string__string (const gchar *method_name,
 	return proxy_method_call_sync (method_name, E_GDBUS_TYPE_STRING, in_string, E_GDBUS_TYPE_STRING, out_string, proxy, cancellable, error);
 }
 
+/**
+ * e_gdbus_proxy_call_sync_strv__string:
+ * @proxy:
+ * @in_strv:
+ * @out_string:
+ * @cancellable: (allow-none):
+ * @error:
+ * @start_func: (scope call):
+ * @finish_func: (scope call):
+ *
+ * Returns:
+ */
 gboolean
 e_gdbus_proxy_method_call_sync_strv__string (const gchar *method_name,
                                              GDBusProxy *proxy,
@@ -2040,7 +2197,13 @@ e_gdbus_proxy_method_call_sync_strv__string (const gchar *method_name,
 	return proxy_method_call_sync (method_name, E_GDBUS_TYPE_STRV, in_strv, E_GDBUS_TYPE_STRING, out_string, proxy, cancellable, error);
 }
 
-/* free returned pointer with g_strfreev() */
+/**
+ * e_gdbus_templates_encode_error:
+ * @in_error: (allow-none):
+ *
+ * Returns: (transfer full): a %NULL-terminated array of strings; free with
+ * g_strfreev()
+ */
 gchar **
 e_gdbus_templates_encode_error (const GError *in_error)
 {
@@ -2088,7 +2251,14 @@ e_gdbus_templates_decode_error (const gchar * const *in_strv,
 	return TRUE;
 }
 
-/* free returned pointer with g_strfreev() */
+/**
+ * e_gdbus_templates_encode_two_strings:
+ * @in_str1: (allow-none):
+ * @in_str2: (allow-none):
+ *
+ * Returns: (transfer full): a %NULL-terminated array of strings; free with
+ * g_strfreev()
+ */
 gchar **
 e_gdbus_templates_encode_two_strings (const gchar *in_str1,
                                       const gchar *in_str2)
diff --git a/libedataserver/e-list.c b/libedataserver/e-list.c
index 6fcd2be..d8bee66 100644
--- a/libedataserver/e-list.c
+++ b/libedataserver/e-list.c
@@ -164,6 +164,11 @@ e_list_invalidate_iterators (EList *list,
 /* FIXME: This doesn't work properly if the iterator is the first
  * iterator in the list.  Well, the iterator doesn't continue on after
  * the next time next is called, at least. */
+/**
+ * e_list_remove_link: (skip)
+ * @list:
+ * @link:
+ */
 void
 e_list_remove_link (EList *list,
                     GList *link)
diff --git a/libedataserver/e-memory.c b/libedataserver/e-memory.c
index 0d60bfd..c956539 100644
--- a/libedataserver/e-memory.c
+++ b/libedataserver/e-memory.c
@@ -101,7 +101,7 @@ e_memchunk_new (gint atomcount,
  * Allocate a new atom size block of memory from an #EMemChunk.
  * Free the returned atom with e_memchunk_free().
  *
- * Returns: an allocated block of memory
+ * Returns: (transfer full): an allocated block of memory
  **/
 gpointer
 e_memchunk_alloc (EMemChunk *memchunk)
@@ -139,7 +139,7 @@ e_memchunk_alloc (EMemChunk *memchunk)
  * and fill the memory with zeros.  Free the returned atom with
  * e_memchunk_free().
  *
- * Returns: an allocated block of memory
+ * Returns: (transfer full): an allocated block of memory
  **/
 gpointer
 e_memchunk_alloc0 (EMemChunk *memchunk)
diff --git a/libedataserver/e-operation-pool.c b/libedataserver/e-operation-pool.c
index 4f990f4..10098ad 100644
--- a/libedataserver/e-operation-pool.c
+++ b/libedataserver/e-operation-pool.c
@@ -30,7 +30,10 @@ struct _EOperationPool {
 };
 
 /**
- * e_operation_pool_new:
+ * e_operation_pool_new: (skip)
+ * @max_threads:
+ * @thread_func:
+ * @user_data:
  *
  * FIXME: Document me.
  *
diff --git a/libedataserver/e-source-extension.c b/libedataserver/e-source-extension.c
index 4d7ea76..330fe7d 100644
--- a/libedataserver/e-source-extension.c
+++ b/libedataserver/e-source-extension.c
@@ -175,7 +175,7 @@ e_source_extension_init (ESourceExtension *extension)
  *
  * Returns the #ESource instance to which @extension belongs.
  *
- * Returns: the #ESource instance
+ * Returns: (transfer none): the #ESource instance
  **/
 ESource *
 e_source_extension_get_source (ESourceExtension *extension)
diff --git a/libedataserver/e-source-mail-composition.c b/libedataserver/e-source-mail-composition.c
index d26668c..b2b71db 100644
--- a/libedataserver/e-source-mail-composition.c
+++ b/libedataserver/e-source-mail-composition.c
@@ -272,7 +272,7 @@ e_source_mail_composition_init (ESourceMailComposition *extension)
  * the form "Full Name <email-address>".  The returned array is owned
  * by @extension and should not be modified or freed.
  *
- * Returns: a %NULL-terminated string array of Bcc recipients
+ * Returns: (transfer none): a %NULL-terminated string array of Bcc recipients
  *
  * Since: 3.6
  **/
@@ -294,7 +294,8 @@ e_source_mail_composition_get_bcc (ESourceMailComposition *extension)
  * The returned string array should be freed with g_strfreev() when no
  * longer needed.
  *
- * Returns: a newly-allocated copy of #ESourceMailComposition:bcc
+ * Returns: (transfer full): a newly-allocated copy of
+ * #ESourceMailComposition:bcc
  *
  * Since: 3.6
  **/
@@ -353,7 +354,7 @@ e_source_mail_composition_set_bcc (ESourceMailComposition *extension,
  * Name <email-address>".  The returned array is owned by @extension and
  * should not be modified or freed.
  *
- * Returns: a %NULL-terminated string array of Cc recipients
+ * Returns: (transfer none): a %NULL-terminated string array of Cc recipients
  *
  * Since: 3.6
  **/
@@ -375,7 +376,8 @@ e_source_mail_composition_get_cc (ESourceMailComposition *extension)
  * The returned string array should be freed with g_strfreev() when no
  * longer needed.
  *
- * Returns: a newly-allocated copy of #ESourceMailComposition:cc
+ * Returns: (transfer full): a newly-allocated copy of
+ * #ESourceMailComposition:cc
  *
  * Since: 3.6
  **/
diff --git a/libedataserver/e-source-mail-signature.c b/libedataserver/e-source-mail-signature.c
index 3860139..b63aefb 100644
--- a/libedataserver/e-source-mail-signature.c
+++ b/libedataserver/e-source-mail-signature.c
@@ -248,7 +248,7 @@ e_source_mail_signature_init (ESourceMailSignature *extension)
  *
  * e_source_mail_signature_load() uses this to load the signature content.
  *
- * Returns: a #GFile
+ * Returns: (transfer none): a #GFile
  *
  * Since: 3.6
  **/
diff --git a/libedataserver/e-source-registry.c b/libedataserver/e-source-registry.c
index a99f040..d07a7b8 100644
--- a/libedataserver/e-source-registry.c
+++ b/libedataserver/e-source-registry.c
@@ -1022,7 +1022,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 	 * "org.gnome.Evolution.DefaultSources" GSettings schema. */
 
 	/**
-	 * ESourceRegistry:default-address-book
+	 * ESourceRegistry:default-address-book:
 	 *
 	 * The default address book #ESource.
 	 **/
@@ -1038,7 +1038,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 			G_PARAM_STATIC_STRINGS));
 
 	/**
-	 * ESourceRegistry:default-calendar
+	 * ESourceRegistry:default-calendar:
 	 *
 	 * The default calendar #ESource.
 	 **/
@@ -1054,7 +1054,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 			G_PARAM_STATIC_STRINGS));
 
 	/**
-	 * ESourceRegistry:default-mail-account
+	 * ESourceRegistry:default-mail-account:
 	 *
 	 * The default mail account #ESource.
 	 **/
@@ -1070,7 +1070,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 			G_PARAM_STATIC_STRINGS));
 
 	/**
-	 * ESourceRegistry:default-mail-identity
+	 * ESourceRegistry:default-mail-identity:
 	 *
 	 * The default mail identity #ESource.
 	 **/
@@ -1086,7 +1086,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 			G_PARAM_STATIC_STRINGS));
 
 	/**
-	 * ESourceRegistry:default-memo-list
+	 * ESourceRegistry:default-memo-list:
 	 *
 	 * The default memo list #ESource.
 	 **/
@@ -1102,7 +1102,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 			G_PARAM_STATIC_STRINGS));
 
 	/**
-	 * ESourceRegistry:default-task-list
+	 * ESourceRegistry:default-task-list:
 	 *
 	 * The default task list #ESource.
 	 **/
@@ -1135,7 +1135,7 @@ e_source_registry_class_init (ESourceRegistryClass *class)
 		E_TYPE_SOURCE);
 
 	/**
-	 * ESourceRegistry::source-changed
+	 * ESourceRegistry::source-changed:
 	 * @registry: the #ESourceRegistry which emitted the signal
 	 * @source: the #ESource that changed
 	 *
@@ -1930,7 +1930,8 @@ source_registry_create_sources_thread (GSimpleAsyncResult *simple,
 /**
  * e_source_registry_create_sources_sync:
  * @registry: an #ESourceRegistry
- * @list_of_sources: a list of #ESource instances with no #GDBusObject
+ * @list_of_sources: (element-type ESource): a list of #ESource instances with
+ * no #GDBusObject
  * @cancellable: (allow-none): optional #GCancellable object, or %NULL
  * @error: return location for a #GError, or %NULL
  *
@@ -1991,7 +1992,8 @@ e_source_registry_create_sources_sync (ESourceRegistry *registry,
 /**
  * e_source_registry_create_sources:
  * @registry: an #ESourceRegistry
- * @list_of_sources: a list of #ESource instances with no #GDBusObject
+ * @list_of_sources: (element-type ESource): a list of #ESource instances with
+ * no #GDBusObject
  * @cancellable: (allow-none): optional #GCancellable object, or %NULL
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request
  *            is satisfied