GNOME.org
 

[evolution-data-server/wip/tintou/ebackend-annotations] [EBackend] improve the coverage of the annotations

commit dca0712240b8674acefea258abf77fb0463dd45e
Author: Corentin Noël <corentin elementary io>
Date:   Mon Dec 17 13:44:08 2018 +0100

    [EBackend] improve the coverage of the annotations

 src/libebackend/e-backend-factory.c        |  2 +-
 src/libebackend/e-backend.c                |  4 ++--
 src/libebackend/e-cache.c                  | 12 +++++-----
 src/libebackend/e-cache.h                  | 12 +++++-----
 src/libebackend/e-collection-backend.c     | 17 ++++++++------
 src/libebackend/e-data-factory.c           | 36 +++++++++++++++++++++++++-----
 src/libebackend/e-file-cache.c             |  4 ++--
 src/libebackend/e-oauth2-support.c         | 12 ++++++----
 src/libebackend/e-server-side-source.c     | 10 ++++-----
 src/libebackend/e-source-registry-server.c | 13 ++++++-----
 src/libebackend/e-subprocess-factory.c     |  9 ++++----
 src/libebackend/e-user-prompter-server.c   | 12 ++++++++++
 src/libebackend/e-user-prompter.c          |  6 +++--
 13 files changed, 99 insertions(+), 50 deletions(-)
---
diff --git a/src/libebackend/e-backend-factory.c b/src/libebackend/e-backend-factory.c
index 87936b3a5..4dc5f83b2 100644
--- a/src/libebackend/e-backend-factory.c
+++ b/src/libebackend/e-backend-factory.c
@@ -92,7 +92,7 @@ e_backend_factory_get_hash_key (EBackendFactory *factory)
  *
  * Returns a new #EBackend instance for @source.
  *
- * Returns: a new #EBackend instance for @source
+ * Returns: (transfer full): a new #EBackend instance for @source
  *
  * Since: 3.4
  **/
diff --git a/src/libebackend/e-backend.c b/src/libebackend/e-backend.c
index 1c09797bd..6d07dd52e 100644
--- a/src/libebackend/e-backend.c
+++ b/src/libebackend/e-backend.c
@@ -944,7 +944,7 @@ e_backend_ensure_online_state_updated (EBackend *backend,
  *
  * Returns the #ESource to which @backend is paired.
  *
- * Returns: the #ESource to which @backend is paired
+ * Returns: (transfer none): the #ESource to which @backend is paired
  *
  * Since: 3.4
  **/
@@ -970,7 +970,7 @@ e_backend_get_source (EBackend *backend)
  * The returned #GSocketConnectable is referenced for thread-safety and
  * must be unreferenced with g_object_unref() when finished with it.
  *
- * Returns: a #GSocketConnectable, or %NULL
+ * Returns: (transfer full): a #GSocketConnectable, or %NULL
  *
  * Since: 3.8
  **/
diff --git a/src/libebackend/e-cache.c b/src/libebackend/e-cache.c
index cfc13b0ec..552f3db8b 100644
--- a/src/libebackend/e-cache.c
+++ b/src/libebackend/e-cache.c
@@ -1945,7 +1945,7 @@ e_cache_foreach_cb (ECache *cache,
  * @cache: an #ECache
  * @deleted_flag: one of #ECacheDeletedFlag enum
  * @where_clause: (nullable): an optional SQLite WHERE clause part, or %NULL
- * @func: an #ECacheForeachFunc function to call for each object
+ * @func: (scope call): an #ECacheForeachFunc function to call for each object
  * @user_data: user data for the @func
  * @cancellable: optional #GCancellable object, or %NULL
  * @error: return location for a #GError, or %NULL
@@ -2129,7 +2129,7 @@ e_cache_foreach_update_cb (ECache *cache,
  * @cache: an #ECache
  * @deleted_flag: one of #ECacheDeletedFlag enum
  * @where_clause: (nullable): an optional SQLite WHERE clause part, or %NULL
- * @func: an #ECacheUpdateFunc function to call for each object
+ * @func: (scope call): an #ECacheUpdateFunc function to call for each object
  * @user_data: user data for the @func
  * @cancellable: optional #GCancellable object, or %NULL
  * @error: return location for a #GError, or %NULL
@@ -2285,9 +2285,9 @@ e_cache_foreach_update (ECache *cache,
  * e_cache_copy_missing_to_column_values:
  * @cache: an #ECache
  * @ncols: count of columns, items in column_names and column_values
- * @column_names: column names
- * @column_values: column values
- * @other_columns: (in out): an #ECacheColumnValues to fill
+ * @column_names: (array length=ncols) (element-type utf8): column names
+ * @column_values: (array length=ncols) (element-type utf8): column values
+ * @other_columns: (inout): an #ECacheColumnValues to fill
  *
  * Adds every column value which is not part of the @other_columns to it,
  * except of E_CACHE_COLUMN_UID, E_CACHE_COLUMN_REVISION, E_CACHE_COLUMN_OBJECT
@@ -2745,7 +2745,7 @@ e_cache_sqlite_exec (ECache *cache,
  * e_cache_sqlite_select:
  * @cache: an #ECache
  * @sql_stmt: an SQLite SELECT statement to execute
- * @func: an #ECacheSelectFunc function to call for each row
+ * @func: (scope call): an #ECacheSelectFunc function to call for each row
  * @user_data: user data for @func
  * @cancellable: optional #GCancellable object, or %NULL
  * @error: return location for a #GError, or %NULL
diff --git a/src/libebackend/e-cache.h b/src/libebackend/e-cache.h
index 3230cdec5..5dc81f282 100644
--- a/src/libebackend/e-cache.h
+++ b/src/libebackend/e-cache.h
@@ -242,8 +242,8 @@ typedef struct _ECachePrivate ECachePrivate;
  * @object: the object itself
  * @offline_state: objects offline state, one of #EOfflineState
  * @ncols: count of columns, items in column_names and column_values
- * @column_names: column names
- * @column_values: column values
+ * @column_names: (array length=ncols) (element-type utf8): column names
+ * @column_values: (array length=ncols) (element-type utf8): column values
  * @user_data: user data, as used in e_cache_foreach()
  *
  * A callback called for each object row when using e_cache_foreach() function.
@@ -270,8 +270,8 @@ typedef gboolean (* ECacheForeachFunc)      (ECache *cache,
  * @object: the object itself
  * @offline_state: objects offline state, one of #EOfflineState
  * @ncols: count of columns, items in column_names and column_values
- * @column_names: column names
- * @column_values: column values
+ * @column_names: (array length=ncols) (element-type utf8): column names
+ * @column_values: (array length=ncols) (element-type utf8): column values
  * @out_revision: (out): the new object revision to set; keep it untouched to not change
  * @out_object: (out): the new object to set; keep it untouched to not change
  * @out_offline_state: (out): the offline state to set; the default is the same as @offline_state
@@ -303,8 +303,8 @@ typedef gboolean (* ECacheUpdateFunc)       (ECache *cache,
  * ECacheSelectFunc:
  * @cache: an #ECache
  * @ncols: count of columns, items in column_names and column_values
- * @column_names: column names
- * @column_values: column values
+ * @column_names: (array length=ncols) (element-type utf8): column names
+ * @column_values: (array length=ncols) (element-type utf8): column values
  * @user_data: user data, as used in e_cache_sqlite_select()
  *
  * A callback called for each row of a SELECT statement executed
diff --git a/src/libebackend/e-collection-backend.c b/src/libebackend/e-collection-backend.c
index 5c1f20801..8c102c6ae 100644
--- a/src/libebackend/e-collection-backend.c
+++ b/src/libebackend/e-collection-backend.c
@@ -1284,7 +1284,7 @@ e_collection_backend_init (ECollectionBackend *backend)
  * The returned data source should be passed to
  * e_source_registry_server_add_source() to export it over D-Bus.
  *
- * Return: a newly-created data source
+ * Return: (transfer full): a newly-created data source
  *
  * Since: 3.6
  **/
@@ -1366,7 +1366,7 @@ e_collection_backend_is_new_source (ECollectionBackend *backend,
  * The returned #GProxyResolver is referenced for thread-safety and must
  * be unreferenced with g_object_unref() when finished with it.
  *
- * Returns: a #GProxyResolver, or %NULL
+ * Returns: (transfer full): a #GProxyResolver, or %NULL
  *
  * Since: 3.12
  **/
@@ -1397,7 +1397,8 @@ e_collection_backend_ref_proxy_resolver (ECollectionBackend *backend)
  * Unreference the #ESourceRegistryServer with g_object_unref() when
  * finished with it.
  *
- * Returns: the #ESourceRegistryServer for @backend
+ * Returns: (transfer full) (type ESourceRegistryServer): the
+ * #ESourceRegistryServer for @backend
  *
  * Since: 3.6
  **/
@@ -1509,7 +1510,8 @@ e_collection_backend_dup_resource_id (ECollectionBackend *backend,
  *   g_list_free_full (list, g_object_unref);
  * ]|
  *
- * Returns: a list of previously used sources
+ * Returns: (element-type ESource) (transfer full): a list of previously used
+ * sources
  *
  * Since: 3.6
  **/
@@ -1550,7 +1552,7 @@ e_collection_backend_claim_all_resources (ECollectionBackend *backend)
  *   g_list_free_full (list, g_object_unref);
  * ]|
  *
- * Returns: a list of calendar sources
+ * Returns: (element-type ESource) (transfer full): a list of calendar sources
  *
  * Since: 3.6
  **/
@@ -1593,7 +1595,8 @@ e_collection_backend_list_calendar_sources (ECollectionBackend *backend)
  *   g_list_free_full (list, g_object_unref);
  * ]|
  *
- * Returns: a list of address book sources
+ * Returns: (element-type ESource) (transfer full): a list of address book
+ * sources
  *
  * Since: 3.6
  **/
@@ -1636,7 +1639,7 @@ e_collection_backend_list_contacts_sources (ECollectionBackend *backend)
  *   g_list_free_full (list, g_object_unref);
  * ]|
  *
- * Returns: a list of mail sources
+ * Returns: (element-type ESource) (transfer full): a list of mail sources
  *
  * Since: 3.6
  **/
diff --git a/src/libebackend/e-data-factory.c b/src/libebackend/e-data-factory.c
index 15a5249d7..865773430 100644
--- a/src/libebackend/e-data-factory.c
+++ b/src/libebackend/e-data-factory.c
@@ -1173,7 +1173,7 @@ e_data_factory_init (EDataFactory *data_factory)
  * Unreference the #EBackendFactory with g_object_unref() when finished
  * with it.
  *
- * Returns: the #EBackendFactory for @hash_key, or %NULL
+ * Returns: (transfer full): the #EBackendFactory for @hash_key, or %NULL
  *
  * Since: 3.6
  **/
@@ -1214,7 +1214,7 @@ e_data_factory_ref_backend_factory (EDataFactory *data_factory,
  *
  * Returns the #ESourceRegistry owned by @data_factory.
  *
- * Returns: the #ESourceRegistry
+ * Returns: (transfer none): the #ESourceRegistry
  *
  * Since: 3.16
  **/
@@ -1632,8 +1632,17 @@ e_data_factory_use_backend_per_process (EDataFactory *data_factory)
        return backend_per_process;
 }
 
-/* Used only when backend-per-process is off. Free the returned pointer
-   with g_object_unref(), if not NULL and no longer needed */
+/**
+ * e_data_factory_create_backend:
+ * @data_factory: an #EDataFactory
+ *
+ * Used only when backend-per-process is off.
+ *
+ * Free the returned pointer with g_object_unref(), if not NULL and no longer
+ * needed.
+ *
+ * Returns: (transfer full): a newly-created #EBackend
+ **/
 EBackend *
 e_data_factory_create_backend (EDataFactory *data_factory,
                               EBackendFactory *backend_factory,
@@ -1686,7 +1695,24 @@ e_data_factory_backend_closed (EDataFactory *data_factory,
        g_object_unref (backend);
 }
 
-/* free with g_list_free_full (list, g_object_unref);, element is 'EBackend *' */
+/**
+ * e_data_factory_list_opened_backends:
+ * @data_factory: an #EDataFactory
+ *
+ * Lists the currently opened backends.
+ *
+ * The sources returned in the list are referenced for thread-safety.
+ * They must each be unreferenced with g_object_unref() when finished
+ * with them.  Free the returned #GSList itself with g_slist_free().
+ *
+ * An easy way to free the list properly in one step is as follows:
+ *
+ * |[
+ *   g_slist_free_full (list, g_object_unref);
+ * ]|
+ *
+ * Returns: (element-type EBackend) (transfer full): a #GSList of #EBackend
+ **/
 GSList *
 e_data_factory_list_opened_backends (EDataFactory *data_factory)
 {
diff --git a/src/libebackend/e-file-cache.c b/src/libebackend/e-file-cache.c
index 529764ff1..8f92df7e8 100644
--- a/src/libebackend/e-file-cache.c
+++ b/src/libebackend/e-file-cache.c
@@ -377,7 +377,7 @@ add_object_to_slist (const gchar *key,
  * Returns a list of objects in @cache.  The objects are owned by @cache and
  * must not be modified or freed.  Free the returned list with g_slist_free().
  *
- * Returns: a list of objects
+ * Returns: (element-type utf8) (transfer container): a list of objects
  */
 GSList *
 e_file_cache_get_objects (EFileCache *cache)
@@ -400,7 +400,7 @@ e_file_cache_get_objects (EFileCache *cache)
  * Returns a list of keys in @cache.  The keys are owned by @cache and must
  * not be modified or freed.  Free the returned list with g_slist_free().
  *
- * Returns: a list of keys
+ * Returns: (element-type utf8) (transfer container): a list of keys
  */
 GSList *
 e_file_cache_get_keys (EFileCache *cache)
diff --git a/src/libebackend/e-oauth2-support.c b/src/libebackend/e-oauth2-support.c
index 147f989ce..0cf383b42 100644
--- a/src/libebackend/e-oauth2-support.c
+++ b/src/libebackend/e-oauth2-support.c
@@ -155,8 +155,10 @@ e_oauth2_support_default_init (EOAuth2SupportInterface *iface)
  * @support: an #EOAuth2Support
  * @source: an #ESource
  * @cancellable: optional #GCancellable object, or %NULL
- * @out_access_token: return location for the access token, or %NULL
- * @out_expires_in: return location for the token expiry, or %NULL
+ * @out_access_token: (out) (optional): return location for the access token,
+ * or %NULL
+ * @out_expires_in: (out) (optional): return location for the token expiry,
+ * or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * Obtains the OAuth 2.0 access token for @source along with its expiry
@@ -230,8 +232,10 @@ e_oauth2_support_get_access_token (EOAuth2Support *support,
  * e_oauth2_support_get_access_token_finish:
  * @support: an #EOAuth2Support
  * @result: a #GAsyncResult
- * @out_access_token: return location for the access token, or %NULL
- * @out_expires_in: return location for the token expiry, or %NULL
+ * @out_access_token: (out) (optional): return location for the access token,
+ * or %NULL
+ * @out_expires_in: (out) (optional): return location for the token expiry,
+ * or %NULL
  * @error: return location for a #GError, or %NULL
  *
  * Finishes the operation started with e_oauth2_support_get_access_token().
diff --git a/src/libebackend/e-server-side-source.c b/src/libebackend/e-server-side-source.c
index 376202e84..84f007d9b 100644
--- a/src/libebackend/e-server-side-source.c
+++ b/src/libebackend/e-server-side-source.c
@@ -1798,7 +1798,7 @@ e_server_side_source_get_user_dir (void)
  *
  * Note the data source file itself is not created here, only its name.
  *
- * Returns: the #GFile for a new data source
+ * Returns: (transfer full): the #GFile for a new data source
  *
  * Since: 3.6
  **/
@@ -2062,7 +2062,7 @@ e_server_side_source_load (EServerSideSource *source,
  * Returns the #GFile from which data source content is loaded and to
  * which changes are saved.  Note the @source may not have a #GFile.
  *
- * Returns: the #GFile for @source, or %NULL
+ * Returns: (transfer none) (nullable): the #GFile for @source, or %NULL
  *
  * Since: 3.6
  **/
@@ -2086,7 +2086,7 @@ e_server_side_source_get_file (EServerSideSource *source)
  * Note that accessing other data sources this way is not thread-safe,
  * and this therefore function may be replaced at some later date.
  *
- * Returns: a #GNode, or %NULL
+ * Returns: (transfer none) (nullable): a #GNode, or %NULL
  *
  * Since: 3.6
  **/
@@ -2104,7 +2104,7 @@ e_server_side_source_get_node (EServerSideSource *source)
  *
  * Returns the #ESourceRegistryServer to which @source belongs.
  *
- * Returns: the #ESourceRegistryServer for @source
+ * Returns: (transfer none): the #ESourceRegistryServer for @source
  *
  * Since: 3.6
  **/
@@ -2432,7 +2432,7 @@ e_server_side_source_set_remote_deletable (EServerSideSource *source,
  * The returned #EOAuth2Support object is referenced for thread-safety.
  * Unreference the object with g_object_unref() when finished with it.
  *
- * Returns: an #EOAuth2Support object, or %NULL
+ * Returns: (transfer full): an #EOAuth2Support object, or %NULL
  *
  * Since: 3.8
  **/
diff --git a/src/libebackend/e-source-registry-server.c b/src/libebackend/e-source-registry-server.c
index 6eafd1f80..17ceaf2f0 100644
--- a/src/libebackend/e-source-registry-server.c
+++ b/src/libebackend/e-source-registry-server.c
@@ -1724,7 +1724,7 @@ source_registry_server_tweak_key_file (ESourceRegistryServer *server,
  * The returned #ESource is referenced for thread-safety.  Unreference
  * the #ESource with g_object_unref() when finished with it.
  *
- * Returns: the newly-added #ESource, or %NULL on error
+ * Returns: (transfer full): the newly-added #ESource, or %NULL on error
  *
  * Since: 3.6
  **/
@@ -1849,7 +1849,7 @@ e_source_registry_server_load_error (ESourceRegistryServer *server,
  * The returned #ESource is referenced for thread-safety and must be
  * unreferenced with g_object_unref() when finished with it.
  *
- * Returns: an #ESource, or %NULL if no match was found
+ * Returns: (transfer full): an #ESource, or %NULL if no match was found
  *
  * Since: 3.6
  **/
@@ -1882,7 +1882,7 @@ e_source_registry_server_ref_source (ESourceRegistryServer *server,
  *   g_list_free_full (list, g_object_unref);
  * ]|
  *
- * Returns: a sorted list of sources
+ * Returns: (element-type ESource) (transfer full): a sorted list of sources
  *
  * Since: 3.6
  **/
@@ -1944,7 +1944,7 @@ e_source_registry_server_list_sources (ESourceRegistryServer *server,
  * instead of the #ESourceExtension itself because extension instances are
  * not to be referenced directly (see e_source_get_extension()).
  *
- * Returns: an #ESource, or %NULL if no match was found
+ * Returns: (transfer full): an #ESource, or %NULL if no match was found
  *
  * Since: 3.8
  **/
@@ -1996,7 +1996,7 @@ e_source_registry_server_find_extension (ESourceRegistryServer *server,
  * Unreference the #ECollectionBackend with g_object_unref() when finished
  * with it.
  *
- * Returns: the #ECollectionBackend for @source, or %NULL
+ * Returns: (transfer full): the #ECollectionBackend for @source, or %NULL
  *
  * Since: 3.6
  **/
@@ -2038,7 +2038,8 @@ e_source_registry_server_ref_backend (ESourceRegistryServer *server,
  * Unreference the #ECollectionBackendFactory with g_object_unref() when
  * finished with it.
  *
- * Returns: the #ECollectionBackendFactory for @source, or %NULL
+ * Returns: (transfer full): the #ECollectionBackendFactory for @source,
+ * or %NULL
  *
  * Since: 3.6
  **/
diff --git a/src/libebackend/e-subprocess-factory.c b/src/libebackend/e-subprocess-factory.c
index 9654fc835..7241bd02a 100644
--- a/src/libebackend/e-subprocess-factory.c
+++ b/src/libebackend/e-subprocess-factory.c
@@ -234,7 +234,7 @@ e_subprocess_factory_init (ESubprocessFactory *subprocess_factory)
  * If no suitable #EBackendFactory exists, or if the #EBackend fails to
  * initialize, the function sets @error and returns %NULL.
  *
- * Returns: an #EBackend for @source, or %NULL
+ * Returns: (transfer full): an #EBackend for @source, or %NULL
  *
  * Since: 3.16
  **/
@@ -324,7 +324,7 @@ exit:
  *
  * Returns the #ESourceRegistry owned by @subprocess_factory.
  *
- * Returns: the #ESourceRegistry
+ * Returns: (transfer none): the #ESourceRegistry
  *
  * Since: 3.16
  **/
@@ -422,8 +422,9 @@ e_subprocess_factory_open_backend (ESubprocessFactory *subprocess_factory,
  *
  * Returns a list of used backends.
  *
- * Returns: A #GList that contains a list of used backends. The list should be freed
- * by the caller using: g_list_free_full (backends, g_object_unref).
+ * Returns: (transfer full) (element-type EBackend): A #GList that contains a
+ * list of used backends. The list should be freed by the caller using:
+ * g_list_free_full (backends, g_object_unref).
  *
  * Since: 3.16
  **/
diff --git a/src/libebackend/e-user-prompter-server.c b/src/libebackend/e-user-prompter-server.c
index 1a72a117c..9ac4fe730 100644
--- a/src/libebackend/e-user-prompter-server.c
+++ b/src/libebackend/e-user-prompter-server.c
@@ -423,6 +423,18 @@ e_user_prompter_server_class_init (EUserPrompterServerClass *class)
        dbus_server_class->bus_acquired = user_prompter_server_bus_acquired;
        dbus_server_class->quit_server = user_prompter_server_quit_server;
 
+       /**
+        * EUserPrompterServer::prompt:
+        * @server: an #EUserPrompterServer which emited the signal
+        * @prompt_id: the id of the prompt
+        * @type: (nullable): type of the prompt; can be %NULL
+        * @title: (nullable): window title of the prompt; can be %NULL
+        * @primary_text: (nullable): primary text of the prompt; can be %NULL
+        * @secondary_text: (nullable): secondary text of the prompt; can be %NULL
+        * @use_markup: whether both texts are with markup
+        * @button_captions: (type GStrv) (nullable): captions of buttons to
+        * use in the message; can be %NULL
+        **/
        signals[PROMPT] = g_signal_new (
                "prompt",
                G_OBJECT_CLASS_TYPE (object_class),
diff --git a/src/libebackend/e-user-prompter.c b/src/libebackend/e-user-prompter.c
index 71dd81ee8..f8c76dced 100644
--- a/src/libebackend/e-user-prompter.c
+++ b/src/libebackend/e-user-prompter.c
@@ -326,7 +326,8 @@ user_prompter_prompt_thread (GSimpleAsyncResult *simple,
  * @primary_text: (allow-none): primary text of the prompt; can be %NULL
  * @secondary_text: (allow-none): secondary text of the prompt; can be %NULL
  * @use_markup: whether both texts are with markup
- * @button_captions: (allow-none): captions of buttons to use in the message; can be %NULL
+ * @button_captions: (allow-none) (element-type utf8): captions of buttons to
+ * use in the message; can be %NULL
  * @cancellable: (allow-none): optional #GCancellable object, or %NULL
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request
  *            is satisfied
@@ -433,7 +434,8 @@ e_user_prompter_prompt_finish (EUserPrompter *prompter,
  * @primary_text: (allow-none): primary text of the prompt; can be %NULL
  * @secondary_text: (allow-none): secondary text of the prompt; can be %NULL
  * @use_markup: whether both texts are with markup
- * @button_captions: (allow-none): captions of buttons to use in the message; can be %NULL
+ * @button_captions: (allow-none) (element-type utf8): captions of buttons to
+ * use in the message; can be %NULL
  * @cancellable: (allow-none): optional #GCancellable object, or %NULL
  * @error: return location for a #GError, or %NULL
  *
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]