GNOME.org
 

[evolution-data-server/wip/tintou/edata-book-annotations] [EData-Book] fix several annotations

commit a293ad75c5d23b68e9128d543ab3021150decb9b
Author: Corentin Noël <corentin elementary io>
Date:   Thu Feb 7 23:06:28 2019 +0100

    [EData-Book] fix several annotations

 .../libedata-book/e-book-backend-cache.c           |  6 ++--
 .../libedata-book/e-book-backend-db-cache.c        |  6 ++--
 .../libedata-book/e-book-backend-sqlitedb.c        | 36 +++++++++++-----------
 .../libedata-book/e-book-backend-summary.c         |  2 +-
 src/addressbook/libedata-book/e-book-backend.c     | 18 +++++------
 src/addressbook/libedata-book/e-book-cache.c       |  2 +-
 .../libedata-book/e-book-meta-backend.c            |  2 +-
 src/addressbook/libedata-book/e-book-sqlite.c      |  6 ++--
 src/addressbook/libedata-book/e-data-book-view.c   |  8 ++---
 src/addressbook/libedata-book/e-data-book.c        | 12 ++++----
 10 files changed, 49 insertions(+), 49 deletions(-)
---
diff --git a/src/addressbook/libedata-book/e-book-backend-cache.c 
b/src/addressbook/libedata-book/e-book-backend-cache.c
index 08cd62313..9da28c4e3 100644
--- a/src/addressbook/libedata-book/e-book-backend-cache.c
+++ b/src/addressbook/libedata-book/e-book-backend-cache.c
@@ -84,7 +84,7 @@ e_book_backend_cache_new (const gchar *filename)
  * newly created, and must be unreffed by the caller when no longer
  * needed.
  *
- * Returns: A cached #EContact, or %NULL if @uid is not cached.
+ * Returns: (transfer full): A cached #EContact, or %NULL if @uid is not cached.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
@@ -202,7 +202,7 @@ e_book_backend_cache_check_contact (EBookBackendCache *cache,
  * When done with the list, the caller must unref the contacts and
  * free the list.
  *
- * Returns: A #GList of pointers to #EContact.
+ * Returns: (transfer full) (element-type EContact): A #GList of pointers to #EContact.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
@@ -255,7 +255,7 @@ e_book_backend_cache_get_contacts (EBookBackendCache *cache,
  * in @cache matching @query. When done with the array, the caller must
  * free the ID strings and the array.
  *
- * Returns: A #GPtrArray of pointers to contact ID strings.
+ * Returns: (transfer full) (element-type utf8): A #GPtrArray of pointers to contact ID strings.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
diff --git a/src/addressbook/libedata-book/e-book-backend-db-cache.c 
b/src/addressbook/libedata-book/e-book-backend-db-cache.c
index 943d9bc45..2d2328612 100644
--- a/src/addressbook/libedata-book/e-book-backend-db-cache.c
+++ b/src/addressbook/libedata-book/e-book-backend-db-cache.c
@@ -138,7 +138,7 @@ e_book_backend_db_cache_get_filename (DB *db)
  * newly created, and must be unreffed by the caller when no longer
  * needed.
  *
- * Returns: A cached #EContact, or %NULL if @uid is not cached.
+ * Returns: (transfer full) (nullable): A cached #EContact, or %NULL if @uid is not cached.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
@@ -289,7 +289,7 @@ e_book_backend_db_cache_check_contact (DB *db,
  * When done with the list, the caller must unref the contacts and
  * free the list.
  *
- * Returns: A #GList of pointers to #EContact.
+ * Returns: (element-type EContact) (transfer full): A #GList of pointers to #EContact.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
@@ -353,7 +353,7 @@ e_book_backend_db_cache_get_contacts (DB *db,
  * in @cache matching @query. When done with the array, the caller must
  * free the ID strings and the array.
  *
- * Returns: A #GPtrArray of pointers to contact ID strings.
+ * Returns: (element-type utf8) (transfer full): A #GPtrArray of pointers to contact ID strings.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
diff --git a/src/addressbook/libedata-book/e-book-backend-sqlitedb.c 
b/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
index 39ab294a2..a064f3ec9 100644
--- a/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
+++ b/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
@@ -2426,7 +2426,7 @@ e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
  * e_book_backend_sqlitedb_new_contacts
  * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: folder id
- * @contacts: list of #EContact
+ * @contacts: (element-type EContact): list of #EContact
  * @replace_existing: Whether this contact should replace another contact with the same UID.
  * @error: (allow-none): A location to store any error that may have occurred.
  *
@@ -2522,7 +2522,7 @@ e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
  * e_book_backend_sqlitedb_add_contacts:
  * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: folder id
- * @contacts: list of #EContact
+ * @contacts: (element-type EContact): list of #EContact
  * @partial_content: contact does not contain full information. Used when
  * the backend cache's partial information for auto-completion.
  * @error: (allow-none): A location to store any error that may have occurred.
@@ -2625,7 +2625,7 @@ generate_delete_stmt (const gchar *table,
  * e_book_backend_sqlitedb_remove_contacts:
  * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: folder id
- * @uids: a #GSList of uids indicating which contacts to remove
+ * @uids: (element-type utf8): a #GSList of uids indicating which contacts to remove
  * @error: (allow-none): A location to store any error that may have occurred.
  *
  * Removes the contacts indicated by @uids from the folder @folderid in @ebsdb.
@@ -2771,7 +2771,8 @@ get_vcard_cb (gpointer ref,
  * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: folder id
  * @uid: The uid of the contact to fetch
- * @fields_of_interest: (allow-none): A #GHashTable indicating which fields should be included in returned 
contacts
+ * @fields_of_interest: (allow-none) (element-type utf8 gint): A #GHashTable indicating which fields
+ *   should be included in returned contacts
  * @with_all_required_fields: (out) (allow-none): Whether all of the fields of interest were available
  * @error: (allow-none): A location to store any error that may have occurred.
  *
@@ -2786,8 +2787,8 @@ get_vcard_cb (gpointer ref,
  * is not stored in @ebsdb, you must pass the @error parameter and check whether
  * it was set by this function.</para></note>
  *
- * Returns: On success the #EContact corresponding to @uid is returned, otherwise %NULL is
- * returned if there was an error or if no contact was found for @uid.
+ * Returns: (transfer full): On success the #EContact corresponding to @uid is returned,
+ *   otherwise %NULL is returned if there was an error or if no contact was found for @uid.
  *
  * Since: 3.2
  *
@@ -2844,7 +2845,7 @@ uid_rev_fields (GHashTable *fields_of_interest)
 
 /**
  * e_book_backend_sqlitedb_is_summary_fields:
- * @fields_of_interest: A hash table containing the fields of interest
+ * @fields_of_interest: (element-type utf8 gint): A hash table containing the fields of interest
  * 
  * This only checks if all the fields are part of the default summary fields,
  * not part of the configured summary fields.
@@ -2891,7 +2892,7 @@ e_book_backend_sqlitedb_is_summary_fields (GHashTable *fields_of_interest)
 /**
  * e_book_backend_sqlitedb_check_summary_fields:
  * @ebsdb: An #EBookBackendSqliteDB
- * @fields_of_interest: A #GHashTable containing the fields of interest
+ * @fields_of_interest: (element-type utf8 gint): A #GHashTable containing the fields of interest
  * 
  * Checks if all the specified fields are part of the configured summary
  * fields for @ebsdb
@@ -2996,7 +2997,8 @@ store_data_to_vcard (gpointer ref,
  * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: The folder id
  * @uid: The uid to fetch a vcard for
- * @fields_of_interest: The required fields for this vcard, or %NULL to require all fields.
+ * @fields_of_interest: (element-type utf8 gint) (nullable): The required fields for this vcard,
+ *   or %NULL to require all fields.
  * @with_all_required_fields: (allow-none) (out): Whether all the required fields are present in the 
returned vcard.
  * @error: (allow-none): A location to store any error that may have occurred.
  *
@@ -3347,7 +3349,7 @@ e_book_backend_sqlitedb_check_summary_query_locked (EBookBackendSqliteDB *ebsdb,
  * e_book_backend_sqlitedb_check_summary_query:
  * @ebsdb: An #EBookBackendSqliteDB
  * @query: the query to check
- * @with_list_attrs: Return location to store whether the query touches upon list attributes
+ * @with_list_attrs: (out): Return location to store whether the query touches upon list attributes
  *
  * Checks whether @query contains only checks for the summary fields
  * configured in @ebsdb
@@ -3384,9 +3386,7 @@ e_book_backend_sqlitedb_check_summary_query (EBookBackendSqliteDB *ebsdb,
  *
  * Since: 3.2
  *
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_check_summary_query() instead
- *
- * Deprecated: 3.12: Use #EBookSqlite instead
+ * Deprecated: 3.8: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_is_summary_query (const gchar *query)
@@ -4238,8 +4238,8 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb,
  * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: folder id of the address-book
  * @sexp: (allow-none): search expression; use %NULL or an empty string to get all stored contacts.
- * @fields_of_interest: (allow-none): A #GHashTable indicating which fields should be 
- * included in the returned contacts
+ * @fields_of_interest: (allow-none) (element-type utf8 gint): A #GHashTable indicating which fields
+ * should be  included in the returned contacts
  * @searched: (allow-none) (out): Whether @ebsdb was capable of searching
  * for the provided query @sexp.
  * @with_all_required_fields: (allow-none) (out): Whether all the required
@@ -4265,7 +4265,7 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb,
  * The returned list should be freed with g_slist_free()
  * and all elements freed with e_book_backend_sqlitedb_search_data_free().
  *
- * Returns: (transfer full): A #GSList of #EbSdbSearchData structures.
+ * Returns: (transfer full) (element-type EbSdbSearchData): A #GSList of #EbSdbSearchData structures.
  *
  * Since: 3.2
  *
@@ -4360,7 +4360,7 @@ e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb,
  * The returned list should be freed with g_slist_free()
  * and all elements freed with g_free().
  *
- * Returns: (transfer full): A #GSList of allocated contact UID strings.
+ * Returns: (transfer full) (element-type utf8): A #GSList of allocated contact UID strings.
  *
  * Since: 3.2
  *
@@ -5105,7 +5105,7 @@ e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
  *
  * Obsolete, do not use, this always ends with an error.
  *
- * Returns: %NULL
+ * Returns: (element-type utf8) (transfer full): %NULL
  *
  * Since: 3.2
  *
diff --git a/src/addressbook/libedata-book/e-book-backend-summary.c 
b/src/addressbook/libedata-book/e-book-backend-summary.c
index 79e46c3f6..5b5fe7a01 100644
--- a/src/addressbook/libedata-book/e-book-backend-summary.c
+++ b/src/addressbook/libedata-book/e-book-backend-summary.c
@@ -1238,7 +1238,7 @@ static const struct {
  *
  * Searches @summary for contacts matching @query.
  *
- * Returns: A #GPtrArray of pointers to contact ID strings.
+ * Returns: (element-type utf8) (transfer container): A #GPtrArray of pointers to contact ID strings.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
diff --git a/src/addressbook/libedata-book/e-book-backend.c b/src/addressbook/libedata-book/e-book-backend.c
index 2da60b13d..18577618b 100644
--- a/src/addressbook/libedata-book/e-book-backend.c
+++ b/src/addressbook/libedata-book/e-book-backend.c
@@ -954,7 +954,7 @@ e_book_backend_set_cache_dir (EBookBackend *backend,
  * The returned #EDataBook is referenced for thread-safety and must be
  * unreferenced with g_object_unref() when finished with it.
  *
- * Returns: an #EDataBook, or %NULL
+ * Returns: (transfer full) (nullable): an #EDataBook, or %NULL
  *
  * Since: 3.10
  **/
@@ -1007,7 +1007,7 @@ e_book_backend_set_data_book (EBookBackend *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) (nullable): a #GProxyResolver, or %NULL
  *
  * Since: 3.12
  **/
@@ -1034,7 +1034,7 @@ e_book_backend_ref_proxy_resolver (EBookBackend *backend)
  *
  * Returns the data source registry to which #EBackend:source belongs.
  *
- * Returns: an #ESourceRegistry
+ * Returns: (transfer none): an #ESourceRegistry
  *
  * Since: 3.6
  **/
@@ -1665,7 +1665,7 @@ book_backend_create_contacts_thread_old_style (GSimpleAsyncResult *simple,
 }
 
 /**
- * e_book_backend_create_contacts
+ * e_book_backend_create_contacts:
  * @backend: an #EBookBackend
  * @vcards: a %NULL-terminated array of vCard strings
  * @cancellable: optional #GCancellable object, or %NULL
@@ -2194,7 +2194,7 @@ book_backend_remove_contacts_thread_old_style (GSimpleAsyncResult *simple,
 /**
  * e_book_backend_remove_contacts:
  * @backend: an #EBookBackend
- * @uids: a %NULL-terminated array of contact ID strings
+ * @uids: (array zero-terminated=1): a %NULL-terminated array of contact ID strings
  * @cancellable: optional #GCancellable object, or %NULL
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: data to pass to the callback function
@@ -2321,7 +2321,7 @@ e_book_backend_remove_contacts_finish (EBookBackend *backend,
  *
  * If an error occurs, the function will set @error and return %NULL.
  *
- * Returns: an #EContact, or %NULL
+ * Returns: (transfer full): an #EContact, or %NULL
  *
  * Since: 3.10
  **/
@@ -2527,7 +2527,7 @@ e_book_backend_get_contact (EBookBackend *backend,
  *
  * If an error occurred, the function will set @error and return %NULL.
  *
- * Returns: an #EContact, or %NULL
+ * Returns: (transfer full): an #EContact, or %NULL
  *
  * Since: 3.10
  **/
@@ -3210,7 +3210,7 @@ e_book_backend_remove_view (EBookBackend *backend,
  *   g_list_free_full (list, g_object_unref);
  * ]|
  *
- * Returns: a list of book views
+ * Returns: (transfer full) (element-type EDataBookView): a list of book views
  *
  * Since: 3.8
  **/
@@ -3306,7 +3306,7 @@ e_book_backend_is_readonly (EBookBackend *backend)
  * Tries to create an #EDataBookDirect for @backend if
  * backend supports direct read access.
  *
- * Returns: (transfer full): A new #EDataBookDirect object, or %NULL if
+ * Returns: (transfer full) (nullable): A new #EDataBookDirect object, or %NULL if
  *          @backend does not support direct access
  *
  * Since: 3.8
diff --git a/src/addressbook/libedata-book/e-book-cache.c b/src/addressbook/libedata-book/e-book-cache.c
index 3f6e0ece5..eaf620d1d 100644
--- a/src/addressbook/libedata-book/e-book-cache.c
+++ b/src/addressbook/libedata-book/e-book-cache.c
@@ -5332,7 +5332,7 @@ e_book_cache_search_uids (EBookCache *book_cache,
  * e_book_cache_search_with_callback:
  * @book_cache: An #EBookCache
  * @sexp: (nullable): search expression; use %NULL or an empty string to get all stored contacts
- * @func: an #EBookCacheSearchFunc callback to call for each found row
+ * @func: (scope call): an #EBookCacheSearchFunc callback to call for each found 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/addressbook/libedata-book/e-book-meta-backend.c 
b/src/addressbook/libedata-book/e-book-meta-backend.c
index bcec6fe59..66027d42a 100644
--- a/src/addressbook/libedata-book/e-book-meta-backend.c
+++ b/src/addressbook/libedata-book/e-book-meta-backend.c
@@ -3349,7 +3349,7 @@ e_book_meta_backend_ensure_connected_sync (EBookMetaBackend *meta_backend,
 /**
  * e_book_meta_backend_split_changes_sync:
  * @meta_backend: an #EBookMetaBackend
- * @objects: (inout caller-allocates) (element-type EBookMetaBackendInfo):
+ * @objects: (inout) (element-type EBookMetaBackendInfo):
  *    a #GSList of #EBookMetaBackendInfo object infos to split
  * @out_created_objects: (out) (element-type EBookMetaBackendInfo) (transfer full):
  *    a #GSList of #EBookMetaBackendInfo object infos which had been created
diff --git a/src/addressbook/libedata-book/e-book-sqlite.c b/src/addressbook/libedata-book/e-book-sqlite.c
index 282ed65a2..da9e74221 100644
--- a/src/addressbook/libedata-book/e-book-sqlite.c
+++ b/src/addressbook/libedata-book/e-book-sqlite.c
@@ -6961,7 +6961,7 @@ e_book_sqlite_add_contact (EBookSqlite *ebsql,
 }
 
 /**
- * e_book_sqlite_new_contacts:
+ * e_book_sqlite_add_contacts:
  * @ebsql: An #EBookSqlite
  * @contacts: (element-type EContact): A list of contacts to add to @ebsql
  * @extra: (allow-none) (element-type utf8): A list of extra data to store in association with this contact
@@ -7100,7 +7100,7 @@ generate_delete_stmt (const gchar *table,
 /**
  * e_book_sqlite_remove_contacts:
  * @ebsql: An #EBookSqlite
- * @uids: a #GSList of uids indicating which contacts to remove
+ * @uids: (element-type utf8): a #GSList of uids indicating which contacts to remove
  * @cancellable: (allow-none): A #GCancellable
  * @error: (allow-none): A location to store any error that may have occurred.
  *
@@ -7604,7 +7604,7 @@ e_book_sqlite_search (EBookSqlite *ebsql,
  * e_book_sqlite_search_uids:
  * @ebsql: An #EBookSqlite
  * @sexp: (allow-none): search expression; use %NULL or an empty string to get all stored contacts.
- * @ret_list: (out) (transfer full): Return location to store a #GSList of contact uids
+ * @ret_list: (out) (transfer full) (element-type utf8): Return location to store a #GSList of contact uids
  * @cancellable: (allow-none): A #GCancellable
  * @error: (allow-none): A location to store any error that may have occurred.
  *
diff --git a/src/addressbook/libedata-book/e-data-book-view.c 
b/src/addressbook/libedata-book/e-data-book-view.c
index 86c98af92..c34f1e559 100644
--- a/src/addressbook/libedata-book/e-data-book-view.c
+++ b/src/addressbook/libedata-book/e-data-book-view.c
@@ -707,7 +707,7 @@ e_data_book_view_get_backend (EDataBookView *view)
  *
  * Gets the s-expression used for matching contacts to @view.
  *
- * Returns: The #EBookBackendSExp used.
+ * Returns: (transfer none): The #EBookBackendSExp used.
  *
  * Since: 3.8
  **/
@@ -726,7 +726,7 @@ e_data_book_view_get_sexp (EDataBookView *view)
  * Returns the #GDBusConnection on which the AddressBookView D-Bus
  * interface is exported.
  *
- * Returns: the #GDBusConnection
+ * Returns: (transfer none): the #GDBusConnection
  *
  * Since: 3.8
  **/
@@ -1146,8 +1146,8 @@ e_data_book_view_notify_progress (EDataBookView *view,
  * e_data_book_view_get_fields_of_interest:
  * @view: an #EDataBookView
  *
- * Returns: Hash table of field names which the listener is interested in.
- * Backends can return fully populated objects, but the listener advertised
+ * Returns: (transfer none) (element-type utf8 gint): Hash table of field names which the listener
+ * is interested in. Backends can return fully populated objects, but the listener advertised
  * that it will use only these. Returns %NULL for all available fields.
  *
  * Note: The data pointer in the hash table has no special meaning, it's
diff --git a/src/addressbook/libedata-book/e-data-book.c b/src/addressbook/libedata-book/e-data-book.c
index a99ef4d3c..9bc2288e7 100644
--- a/src/addressbook/libedata-book/e-data-book.c
+++ b/src/addressbook/libedata-book/e-data-book.c
@@ -518,12 +518,12 @@ e_data_book_create_error_fmt (EDataBookStatus status,
 
 /**
  * e_data_book_string_slist_to_comma_string:
- * @strings: (element-type gchar *): a list of gchar *
+ * @strings: (element-type utf8): a list of gchar *
  *
  * Takes a list of strings and converts it to a comma-separated string of
  * values; free returned pointer with g_free()
  *
- * Returns: (transfer full): comma-separated newly allocated text of @strings
+ * Returns: comma-separated newly allocated text of @strings
  *
  * Since: 3.2
  **/
@@ -1517,7 +1517,7 @@ e_data_book_respond_get_contact (EDataBook *book,
  * @book: An #EDataBook
  * @opid: An operation ID
  * @error: Operation error, if any, automatically freed if passed it
- * @cards: (allow-none) (element-type gchar *): A list of vCard strings, or %NULL on error
+ * @cards: (allow-none) (element-type utf8): A list of vCard strings, or %NULL on error
  *
  * Finishes a call to get list of vCards which satisfy certain criteria.
  *
@@ -1573,7 +1573,7 @@ e_data_book_respond_get_contact_list (EDataBook *book,
  * @book: An #EDataBook
  * @opid: An operation ID
  * @error: Operation error, if any, automatically freed if passed it
- * @uids: (allow-none) (element-type gchar *): A list of picked UIDs, or %NULL on error
+ * @uids: (allow-none) (element-type utf8): A list of picked UIDs, or %NULL on error
  *
  * Finishes a call to get list of UIDs which satisfy certain criteria.
  *
@@ -1730,7 +1730,7 @@ e_data_book_respond_modify_contacts (EDataBook *book,
  * @book: An #EDataBook
  * @opid: An operation ID
  * @error: Operation error, if any, automatically freed if passed it
- * @ids: (allow-none) (element-type gchar *): A list of removed contact UID-s, or %NULL on error
+ * @ids: (allow-none) (element-type utf8): A list of removed contact UID-s, or %NULL on error
  *
  * Finishes a call to remove a list of contacts.
  *
@@ -2310,7 +2310,7 @@ e_data_book_ref_backend (EDataBook *book)
  * Returns the #GDBusConnection on which the AddressBook D-Bus interface
  * is exported.
  *
- * Returns: the #GDBusConnection
+ * Returns: (transfer none): the #GDBusConnection
  *
  * Since: 3.8
  **/
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]