From 874cfbd0c6dbb130489c27e9b50e51d8da6da398 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 18 Jun 2012 16:12:36 +0100 Subject: [PATCH] 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 #GObjects to be copied * - * Copies GSList of GObject-s at the end of @copy_to. + * Copies a #GSList of #GObjects 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 #GObjects * - * 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 #GObjects to be copied * - * Copies GSList of GObject-s at the end of @copy_to. + * Copies #GSList of #GObjects 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 #GObjects * * 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 #GObjects * - * 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 ". 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 ". 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 -- 2.7.4