[evolution-data-server] M!79 - Add nullable annotations into developer documentation
- From: Milan Crha <mcrha src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [evolution-data-server] M!79 - Add nullable annotations into developer documentation
- Date: Thu, 27 Jan 2022 14:48:00 +0000 (UTC)
commit 617739e67b095dc7ca4623adf6f1f592ee528d55
Author: Michael McClurg <michael mcclurg outlook com>
Date: Thu Jan 27 15:46:47 2022 +0100
M!79 - Add nullable annotations into developer documentation
Closes https://gitlab.gnome.org/GNOME/evolution-data-server/-/merge_requests/79
.../libebook-contacts/e-address-western.c | 3 +-
.../libebook-contacts/e-book-contacts-utils.c | 2 +-
src/addressbook/libebook-contacts/e-contact.c | 9 ++--
src/addressbook/libebook-contacts/e-phone-number.c | 2 +-
src/addressbook/libebook/e-book-client.c | 11 +++--
src/addressbook/libebook/e-book.c | 4 +-
src/addressbook/libebook/e-book.h | 2 +-
.../libedata-book/e-book-backend-sqlitedb.c | 9 ++--
.../libedata-book/e-book-backend-summary.c | 6 +--
.../libedata-book/e-book-backend-sync.c | 2 +-
src/addressbook/libedata-book/e-book-backend.c | 8 ++--
src/addressbook/libedata-book/e-book-cache.c | 8 ++--
.../libedata-book/e-book-meta-backend.c | 2 +-
src/addressbook/libedata-book/e-book-sqlite.c | 13 ++---
.../libedata-book/e-data-book-cursor-cache.c | 2 +-
.../libedata-book/e-data-book-cursor-sqlite.c | 2 +-
src/addressbook/libedata-book/e-data-book-cursor.c | 2 +-
src/addressbook/libedata-book/e-data-book-view.c | 2 +-
src/addressbook/libedata-book/e-data-book.c | 2 +-
src/calendar/backends/file/e-cal-backend-file.c | 8 ++--
src/calendar/libecal/e-cal-check-timezones.c | 2 +
src/calendar/libecal/e-cal-component-alarm.c | 2 +-
src/calendar/libecal/e-cal-component.c | 18 ++++---
src/calendar/libecal/e-cal-system-timezone.c | 3 +-
src/calendar/libecal/e-cal-util.c | 3 +-
src/calendar/libecal/e-reminder-watcher.c | 4 +-
src/calendar/libedata-cal/e-cal-backend-sync.c | 4 +-
src/calendar/libedata-cal/e-cal-backend.c | 30 ++++++------
src/calendar/libedata-cal/e-cal-cache.c | 4 +-
src/calendar/libedata-cal/e-data-cal-view.c | 7 +--
src/camel/camel-async-closure.c | 2 +-
src/camel/camel-block-file.c | 12 ++---
src/camel/camel-cipher-context.c | 12 ++---
src/camel/camel-data-cache.c | 10 ++--
src/camel/camel-debug.c | 4 +-
src/camel/camel-filter-driver.c | 16 +++----
src/camel/camel-folder-search.c | 6 +--
src/camel/camel-folder-summary.c | 6 +--
src/camel/camel-folder.c | 10 ++--
src/camel/camel-internet-address.c | 2 +-
src/camel/camel-message-info.c | 55 +++++++++++-----------
src/camel/camel-mime-parser.c | 15 +++---
src/camel/camel-mime-part-utils.c | 2 +-
src/camel/camel-mime-utils.c | 6 +--
src/camel/camel-multipart.c | 2 +-
src/camel/camel-network-service.c | 10 ++--
src/camel/camel-network-settings.c | 10 ++--
src/camel/camel-offline-folder.c | 4 +-
src/camel/camel-provider.c | 2 +-
src/camel/camel-sasl.c | 12 ++---
src/camel/camel-search-sql-sexp.c | 5 +-
src/camel/camel-service.c | 12 ++---
src/camel/camel-session.c | 12 ++---
src/camel/camel-store-summary.c | 2 +-
src/camel/camel-stream-fs.c | 2 +-
src/camel/camel-string-utils.c | 16 +++----
src/camel/camel-uid-cache.c | 2 +-
src/camel/camel-url.c | 6 +--
src/camel/camel-vee-store.c | 4 +-
src/camel/camel-weak-ref-group.c | 4 +-
src/camel/camel.c | 4 +-
src/camel/providers/imapx/camel-imapx-folder.c | 4 +-
.../providers/imapx/camel-imapx-list-response.c | 6 +--
src/camel/providers/imapx/camel-imapx-mailbox.c | 4 +-
.../imapx/camel-imapx-namespace-response.c | 6 +--
src/camel/providers/imapx/camel-imapx-search.c | 4 +-
src/camel/providers/imapx/camel-imapx-server.c | 10 ++--
src/camel/providers/imapx/camel-imapx-server.h | 2 +-
src/camel/providers/imapx/camel-imapx-settings.c | 24 +++++-----
.../providers/imapx/camel-imapx-status-response.c | 2 +-
.../providers/imapx/camel-imapx-store-summary.c | 2 +-
src/camel/providers/imapx/camel-imapx-store.c | 2 +-
src/camel/providers/imapx/camel-imapx-utils.c | 2 +-
src/camel/providers/nntp/camel-nntp-store.c | 6 +--
src/camel/providers/pop3/camel-pop3-engine.c | 2 +-
src/camel/providers/pop3/camel-pop3-store.c | 4 +-
.../providers/sendmail/camel-sendmail-settings.c | 13 ++---
src/libebackend/e-cache.c | 14 +++---
src/libebackend/e-collection-backend.c | 6 ++-
src/libebackend/e-data-factory.c | 5 +-
src/libebackend/e-file-cache.c | 2 +-
src/libebackend/e-server-side-source.c | 14 +++---
src/libebackend/e-source-registry-server.c | 2 +-
src/libedataserver/e-collator.c | 3 +-
src/libedataserver/e-credentials.c | 2 +-
src/libedataserver/e-data-server-util.c | 23 ++++-----
src/libedataserver/e-flag.c | 2 +-
src/libedataserver/e-free-form-exp.c | 2 +-
src/libedataserver/e-gdata-oauth2-authorizer.c | 4 +-
src/libedataserver/e-soup-session.c | 2 +-
src/libedataserver/e-source-credentials-provider.c | 7 +--
src/libedataserver/e-source-proxy.c | 6 ++-
src/libedataserver/e-source-registry.c | 7 +--
src/libedataserver/e-source.c | 4 +-
src/libedataserver/e-webdav-discover.c | 2 +-
src/libedataserver/e-webdav-session.c | 16 +++----
src/libedataserver/e-xml-hash-utils.c | 4 +-
src/libedataserver/e-xml-utils.c | 2 +-
src/libedataserver/eds-version.c | 8 ++--
src/libedataserverui/e-credentials-prompter.c | 14 +++---
src/libedataserverui/e-webdav-discover-widget.c | 8 ++--
101 files changed, 366 insertions(+), 329 deletions(-)
---
diff --git a/src/addressbook/libebook-contacts/e-address-western.c
b/src/addressbook/libebook-contacts/e-address-western.c
index 3dc5d7284..b76e1d25b 100644
--- a/src/addressbook/libebook-contacts/e-address-western.c
+++ b/src/addressbook/libebook-contacts/e-address-western.c
@@ -310,7 +310,8 @@ e_address_western_extract_street (gchar *line,
* Parses a string representing a mailing address into a
* structure of type #EAddressWestern.
*
- * Returns: A new #EAddressWestern structure, or %NULL if the parsing failed.
+ * Returns: (nullable): A new #EAddressWestern structure, or %NULL if
+ * the parsing failed.
**/
EAddressWestern *
e_address_western_parse (const gchar *in_address)
diff --git a/src/addressbook/libebook-contacts/e-book-contacts-utils.c
b/src/addressbook/libebook-contacts/e-book-contacts-utils.c
index d4efc8f67..465501d83 100644
--- a/src/addressbook/libebook-contacts/e-book-contacts-utils.c
+++ b/src/addressbook/libebook-contacts/e-book-contacts-utils.c
@@ -54,7 +54,7 @@ e_book_client_error_to_string (EBookClientError code)
/**
* e_book_client_error_create:
* @code: an #EBookClientError code to create
- * @custom_msg: custom message to use for the error; can be %NULL
+ * @custom_msg: (nullable): custom message to use for the error; can be %NULL
*
* Returns: a new #GError containing an E_BOOK_CLIENT_ERROR of the given
* @code. If the @custom_msg is NULL, then the error message is
diff --git a/src/addressbook/libebook-contacts/e-contact.c b/src/addressbook/libebook-contacts/e-contact.c
index c8d88d538..66013fef4 100644
--- a/src/addressbook/libebook-contacts/e-contact.c
+++ b/src/addressbook/libebook-contacts/e-contact.c
@@ -1678,7 +1678,8 @@ e_contact_field_type (EContactField field_id)
*
* Gets the string representation of @field_id.
*
- * Returns: The string representation of @field_id, or %NULL if it doesn't exist.
+ * Returns: (nullable): The string representation of @field_id, or %NULL
+ * if it doesn't exist.
**/
const gchar *
e_contact_field_name (EContactField field_id)
@@ -1695,7 +1696,8 @@ e_contact_field_name (EContactField field_id)
* Gets a human-readable, translated string representation
* of @field_id.
*
- * Returns: The human-readable representation of @field_id, or %NULL if it doesn't exist.
+ * Returns: (nullable): The human-readable representation of @field_id, or %NULL
+ * if it doesn't exist.
**/
const gchar *
e_contact_pretty_name (EContactField field_id)
@@ -1716,7 +1718,8 @@ e_contact_pretty_name (EContactField field_id)
*
* Gets the vcard attribute corresponding to @field_id, as a string.
*
- * Returns: The vcard attribute corresponding to @field_id, or %NULL if it doesn't exist.
+ * Returns: (nullable): The vcard attribute corresponding to @field_id,
+ * or %NULL if it doesn't exist.
**/
const gchar *
e_contact_vcard_attribute (EContactField field_id)
diff --git a/src/addressbook/libebook-contacts/e-phone-number.c
b/src/addressbook/libebook-contacts/e-phone-number.c
index 188c7af75..c735becca 100644
--- a/src/addressbook/libebook-contacts/e-phone-number.c
+++ b/src/addressbook/libebook-contacts/e-phone-number.c
@@ -172,7 +172,7 @@ e_phone_number_get_default_region (GError **error)
* If the number is guaranteed to start with a '+' followed by the country
* calling code, then "ZZ" can be passed for @region_code.
*
- * Returns: (transfer full): a new EPhoneNumber instance on success,
+ * Returns: (transfer full) (nullable): a new EPhoneNumber instance on success,
* or %NULL on error. Call e_phone_number_free() to release this instance.
*
* Since: 3.8
diff --git a/src/addressbook/libebook/e-book-client.c b/src/addressbook/libebook/e-book-client.c
index 91776c464..c8451c3e2 100644
--- a/src/addressbook/libebook/e-book-client.c
+++ b/src/addressbook/libebook/e-book-client.c
@@ -1338,7 +1338,8 @@ e_book_client_init (EBookClient *client)
* function will have a descriptive prefix that includes the display
* name of @source.
*
- * Returns: (transfer full) (type EBookClient): a new #EBookClient, or %NULL
+ * Returns: (transfer full) (type EBookClient) (nullable): a new #EBookClient,
+ * or %NULL
*
* Since: 3.8
**/
@@ -1587,7 +1588,8 @@ e_book_client_connect (ESource *source,
* function will have a descriptive prefix that includes the display
* name of the #ESource passed to e_book_client_connect().
*
- * Returns: (transfer full) (type EBookClient): a new #EBookClient, or %NULL
+ * Returns: (transfer full) (type EBookClient) (nullable): a new #EBookClient,
+ * or %NULL
*
* Since: 3.8
**/
@@ -1717,7 +1719,7 @@ connect_direct (EBookClient *client,
* Like e_book_client_connect_sync(), except creates the book client for
* direct read access to the underlying addressbook.
*
- * Returns: (transfer full) (type EBookClient): a new but unopened #EBookClient.
+ * Returns: (transfer full) (type EBookClient) (nullable): a new but unopened #EBookClient.
*
* Since: 3.8
**/
@@ -1863,7 +1865,8 @@ e_book_client_connect_direct (ESource *source,
* function will have a descriptive prefix that includes the display
* name of the #ESource passed to e_book_client_connect_direct().
*
- * Returns: (transfer full) (type EBookClient): a new #EBookClient, or %NULL
+ * Returns: (transfer full) (type EBookClient) (nullable): a new #EBookClient,
+ * or %NULL
*
* Since: 3.12
**/
diff --git a/src/addressbook/libebook/e-book.c b/src/addressbook/libebook/e-book.c
index 06c5953f6..8dfff6d35 100644
--- a/src/addressbook/libebook/e-book.c
+++ b/src/addressbook/libebook/e-book.c
@@ -1659,8 +1659,8 @@ get_book_view_reply (GObject *source_object,
* e_book_async_get_book_view:
* @book: an #EBook
* @query: an #EBookQuery
- * @requested_fields: (element-type utf8): a #GList containing the names of
- * fields to return, or NULL for all
+ * @requested_fields: (element-type utf8) (nullable): a #GList containing
+ * the names of fields to return, or %NULL for all
* @max_results: the maximum number of contacts to show (or 0 for all)
* @cb: (scope async): a function to call when the operation finishes
* @closure: data to pass to callback function
diff --git a/src/addressbook/libebook/e-book.h b/src/addressbook/libebook/e-book.h
index 55810c3a7..cdcb3a0d2 100644
--- a/src/addressbook/libebook/e-book.h
+++ b/src/addressbook/libebook/e-book.h
@@ -102,7 +102,7 @@ typedef void (*EBookIdAsyncCallback) (EBook *book, const GError *error, co
* EBookContactAsyncCallback:
* @book: an #EBook
* @error: a #GError or %NULL
- * @contact: an #EContact or %NULL
+ * @contact: (nullable): an #EContact or %NULL
* @closure: the callback closure
*
* Since: 2.32
diff --git a/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
b/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
index d0847d6a9..0d7ec138a 100644
--- a/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
+++ b/src/addressbook/libedata-book/e-book-backend-sqlitedb.c
@@ -3000,7 +3000,7 @@ store_data_to_vcard (gpointer ref,
* In either case, @with_all_required_fields if specified, will be updated to reflect whether
* the returned vcard string satisfies the passed 'fields_of_interest' parameter.
*
- * Returns: (transfer full): The vcard string for @uid or %NULL if @uid was not found.
+ * Returns: (transfer full) (nullable): The vcard string for @uid or %NULL if @uid was not found.
*
* Since: 3.2
*
@@ -4803,7 +4803,8 @@ e_book_backend_sqlitedb_set_has_partial_content (EBookBackendSqliteDB *ebsdb,
* not being present in @ebsdb, you must pass the @error parameter and
* check whether it was set by this function.</para></note>
*
- * Returns: (transfer full): The extra data previously set for @uid, or %NULL
+ * Returns: (transfer full) (nullable): The extra data previously set
+ * for @uid, or %NULL
*
* Since: 3.2
*
@@ -5093,7 +5094,7 @@ e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
*
* Obsolete, do not use, this always ends with an error.
*
- * Returns: (element-type utf8) (transfer full): %NULL
+ * Returns: (element-type utf8) (transfer full) (nullable): %NULL
*
* Since: 3.2
*
@@ -6004,7 +6005,7 @@ cursor_count_position_locked (EBookBackendSqliteDB *ebsdb,
* e_book_backend_sqlitedb_cursor_new: (skip)
* @ebsdb: An #EBookBackendSqliteDB
* @folderid: folder id of the address-book
- * @sexp: search expression; use NULL or an empty string to get all stored contacts.
+ * @sexp: (nullable): search expression; use %NULL or an empty string to get all stored contacts.
* @sort_fields: (array length=n_sort_fields): An array of #EContactFields as sort keys in order of priority
* @sort_types: (array length=n_sort_fields): An array of #EBookCursorSortTypes, one for each field in
@sort_fields
* @n_sort_fields: The number of fields to sort results by.
diff --git a/src/addressbook/libedata-book/e-book-backend-summary.c
b/src/addressbook/libedata-book/e-book-backend-summary.c
index 29907cc35..389157f5a 100644
--- a/src/addressbook/libedata-book/e-book-backend-summary.c
+++ b/src/addressbook/libedata-book/e-book-backend-summary.c
@@ -1292,10 +1292,10 @@ e_book_backend_summary_search (EBookBackendSummary *summary,
* @summary: an #EBookBackendSummary
* @id: a unique contact ID
*
- * Constructs and returns a VCard from the contact summary specified
- * by @id.
+ * Constructs and returns a VCard from the contact summary specified by @id.
*
- * Returns: A new VCard, or %NULL if the contact summary didn't exist.
+ * Returns: (nullable): A new VCard, or %NULL if the contact summary
+ * didn't exist.
*
* Deprecated: 3.12: Use #EBookSqlite instead
**/
diff --git a/src/addressbook/libedata-book/e-book-backend-sync.c
b/src/addressbook/libedata-book/e-book-backend-sync.c
index 405218ddf..e356fbdc8 100644
--- a/src/addressbook/libedata-book/e-book-backend-sync.c
+++ b/src/addressbook/libedata-book/e-book-backend-sync.c
@@ -490,7 +490,7 @@ e_book_backend_sync_remove_contacts (EBookBackendSync *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: (transfer full): an #EContact, or %NULL
+ * Returns: (transfer full) (nullable): an #EContact, or %NULL
*
* Since: 3.34
**/
diff --git a/src/addressbook/libedata-book/e-book-backend.c b/src/addressbook/libedata-book/e-book-backend.c
index 4457664f2..8428be529 100644
--- a/src/addressbook/libedata-book/e-book-backend.c
+++ b/src/addressbook/libedata-book/e-book-backend.c
@@ -1991,7 +1991,7 @@ e_book_backend_remove_contacts_finish (EBookBackend *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: (transfer full): an #EContact, or %NULL
+ * Returns: (transfer full) (nullable): an #EContact, or %NULL
*
* Since: 3.10
**/
@@ -2136,7 +2136,7 @@ e_book_backend_get_contact (EBookBackend *backend,
*
* If an error occurred, the function will set @error and return %NULL.
*
- * Returns: (transfer full): an #EContact, or %NULL
+ * Returns: (transfer full) (nullable): an #EContact, or %NULL
*
* Since: 3.10
**/
@@ -3406,8 +3406,8 @@ e_book_backend_prepare_for_completion (EBookBackend *backend,
* The returned cursor belongs to @backend and should be destroyed
* with e_book_backend_delete_cursor() when no longer needed.
*
- * Returns: (transfer none): A newly created cursor, the cursor belongs
- * to the backend and should not be unreffed, or %NULL
+ * Returns: (transfer none) (nullable): A newly created cursor, the cursor
+ * belongs to the backend and should not be unreffed, or %NULL
*
* Since: 3.12
*/
diff --git a/src/addressbook/libedata-book/e-book-cache.c b/src/addressbook/libedata-book/e-book-cache.c
index 1e62e7d57..6291b7ac1 100644
--- a/src/addressbook/libedata-book/e-book-cache.c
+++ b/src/addressbook/libedata-book/e-book-cache.c
@@ -183,7 +183,7 @@ e_book_cache_search_data_new (const gchar *uid,
* e_book_cache_search_data_copy:
* @data: (nullable): a source #EBookCacheSearchData to copy, or %NULL
*
- * Returns: (transfer full): Copy of the given @data. Free it with
+ * Returns: (transfer full) (nullable): Copy of the given @data. Free it with
* e_book_cache_search_data_free() when no longer needed.
* If the @data is %NULL, then returns %NULL as well.
*
@@ -4706,8 +4706,8 @@ e_book_cache_new_full (const gchar *filename,
* use g_object_unref() when no longer needed.
* It can be %NULL in some cases, like when running tests.
*
- * Returns: (transfer full): A reference to the #ESource to which @book_cache
- * is paired, or %NULL.
+ * Returns: (transfer full) (nullable): A reference to the #ESource to which
+ * @book_cache is paired, or %NULL.
*
* Since: 3.26
**/
@@ -5632,7 +5632,7 @@ e_book_cache_contains_email (EBookCache *book_cache,
/**
* e_book_cache_cursor_new:
* @book_cache: An #EBookCache
- * @sexp: search expression; use %NULL or an empty string to get all stored contacts
+ * @sexp: (nullable): search expression; use %NULL or an empty string to get all stored contacts
* @sort_fields: (array length=n_sort_fields): An array of #EContactField(s) as sort keys in order of
priority
* @sort_types: (array length=n_sort_fields): An array of #EBookCursorSortTypes, one for each field in
@sort_fields
* @n_sort_fields: The number of fields to sort results by
diff --git a/src/addressbook/libedata-book/e-book-meta-backend.c
b/src/addressbook/libedata-book/e-book-meta-backend.c
index a8029ab41..fee3aa92d 100644
--- a/src/addressbook/libedata-book/e-book-meta-backend.c
+++ b/src/addressbook/libedata-book/e-book-meta-backend.c
@@ -165,7 +165,7 @@ e_book_meta_backend_info_new (const gchar *uid,
* e_book_meta_backend_info_copy:
* @src: (nullable): a source EBookMetaBackendInfo to copy, or %NULL
*
- * Returns: (transfer full): Copy of the given @src. Free it with
+ * Returns: (transfer full) (nullable): Copy of the given @src. Free it with
* e_book_meta_backend_info_free() when no longer needed.
* If the @src is %NULL, then returns %NULL as well.
*
diff --git a/src/addressbook/libedata-book/e-book-sqlite.c b/src/addressbook/libedata-book/e-book-sqlite.c
index ee4d4e032..fd3f44b39 100644
--- a/src/addressbook/libedata-book/e-book-sqlite.c
+++ b/src/addressbook/libedata-book/e-book-sqlite.c
@@ -5799,7 +5799,7 @@ ebsql_do_search_query (EBookSqlite *ebsql,
/* ebsql_search_query:
* @ebsql: An EBookSqlite
- * @sexp: The search expression, or NULL for all contacts
+ * @sexp: (nullable): The search expression, or %NULL for all contacts
* @search_type: Indicates what kind of data should be returned
* @return_data: A list of data fetched from the DB, as specified by 'search_type'
* @error: Location to store any error which may have occurred
@@ -6617,7 +6617,7 @@ e_book_sqlite_new (const gchar *path,
/**
* e_book_sqlite_new_full:
* @path: location to load or create the new database
- * @source: an optional #ESource, associated with the #EBookSqlite, or %NULL
+ * @source: (nullable): an optional #ESource, associated with the #EBookSqlite, or %NULL
* @setup: (nullable): an #ESourceBackendSummarySetup describing how the summary should be setup, or %NULL
to use the default
* @vcard_callback: (nullable) (scope async) (closure user_data): A function to resolve vcards
* @change_callback: (nullable) (scope async) (closure user_data): A function to catch notifications of
vcard changes
@@ -6651,7 +6651,8 @@ e_book_sqlite_new (const gchar *path,
* if at all possible, however in some cases the vcards must be stored in some
* other storage.
*
- * Returns: (transfer full): The newly created #EBookSqlite, or %NULL if opening or creating the addressbook
failed.
+ * Returns: (transfer full) (nullable): The newly created #EBookSqlite, or %NULL if
+ * opening or creating the addressbook failed.
*
* Since: 3.12
**/
@@ -6907,8 +6908,8 @@ e_book_sqlite_ref_collator (EBookSqlite *ebsql)
* use g_object_unref() when finished using the source.
* It can be %NULL in some cases, like when running tests.
*
- * Returns: (transfer full): A reference to the #ESource to which @ebsql
- * is paired, or %NULL.
+ * Returns: (transfer full) (nullable): A reference to the #ESource to which
+ * @ebsql is paired, or %NULL.
*
* Since: 3.16
*/
@@ -7927,7 +7928,7 @@ e_book_sqlite_get_locale (EBookSqlite *ebsql,
/**
* e_book_sqlite_cursor_new: (skip)
* @ebsql: An #EBookSqlite
- * @sexp: search expression; use NULL or an empty string to get all stored contacts.
+ * @sexp: (nullable): search expression; use %NULL or an empty string to get all stored contacts.
* @sort_fields: (array length=n_sort_fields): An array of #EContactFields as sort keys in order of priority
* @sort_types: (array length=n_sort_fields): An array of #EBookCursorSortTypes, one for each field in
@sort_fields
* @n_sort_fields: The number of fields to sort results by.
diff --git a/src/addressbook/libedata-book/e-data-book-cursor-cache.c
b/src/addressbook/libedata-book/e-data-book-cursor-cache.c
index c2cf9d69b..c1a249160 100644
--- a/src/addressbook/libedata-book/e-data-book-cursor-cache.c
+++ b/src/addressbook/libedata-book/e-data-book-cursor-cache.c
@@ -389,7 +389,7 @@ e_data_book_cursor_cache_init (EDataBookCursorCache *cache_cursor)
* This is suitable cursor type for any backend which stores its contacts
* using the #EBookCache object. The #EBookMetaBackend does that transparently.
*
- * Returns: (transfer full): A newly created #EDataBookCursor, or %NULL if cursor creation failed.
+ * Returns: (transfer full) (nullable): A newly created #EDataBookCursor, or %NULL if cursor creation failed.
*
* Since: 3.26
*/
diff --git a/src/addressbook/libedata-book/e-data-book-cursor-sqlite.c
b/src/addressbook/libedata-book/e-data-book-cursor-sqlite.c
index 6ba42799b..eb9796a6c 100644
--- a/src/addressbook/libedata-book/e-data-book-cursor-sqlite.c
+++ b/src/addressbook/libedata-book/e-data-book-cursor-sqlite.c
@@ -504,7 +504,7 @@ e_data_book_cursor_sqlite_load_locale (EDataBookCursor *cursor,
* This is a suitable cursor type for any backend which stores its contacts
* using the #EBookSqlite object.
*
- * Returns: (transfer full): A newly created #EDataBookCursor, or %NULL if cursor creation failed.
+ * Returns: (transfer full) (nullable): A newly created #EDataBookCursor, or %NULL if cursor creation failed.
*
* Since: 3.12
*/
diff --git a/src/addressbook/libedata-book/e-data-book-cursor.c
b/src/addressbook/libedata-book/e-data-book-cursor.c
index 40f7ebb28..51034b0a5 100644
--- a/src/addressbook/libedata-book/e-data-book-cursor.c
+++ b/src/addressbook/libedata-book/e-data-book-cursor.c
@@ -791,7 +791,7 @@ e_data_book_cursor_set_sexp (EDataBookCursor *cursor,
/**
* e_data_book_cursor_step:
* @cursor: an #EDataBookCursor
- * @revision_guard: The expected current addressbook revision, or %NULL
+ * @revision_guard: (nullable): The expected current addressbook revision, or %NULL
* @flags: The #EBookCursorStepFlags for this step
* @origin: The #EBookCursorOrigin from whence to step
* @count: a positive or negative amount of contacts to try and fetch
diff --git a/src/addressbook/libedata-book/e-data-book-view.c
b/src/addressbook/libedata-book/e-data-book-view.c
index 462a995c5..bf803c40e 100644
--- a/src/addressbook/libedata-book/e-data-book-view.c
+++ b/src/addressbook/libedata-book/e-data-book-view.c
@@ -688,7 +688,7 @@ e_data_book_view_init (EDataBookView *view)
* @connection at @object_path. If an error occurs while exporting,
* the function sets @error and returns %NULL.
*
- * Returns: an #EDataBookView
+ * Returns: (nullable): an #EDataBookView
*/
EDataBookView *
e_data_book_view_new (EBookBackend *backend,
diff --git a/src/addressbook/libedata-book/e-data-book.c b/src/addressbook/libedata-book/e-data-book.c
index 2d48488b2..5773214cf 100644
--- a/src/addressbook/libedata-book/e-data-book.c
+++ b/src/addressbook/libedata-book/e-data-book.c
@@ -2063,7 +2063,7 @@ e_data_book_init (EDataBook *data_book)
* method invocations and forwards them to the @backend. If the AddressBook
* interface fails to export, the function sets @error and returns %NULL.
*
- * Returns: an #EDataBook, or %NULL on error
+ * Returns: (nullable): an #EDataBook, or %NULL on error
**/
EDataBook *
e_data_book_new (EBookBackend *backend,
diff --git a/src/calendar/backends/file/e-cal-backend-file.c b/src/calendar/backends/file/e-cal-backend-file.c
index 376c54e58..5322bdf8e 100644
--- a/src/calendar/backends/file/e-cal-backend-file.c
+++ b/src/calendar/backends/file/e-cal-backend-file.c
@@ -2936,10 +2936,10 @@ e_cal_backend_file_discard_alarm_sync (ECalBackendSync *backend,
* TODO: E_CAL_OBJ_MOD_ONLY_THIS
* @uid pointer to UID which must remain valid even if the object gets
* removed
- * @rid NULL, "", or non-empty string when manipulating a specific recurrence;
- * also must remain valid
- * @error may be NULL if caller is not interested in errors
- * @return modified object or NULL if it got removed
+ * @rid: (nullable): %NULL, "", or non-empty string when manipulating a
+ * specific recurrence; also must remain valid
+ * @error may be %NULL if caller is not interested in errors
+ * @return: (nullable): modified object or %NULL if it got removed
*/
static ECalBackendFileObject *
remove_instance (ECalBackendFile *cbfile,
diff --git a/src/calendar/libecal/e-cal-check-timezones.c b/src/calendar/libecal/e-cal-check-timezones.c
index fb1dd80b5..6648de6ef 100644
--- a/src/calendar/libecal/e-cal-check-timezones.c
+++ b/src/calendar/libecal/e-cal-check-timezones.c
@@ -71,6 +71,8 @@ e_cal_match_location (const gchar *location)
* Matches @tzid against the system timezone definitions
* and returns the matching TZID, or %NULL if none found
*
+ * Returns: (nullable): The matching TZID, or %NULL
+ * if none found
* Since: 2.24
*/
const gchar *
diff --git a/src/calendar/libecal/e-cal-component-alarm.c b/src/calendar/libecal/e-cal-component-alarm.c
index 228b32e3d..6a1d0c073 100644
--- a/src/calendar/libecal/e-cal-component-alarm.c
+++ b/src/calendar/libecal/e-cal-component-alarm.c
@@ -626,7 +626,7 @@ e_cal_component_alarm_get_uid (const ECalComponentAlarm *alarm)
/**
* e_cal_component_alarm_set_uid:
* @alarm: an #ECalComponentAlarm
- * @uid: (nullable): a UID to set, or %NULL or emptry string to generate new
+ * @uid: (nullable): a UID to set, or %NULL or empty string to generate new
*
* Set the @alarm UID, or generates a new UID, if @uid is %NULL or an empty string.
*
diff --git a/src/calendar/libecal/e-cal-component.c b/src/calendar/libecal/e-cal-component.c
index ace7033da..dd709d2f9 100644
--- a/src/calendar/libecal/e-cal-component.c
+++ b/src/calendar/libecal/e-cal-component.c
@@ -306,8 +306,8 @@ e_cal_component_new_vtype (ECalComponentVType vtype)
*
* Creates a new calendar component object from the given iCalendar string.
*
- * Returns: (transfer full): A calendar component representing the given iCalendar string on
- * success, NULL if there was an error.
+ * Returns: (transfer full) (nullable): A calendar component representing
+ * the given iCalendar string on success, %NULL if there was an error.
*
* Since: 3.34
**/
@@ -335,8 +335,9 @@ e_cal_component_new_from_string (const gchar *calobj)
* to e_cal_component_set_icalcomponent() fails, then @icalcomp
* is freed.
*
- * Returns: (transfer full): An #ECalComponent with @icalcomp assigned on success,
- * NULL if the @icalcomp cannot be assigned to #ECalComponent.
+ * Returns: (transfer full) (nullable): An #ECalComponent with @icalcomp
+ * assigned on success, %NULL if the @icalcomp cannot be assigned to
+ * #ECalComponent.
*
* Since: 3.34
**/
@@ -1444,7 +1445,8 @@ set_icaltimetype (ICalComponent *icalcomp,
* Free the returned non-NULL pointer with g_object_unref(), when
* no longer needed.
*
- * Returns: (transfer full): the completion date, as an #ICalTime, or %NULL, when none is set
+ * Returns: (transfer full) (nullable): the completion date, as an #ICalTime,
+ * or %NULL, when none is set
*
* Since: 3.34
**/
@@ -1502,7 +1504,8 @@ e_cal_component_set_completed (ECalComponent *comp,
* calendar store. Free the returned non-NULL pointer with g_object_unref(), when
* no longer needed.
*
- * Returns: (transfer full): the creation date, as an #ICalTime, or %NULL, when none is set
+ * Returns: (transfer full) (nullable): the creation date, as an #ICalTime, or
+ * %NULL, when none is set
*
* Since: 3.34
**/
@@ -2544,7 +2547,8 @@ e_cal_component_set_geo (ECalComponent *comp,
* the calendar store. Free the returned non-NULL pointer with g_object_unref(),
* when no longer needed.
*
- * Returns: (transfer full): the last modified time, as an #ICalTime, or %NULL, when none is set
+ * Returns: (transfer full) (nullable): the last modified time, as an
+ * #ICalTime, or %NULL, when none is set
*
* Since: 3.34
**/
diff --git a/src/calendar/libecal/e-cal-system-timezone.c b/src/calendar/libecal/e-cal-system-timezone.c
index 6fe12dbd7..3d07799e5 100644
--- a/src/calendar/libecal/e-cal-system-timezone.c
+++ b/src/calendar/libecal/e-cal-system-timezone.c
@@ -946,7 +946,8 @@ system_timezone_win32_query_registry (void)
*
* The returned string should be freed with g_free().
*
- * Returns: (transfer full): system timezone location string, or %NULL on an error.
+ * Returns: (transfer full) (nullable): system timezone location string, or
+ * %NULL on an error.
*
* Since: 2.28
**/
diff --git a/src/calendar/libecal/e-cal-util.c b/src/calendar/libecal/e-cal-util.c
index 2db174f99..fed67ffae 100644
--- a/src/calendar/libecal/e-cal-util.c
+++ b/src/calendar/libecal/e-cal-util.c
@@ -1945,7 +1945,8 @@ e_cal_util_is_first_instance (ECalComponent *comp,
*
* Fetches system timezone localtion string.
*
- * Returns: (transfer full): system timezone location string, %NULL on an error.
+ * Returns: (transfer full) (nullable): system timezone location string, %NULL
+ * on an error.
*
* Since: 2.28
**/
diff --git a/src/calendar/libecal/e-reminder-watcher.c b/src/calendar/libecal/e-reminder-watcher.c
index 4f9c4af94..a24ede2bc 100644
--- a/src/calendar/libecal/e-reminder-watcher.c
+++ b/src/calendar/libecal/e-reminder-watcher.c
@@ -518,8 +518,8 @@ e_reminder_data_new (const gchar *source_uid,
*
* Copies given #EReminderData structure. When the @rd is %NULL, simply returns %NULL as well.
*
- * Returns: (transfer full): copy of @rd. Free the returned structure
- * with e_reminder_data_free() when no longer needed.
+ * Returns: (transfer full) (nullable): copy of @rd. Free the returned
+ * structure with e_reminder_data_free() when no longer needed.
*
* Since: 3.30
**/
diff --git a/src/calendar/libedata-cal/e-cal-backend-sync.c b/src/calendar/libedata-cal/e-cal-backend-sync.c
index f1eaac85b..0eb31ec4b 100644
--- a/src/calendar/libedata-cal/e-cal-backend-sync.c
+++ b/src/calendar/libedata-cal/e-cal-backend-sync.c
@@ -110,8 +110,8 @@ e_cal_backend_sync_refresh (ECalBackendSync *backend,
* @cal: An EDataCal object.
* @cancellable: a #GCancellable for the operation
* @uid: UID of the object to get.
- * @rid: Recurrence ID of the specific instance to get, or NULL if getting the
- * master object.
+ * @rid: (nullable): Recurrence ID of the specific instance to get, or %NULL if
+ * getting the master object.
* @calobj: (out) (transfer full): Placeholder for returned object.
* @error: Out parameter for a #GError.
*
diff --git a/src/calendar/libedata-cal/e-cal-backend.c b/src/calendar/libedata-cal/e-cal-backend.c
index 66e314c1b..04004da44 100644
--- a/src/calendar/libedata-cal/e-cal-backend.c
+++ b/src/calendar/libedata-cal/e-cal-backend.c
@@ -1343,7 +1343,7 @@ e_cal_backend_get_kind (ECalBackend *backend)
* The returned #EDataCal is referenced for thread-safety and must be
* unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): an #EDataCal, or %NULL
+ * Returns: (transfer full) (nullable): an #EDataCal, or %NULL
*
* Since: 3.10
**/
@@ -1603,8 +1603,8 @@ e_cal_backend_set_cache_dir (ECalBackend *backend,
* e_cal_backend_create_cache_filename:
* @backend: an #ECalBackend
* @uid: a component UID
- * @filename: a filename to use; can be NULL
- * @fileindex: index of a file; used only when @filename is NULL
+ * @filename: (nullable): a filename to use; can be %NULL
+ * @fileindex: index of a file; used only when @filename is %NULL
*
* Returns: a filename for an attachment in a local cache dir. Free returned
* pointer with a g_free().
@@ -2188,7 +2188,7 @@ e_cal_backend_refresh_finish (ECalBackend *backend,
* e_cal_backend_get_object_sync:
* @backend: an #ECalBackend
* @uid: a unique ID for an iCalendar object
- * @rid: a recurrence ID, or %NULL
+ * @rid: (nullable): a recurrence ID, or %NULL
* @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
*
@@ -2199,7 +2199,7 @@ e_cal_backend_refresh_finish (ECalBackend *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: an #ECalComponent, or %NULL
+ * Returns: (nullable): an #ECalComponent, or %NULL
*
* Since: 3.10
**/
@@ -2281,7 +2281,7 @@ cal_backend_get_object_thread (GSimpleAsyncResult *simple,
* e_cal_backend_get_object:
* @backend: an #ECalBackend
* @uid: a unique ID for an iCalendar object
- * @rid: a recurrence ID, or %NULL
+ * @rid: (nullable): a recurrence ID, or %NULL
* @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
@@ -2344,7 +2344,7 @@ e_cal_backend_get_object (ECalBackend *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: an #ECalComponent, or %NULL
+ * Returns: (nullable): an #ECalComponent, or %NULL
*
* Since: 3.10
**/
@@ -3705,7 +3705,7 @@ e_cal_backend_receive_objects_finish (ECalBackend *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: a vCalendar string, or %NULL
+ * Returns: (nullable): a vCalendar string, or %NULL
*
* Since: 3.10
**/
@@ -3854,7 +3854,7 @@ e_cal_backend_send_objects (ECalBackend *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: a newly allocated vCalendar string, or %NULL
+ * Returns: (nullable): a newly allocated vCalendar string, or %NULL
*
* Since: 3.10
**/
@@ -3893,7 +3893,7 @@ e_cal_backend_send_objects_finish (ECalBackend *backend,
* e_cal_backend_get_attachment_uris_sync:
* @backend: an #ECalBackend
* @uid: a unique ID for an iCalendar object
- * @rid: a recurrence ID, or %NULL
+ * @rid: (nullable): a recurrence ID, or %NULL
* @out_attachment_uris: a #GQueue in which to deposit results
* @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
@@ -3990,7 +3990,7 @@ cal_backend_get_attachment_uris_thread (GSimpleAsyncResult *simple,
* e_cal_backend_get_attachment_uris:
* @backend: an #ECalBackend
* @uid: a unique ID for an iCalendar object
- * @rid: a recurrence ID, or %NULL
+ * @rid: (nullable): a recurrence ID, or %NULL
* @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
@@ -4092,7 +4092,7 @@ e_cal_backend_get_attachment_uris_finish (ECalBackend *backend,
* e_cal_backend_discard_alarm_sync:
* @backend: an #ECalBackend
* @uid: a unique ID for an iCalendar object
- * @rid: a recurrence ID, or %NULL
+ * @rid: (nullable): a recurrence ID, or %NULL
* @alarm_uid: a unique ID for an iCalendar VALARM object
* @opflags: bit-or of #ECalOperationFlags
* @cancellable: optional #GCancellable object, or %NULL
@@ -4198,7 +4198,7 @@ cal_backend_discard_alarm_thread (GSimpleAsyncResult *simple,
* e_cal_backend_discard_alarm:
* @backend: an #ECalBackend
* @uid: a unique ID for an iCalendar object
- * @rid: a recurrence ID, or %NULL
+ * @rid: (nullable): a recurrence ID, or %NULL
* @alarm_uid: a unique ID for an iCalendar VALARM object
* @opflags: bit-or of #ECalOperationFlags
* @cancellable: optional #GCancellable object, or %NULL
@@ -4302,7 +4302,7 @@ e_cal_backend_discard_alarm_finish (ECalBackend *backend,
*
* If an error occurs, the function will set @error and return %NULL.
*
- * Returns: an iCalendar string, or %NULL
+ * Returns: (nullable): an iCalendar string, or %NULL
*
* Since: 3.10
**/
@@ -4440,7 +4440,7 @@ e_cal_backend_get_timezone (ECalBackend *backend,
*
* If an error occurred, the function will set @error and return %NULL.
*
- * Returns: an iCalendar string, or %NULL
+ * Returns: (nullable): an iCalendar string, or %NULL
*
* Since: 3.10
**/
diff --git a/src/calendar/libedata-cal/e-cal-cache.c b/src/calendar/libedata-cal/e-cal-cache.c
index 4b6d3ed21..b153fcf07 100644
--- a/src/calendar/libedata-cal/e-cal-cache.c
+++ b/src/calendar/libedata-cal/e-cal-cache.c
@@ -143,7 +143,7 @@ e_cal_cache_offline_change_new (const gchar *uid,
* e_cal_cache_offline_change_copy:
* @change: (nullable): a source #ECalCacheOfflineChange to copy, or %NULL
*
- * Returns: (transfer full): Copy of the given @change. Free it with
+ * Returns: (transfer full) (nullable): Copy of the given @change. Free it with
* e_cal_cache_offline_change_free() when no longer needed.
* If the @change is %NULL, then returns %NULL as well.
*
@@ -219,7 +219,7 @@ e_cal_cache_search_data_new (const gchar *uid,
* e_cal_cache_search_data_copy:
* @data: (nullable): a source #ECalCacheSearchData to copy, or %NULL
*
- * Returns: (transfer full): Copy of the given @data. Free it with
+ * Returns: (transfer full) (nullable): Copy of the given @data. Free it with
* e_cal_cache_search_data_free() when no longer needed.
* If the @data is %NULL, then returns %NULL as well.
*
diff --git a/src/calendar/libedata-cal/e-data-cal-view.c b/src/calendar/libedata-cal/e-data-cal-view.c
index aed964107..bd63317ea 100644
--- a/src/calendar/libedata-cal/e-data-cal-view.c
+++ b/src/calendar/libedata-cal/e-data-cal-view.c
@@ -1060,9 +1060,10 @@ e_data_cal_view_is_completed (EDataCalView *view)
* e_data_cal_view_get_fields_of_interest:
* @view: an #EDataCalView
*
- * Returns: (transfer none): 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.
+ * Returns: (transfer none) (nullable): 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
* only GINT_TO_POINTER(1) for easier checking. Also, field names are
diff --git a/src/camel/camel-async-closure.c b/src/camel/camel-async-closure.c
index 970c36337..c40648392 100644
--- a/src/camel/camel-async-closure.c
+++ b/src/camel/camel-async-closure.c
@@ -163,7 +163,7 @@ camel_async_closure_free (CamelAsyncClosure *closure)
/**
* camel_async_closure_callback: (skip)
- * @source_object: a #GObject or %NULL
+ * @source_object: (nullable): a #GObject or %NULL
* @result: a #GAsyncResult
* @closure: a #CamelAsyncClosure
*
diff --git a/src/camel/camel-block-file.c b/src/camel/camel-block-file.c
index 8d24f343c..45d992b9c 100644
--- a/src/camel/camel-block-file.c
+++ b/src/camel/camel-block-file.c
@@ -352,7 +352,7 @@ block_file_unuse (CamelBlockFile *bs)
*
* @block_size is currently ignored and is set to CAMEL_BLOCK_SIZE.
*
- * Returns: The new block file, or NULL if it could not be created.
+ * Returns: (nullable): The new block file, or %NULL if it could not be created.
**/
CamelBlockFile *
camel_block_file_new (const gchar *path,
@@ -553,7 +553,7 @@ camel_block_file_delete (CamelBlockFile *bs)
* Allocate a new block, return a pointer to it. Old blocks
* may be flushed to disk during this call.
*
- * Returns: The block, or NULL if an error occurred.
+ * Returns: (nullable): The block, or %NULL if an error occurred.
**/
CamelBlock *
camel_block_file_new_block (CamelBlockFile *bs)
@@ -625,8 +625,8 @@ camel_block_file_free_block (CamelBlockFile *bs,
*
* Retreive a block @id.
*
- * Returns: The block, or NULL if blockid is invalid or a file error
- * occurred.
+ * Returns: (nullable): The block, or %NULL if blockid is invalid or a file
+ * error occurred.
**/
CamelBlock *
camel_block_file_get_block (CamelBlockFile *bs,
@@ -1116,8 +1116,8 @@ key_file_unuse (CamelKeyFile *kf)
*
* Create a new key file. A linked list of record blocks.
*
- * Returns: A new key file, or NULL if the file could not
- * be opened/created/initialised.
+ * Returns: (nullable): A new key file, or %NULL if the file could not
+ * be opened/created/initialised.
**/
CamelKeyFile *
camel_key_file_new (const gchar *path,
diff --git a/src/camel/camel-cipher-context.c b/src/camel/camel-cipher-context.c
index 0664204cf..99eba090e 100644
--- a/src/camel/camel-cipher-context.c
+++ b/src/camel/camel-cipher-context.c
@@ -456,7 +456,7 @@ camel_cipher_context_sign_finish (CamelCipherContext *context,
*
* Verifies the signature.
*
- * Returns: a #CamelCipherValidity structure containing information
+ * Returns: (nullable): a #CamelCipherValidity structure containing information
* about the integrity of the input stream, or %NULL on failure to
* execute at all
**/
@@ -575,7 +575,7 @@ camel_cipher_context_verify (CamelCipherContext *context,
*
* Finishes the operation started with camel_cipher_context_verify().
*
- * Returns: a #CamelCipherValidity structure containing information
+ * Returns: (nullable): a #CamelCipherValidity structure containing information
* about the integrity of the input stream, or %NULL on failure to
* execute at all
*
@@ -599,7 +599,7 @@ camel_cipher_context_verify_finish (CamelCipherContext *context,
/**
* camel_cipher_context_encrypt_sync:
* @context: a #CamelCipherContext
- * @userid: key ID (or email address) to use when signing, or %NULL to not sign
+ * @userid: (nullable): key ID (or email address) to use when signing, or %NULL to not sign
* @recipients: (element-type utf8): an array of recipient key IDs and/or email addresses
* @ipart: clear-text #CamelMimePart
* @opart: cipher-text #CamelMimePart
@@ -686,7 +686,7 @@ cipher_context_encrypt_thread (GTask *task,
/**
* camel_cipher_context_encrypt:
* @context: a #CamelCipherContext
- * @userid: key id (or email address) to use when signing, or %NULL to not sign
+ * @userid: (nullable): key id (or email address) to use when signing, or %NULL to not sign
* @recipients: (element-type utf8): an array of recipient key IDs and/or email addresses
* @ipart: clear-text #CamelMimePart
* @opart: cipher-text #CamelMimePart
@@ -784,7 +784,7 @@ camel_cipher_context_encrypt_finish (CamelCipherContext *context,
*
* Decrypts @ipart into @opart.
*
- * Returns: a validity/encryption status, or %NULL on error
+ * Returns: (nullable): a validity/encryption status, or %NULL on error
*
* Since: 3.0
**/
@@ -915,7 +915,7 @@ camel_cipher_context_decrypt (CamelCipherContext *context,
*
* Finishes the operation started with camel_cipher_context_decrypt().
*
- * Returns: a validity/encryption status, or %NULL on error
+ * Returns: (nullable): a validity/encryption status, or %NULL on error
*
* Since: 3.0
**/
diff --git a/src/camel/camel-data-cache.c b/src/camel/camel-data-cache.c
index fe0212d52..f0c52ff17 100644
--- a/src/camel/camel-data-cache.c
+++ b/src/camel/camel-data-cache.c
@@ -184,8 +184,8 @@ camel_data_cache_init (CamelDataCache *data_cache)
*
* Create a new data cache.
*
- * Returns: A new cache object, or NULL if the base path cannot
- * be written to.
+ * Returns: (nullable): A new cache object, or %NULL if the base path cannot
+ * be written to.
**/
CamelDataCache *
camel_data_cache_new (const gchar *path,
@@ -445,7 +445,8 @@ data_cache_path (CamelDataCache *cdc,
* The returned #GIOStream is referenced for thread-safety and must be
* unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): a #GIOStream for the new cache item, or %NULL
+ * Returns: (transfer full) (nullable): a #GIOStream for the new cache item,
+ * or %NULL
**/
GIOStream *
camel_data_cache_add (CamelDataCache *cdc,
@@ -501,7 +502,8 @@ camel_data_cache_add (CamelDataCache *cdc,
* The returned #GIOStream is referenced for thread-safety and must be
* unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): a #GIOStream for the requested cache item, or %NULL
+ * Returns: (transfer full) (nullable): a #GIOStream for the requested cache
+ * item, or %NULL
**/
GIOStream *
camel_data_cache_get (CamelDataCache *cdc,
diff --git a/src/camel/camel-debug.c b/src/camel/camel-debug.c
index 680569130..3f485bae7 100644
--- a/src/camel/camel-debug.c
+++ b/src/camel/camel-debug.c
@@ -800,7 +800,7 @@ camel_pointer_tracker_dump (void)
*
* Gets current backtrace leading to this function call and demangles it.
*
- * Returns: Current backtrace, or %NULL, if cannot determine it.
+ * Returns: (nullable): Current backtrace, or %NULL, if cannot determine it.
*
* Note: Getting backtraces only works if the library was
* configured with --enable-backtraces.
@@ -833,7 +833,7 @@ camel_debug_get_backtrace (void)
* with actual function calls and eventually line numbers, if
* available) call camel_debug_demangle_backtrace().
*
- * Returns: Current raw backtrace, or %NULL, if cannot determine it.
+ * Returns: (nullable): Current raw backtrace, or %NULL, if cannot determine it.
*
* Note: Getting backtraces only works if the library was
* configured with --enable-backtraces.
diff --git a/src/camel/camel-filter-driver.c b/src/camel/camel-filter-driver.c
index 7553daa78..766f5feb3 100644
--- a/src/camel/camel-filter-driver.c
+++ b/src/camel/camel-filter-driver.c
@@ -1754,8 +1754,8 @@ fail:
* @driver: CamelFilterDriver
* @folder: CamelFolder to be filtered
* @cache: UID cache (needed for POP folders)
- * @uids: (element-type utf8): message uids to be filtered or NULL (as a
- * shortcut to filter all messages)
+ * @uids: (element-type utf8) (nullable): message uids to be filtered or
+ * %NULL (as a shortcut to filter all messages)
* @remove: TRUE to mark filtered messages as deleted
* @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
@@ -2171,12 +2171,12 @@ filter_driver_filter_message_internal (CamelFilterDriver *driver,
/**
* camel_filter_driver_filter_message:
* @driver: CamelFilterDriver
- * @message: message to filter or NULL
- * @info: message info or NULL
- * @uid: message uid or NULL
- * @source: source folder or NULL
- * @store_uid: UID of source store, or %NULL
- * @original_store_uid: UID of source store (pre-movemail), or %NULL
+ * @message: (nullable): message to filter or %NULL
+ * @info: (nullable): message info or %NULL
+ * @uid: (nullable): message uid or %NULL
+ * @source: (nullable): source folder or %NULL
+ * @store_uid: (nullable): UID of source store, or %NULL
+ * @original_store_uid: (nullable): UID of source store (pre-movemail), or %NULL
* @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
*
diff --git a/src/camel/camel-folder-search.c b/src/camel/camel-folder-search.c
index 319166651..f19866e6d 100644
--- a/src/camel/camel-folder-search.c
+++ b/src/camel/camel-folder-search.c
@@ -2390,9 +2390,9 @@ fail:
* Run a search. Search must have had Folder already set on it, and
* it must implement summaries.
*
- * Returns: (element-type utf8) (transfer full): a #GPtrArray with matching UIDs,
- * or %NULL on error. Use camel_folder_search_free_result() to free it when
- * no longer needed.
+ * Returns: (element-type utf8) (transfer full) (nullable): a #GPtrArray with
+ * matching UIDs, or %NULL on error. Use camel_folder_search_free_result()
+ * to free it when no longer needed.
**/
GPtrArray *
camel_folder_search_search (CamelFolderSearch *search,
diff --git a/src/camel/camel-folder-summary.c b/src/camel/camel-folder-summary.c
index 013b0b9d9..69aeb8717 100644
--- a/src/camel/camel-folder-summary.c
+++ b/src/camel/camel-folder-summary.c
@@ -1026,7 +1026,7 @@ camel_folder_summary_get_visible_count (CamelFolderSummary *summary)
/**
* camel_folder_summary_set_index:
* @summary: a #CamelFolderSummary object
- * @index: a #CamelIndex
+ * @index: (nullable): a #CamelIndex
*
* Set the index used to index body content. If the index is %NULL, or
* not set (the default), no indexing of body content will take place.
@@ -1050,7 +1050,7 @@ camel_folder_summary_set_index (CamelFolderSummary *summary,
* camel_folder_summary_get_index:
* @summary: a #CamelFolderSummary object
*
- * Returns: (transfer none): a #CamelIndex used to index body content.
+ * Returns: (transfer none) (nullable): a #CamelIndex used to index body content.
*
* Since: 3.4
**/
@@ -3394,7 +3394,7 @@ camel_system_flag_get (CamelMessageFlags flags,
/**
* camel_message_info_new_from_headers:
- * @summary: a #CamelFolderSummary object or %NULL
+ * @summary: (nullable): a #CamelFolderSummary object or %NULL
* @headers: a #CamelNameValueArray
*
* Create a new #CamelMessageInfo pre-populated with info from
diff --git a/src/camel/camel-folder.c b/src/camel/camel-folder.c
index f28b0300c..d0f8d1739 100644
--- a/src/camel/camel-folder.c
+++ b/src/camel/camel-folder.c
@@ -2317,9 +2317,9 @@ camel_folder_set_message_user_tag (CamelFolder *folder,
*
* Retrieve the #CamelMessageInfo for the specified @uid.
*
- * Returns: (transfer full): The summary information for the indicated message, or %NULL
- * if the uid does not exist. Free the returned object with g_object_unref(),
- * when done with it.
+ * Returns: (transfer full) (nullable): The summary information for the
+ * indicated message, or %NULL if the uid does not exist. Free the returned
+ * object with g_object_unref(), when done with it.
**/
CamelMessageInfo *
camel_folder_get_message_info (CamelFolder *folder,
@@ -3662,7 +3662,7 @@ camel_folder_get_message_finish (CamelFolder *folder,
* If quotas are not supported for @folder, the function returns %NULL
* and sets @error to #G_IO_ERROR_NOT_SUPPORTED.
*
- * Returns: a #CamelFolderQuotaInfo, or %NULL
+ * Returns: (nullable): a #CamelFolderQuotaInfo, or %NULL
*
* Since: 3.2
**/
@@ -3769,7 +3769,7 @@ camel_folder_get_quota_info (CamelFolder *folder,
* If quotas are not supported for @folder, the function returns %NULL
* and sets @error to #G_IO_ERROR_NOT_SUPPORTED.
*
- * Returns: a #CamelFolderQuotaInfo, or %NULL
+ * Returns: (nullable): a #CamelFolderQuotaInfo, or %NULL
*
* Since: 3.2
**/
diff --git a/src/camel/camel-internet-address.c b/src/camel/camel-internet-address.c
index bfb7e4ab6..659aae0b7 100644
--- a/src/camel/camel-internet-address.c
+++ b/src/camel/camel-internet-address.c
@@ -588,7 +588,7 @@ append:
/**
* camel_internet_address_encode_address:
- * @len: the length of the line the address is being appended to
+ * @len: (nullable): the length of the line the address is being appended to
* @name: the unencoded real name associated with the address
* @addr: the routing address
*
diff --git a/src/camel/camel-message-info.c b/src/camel/camel-message-info.c
index 0cc450390..fabc73fb3 100644
--- a/src/camel/camel-message-info.c
+++ b/src/camel/camel-message-info.c
@@ -689,7 +689,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
object_class->finalize = message_info_finalize;
/**
- * CamelMessageInfo:summary
+ * CamelMessageInfo:summary:
*
* The #CamelFolderSummary to which the message info belongs, or %NULL.
* It can be set only during construction of the object.
@@ -709,7 +709,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:uid
+ * CamelMessageInfo:uid:
*
* A unique ID of the message in its folder.
*
@@ -728,7 +728,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:dirty
+ * CamelMessageInfo:dirty:
*
* Flag, whether the info is changed and requires save to disk.
* Compare with CamelMessageInfo:folder-flagged
@@ -748,7 +748,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:folder-flagged
+ * CamelMessageInfo:folder-flagged:
*
* Flag, whether the info is changed and requires save to
* the destination store/server. This is different from
@@ -770,7 +770,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:folder-flagged-stamp
+ * CamelMessageInfo:folder-flagged-stamp:
*
* The 'folder-flagged-stamp' is a stamp of the 'folder-flagged' flag. This stamp
* changes whenever anything would mark the @mi 'folder-flagged', regardless the @mi
@@ -791,7 +791,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:abort-notifications
+ * CamelMessageInfo:abort-notifications:
*
* Flag, whether the info is currently aborting notifications. It is used to avoid
* unnecessary 'folder-flagged' and 'dirty' flags changes and also to avoid
@@ -812,7 +812,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:flags
+ * CamelMessageInfo:flags:
*
* Bit-or of #CamelMessageFlags.
*
@@ -832,7 +832,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:user-flags
+ * CamelMessageInfo:user-flags:
*
* User flags for the associated message. Can be %NULL.
* Unlike user-tags, which can contain various values, the user-flags
@@ -853,7 +853,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:user-tags
+ * CamelMessageInfo:user-tags:
*
* User tags for the associated message. Can be %NULL.
* Unlike user-flags, which can be set or not, the user-tags
@@ -874,7 +874,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:subject
+ * CamelMessageInfo:subject:
*
* Subject of the associated message.
*
@@ -893,7 +893,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:from
+ * CamelMessageInfo:from:
*
* From address of the associated message.
*
@@ -912,7 +912,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:to
+ * CamelMessageInfo:to:
*
* To address of the associated message.
*
@@ -931,7 +931,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:cc
+ * CamelMessageInfo:cc:
*
* CC address of the associated message.
*
@@ -950,7 +950,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:mlist
+ * CamelMessageInfo:mlist:
*
* Mailing list address of the associated message.
*
@@ -969,7 +969,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:size
+ * CamelMessageInfo:size:
*
* Size of the associated message.
*
@@ -988,7 +988,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:date-sent
+ * CamelMessageInfo:date-sent:
*
* Sent Date of the associated message.
*
@@ -1007,7 +1007,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:date-received
+ * CamelMessageInfo:date-received:
*
* Received date of the associated message.
*
@@ -1026,7 +1026,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:message-id
+ * CamelMessageInfo:message-id:
*
* Encoded Message-ID of the associated message as a guint64 number,
* partial MD5 sum. The value can be cast to #CamelSummaryMessageID.
@@ -1046,7 +1046,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:references
+ * CamelMessageInfo:references:
*
* Encoded In-Reply-To and References headers of the associated message
* as an array of guint64 numbers, partial MD5 sums. Each value can be
@@ -1067,7 +1067,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:headers
+ * CamelMessageInfo:headers:
*
* Headers of the associated message. Can be %NULL.
*
@@ -1086,7 +1086,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:user-headers
+ * CamelMessageInfo:user-headers:
*
* User-defined headers of the associated message. Can be %NULL.
*
@@ -1105,7 +1105,7 @@ camel_message_info_class_init (CamelMessageInfoClass *class)
G_PARAM_STATIC_STRINGS));
/**
- * CamelMessageInfo:preview
+ * CamelMessageInfo:preview:
*
* Body preview of the associated message. Can be %NULL.
*
@@ -1295,8 +1295,9 @@ camel_message_info_save (const CamelMessageInfo *mi,
* camel_message_info_ref_summary:
* @mi: a #CamelMessageInfo
*
- * Returns: (transfer full): Referenced #CamelFolderSummary to which the @mi belongs, or %NULL,
- * if there is none. Use g_object_unref() for non-NULL returned values when done with it.
+ * Returns: (transfer full) (nullable): Referenced #CamelFolderSummary to which
+ * the @mi belongs, or %NULL, if there is none. Use g_object_unref() for
+ * non-NULL returned values when done with it.
*
* Since: 3.24
**/
@@ -1978,9 +1979,9 @@ camel_message_info_get_user_flags (const CamelMessageInfo *mi)
* camel_message_info_dup_user_flags:
* @mi: a #CamelMessageInfo
*
- * Returns: (transfer full): A newly allocated #CamelNamedFlags with all the currently set
- * user flags on the @mi. Free the returned structure with camel_named_flags_free()
- * when no londer needed.
+ * Returns: (transfer full) (nullable): A newly allocated #CamelNamedFlags with
+ * all the currently set user flags on the @mi. Free the returned structure
+ * with camel_named_flags_free() when no londer needed.
*
* Since: 3.24
**/
diff --git a/src/camel/camel-mime-parser.c b/src/camel/camel-mime-parser.c
index f7fb2ee2f..b1d0c30dd 100644
--- a/src/camel/camel-mime-parser.c
+++ b/src/camel/camel-mime-parser.c
@@ -322,7 +322,7 @@ camel_mime_parser_filter_remove (CamelMimeParser *m,
*
* Lookup a header by name.
*
- * Returns: The header value, or NULL if the header is not
+ * Returns: (nullable): The header value, or %NULL if the header is not
* defined.
**/
const gchar *
@@ -346,8 +346,9 @@ camel_mime_parser_header (CamelMimeParser *m,
* current state of the parser. These headers are valid
* until the next call to camel_mime_parser_step(), or camel_mime_parser_drop_step().
*
- * Returns: (transfer full): The headers, or %NULL, if there are no headers
- * defined for the current part or state. Free it with camel_name_value_array_free().
+ * Returns: (transfer full) (nullable): The headers, or %NULL, if there are no
+ * headers defined for the current part or state. Free it with
+ * camel_name_value_array_free().
*
* Since: 3.24
**/
@@ -388,7 +389,7 @@ byte_array_to_string (GByteArray *array)
* Retrieve the preface text for the current multipart.
* Can only be used when the state is CAMEL_MIME_PARSER_STATE_MULTIPART_END.
*
- * Returns: The preface text, or NULL if there wasn't any.
+ * Returns: (nullable): The preface text, or %NULL if there wasn't any.
*
* Since: 2.22
**/
@@ -411,7 +412,7 @@ camel_mime_parser_preface (CamelMimeParser *m)
* Only returns valid data when the current state if
* CAMEL_MIME_PARSER_STATE_MULTIPART_END.
*
- * Returns: The postface text, or NULL if there wasn't any.
+ * Returns: (nullable): The postface text, or %NULL if there wasn't any.
*
* Since: 2.22
**/
@@ -437,7 +438,7 @@ camel_mime_parser_postface (CamelMimeParser *m)
* The return value will remain valid while in the CAMEL_MIME_PARSER_STATE_FROM
* state, or any deeper state.
*
- * Returns: The From line, or NULL if called out of context.
+ * Returns: (nullable): The From line, or %NULL if called out of context.
*
* Since: 2.22
**/
@@ -590,7 +591,7 @@ camel_mime_parser_scan_pre_from (CamelMimeParser *parser,
*
* Get the content type defined in the current part.
*
- * Returns: A content_type structure, or NULL if there
+ * Returns: (nullable): A content_type structure, or %NULL if there
* is no content-type defined for this part of state of the
* parser.
**/
diff --git a/src/camel/camel-mime-part-utils.c b/src/camel/camel-mime-part-utils.c
index 81265fe91..9bec30373 100644
--- a/src/camel/camel-mime-part-utils.c
+++ b/src/camel/camel-mime-part-utils.c
@@ -180,7 +180,7 @@ camel_message_content_info_new (void)
* camel_message_content_info_copy:
* @src: (nullable): a source #CamelMessageContentInfo to copy
*
- * Returns: a copy of @src, or %NULL, if @src was %NULL
+ * Returns: (nullable): a copy of @src, or %NULL, if @src was %NULL
*
* Since: 3.24
**/
diff --git a/src/camel/camel-mime-utils.c b/src/camel/camel-mime-utils.c
index bafba10fc..a3b860af6 100644
--- a/src/camel/camel-mime-utils.c
+++ b/src/camel/camel-mime-utils.c
@@ -2520,7 +2520,7 @@ camel_content_type_set_param (CamelContentType *t,
/**
* camel_content_type_is:
- * @content_type: A content type specifier, or %NULL.
+ * @content_type: (nullable): A content type specifier, or %NULL.
* @type: A type to check against.
* @subtype: A subtype to check against, or "*" to match any subtype.
*
@@ -4697,10 +4697,10 @@ camel_header_location_decode (const gchar *in)
/**
* camel_header_msgid_generate:
- * @domain: domain to use (like "example.com") for the ID suffix; can be NULL
+ * @domain: (nullable): domain to use (like "example.com") for the ID suffix; can be %NULL
*
* Either the @domain is used, or the user's local hostname,
- * in case it's NULL or empty.
+ * in case it's %NULL or empty.
*
* Returns: Unique message ID.
**/
diff --git a/src/camel/camel-multipart.c b/src/camel/camel-multipart.c
index 288d600f0..31a7b4f21 100644
--- a/src/camel/camel-multipart.c
+++ b/src/camel/camel-multipart.c
@@ -452,7 +452,7 @@ camel_multipart_add_part (CamelMultipart *multipart,
* @multipart: a #CamelMultipart object
* @index: a zero-based index indicating the part to get
*
- * Returns: (transfer none): the indicated subpart, or %NULL
+ * Returns: (transfer none) (nullable): the indicated subpart, or %NULL
**/
CamelMimePart *
camel_multipart_get_part (CamelMultipart *multipart,
diff --git a/src/camel/camel-network-service.c b/src/camel/camel-network-service.c
index 383045021..5203a11ea 100644
--- a/src/camel/camel-network-service.c
+++ b/src/camel/camel-network-service.c
@@ -742,7 +742,8 @@ camel_network_service_init (CamelNetworkService *service)
* name for unencrypted IMAP or encrypted IMAP using STARTTLS is "imap",
* but the service name for IMAP over SSL is "imaps".
*
- * Returns: the network service name for @service and @method, or %NULL
+ * Returns: (nullable): the network service name for @service and @method,
+ * or %NULL
*
* Since: 3.2
**/
@@ -843,7 +844,7 @@ camel_network_service_ref_connectable (CamelNetworkService *service)
/**
* camel_network_service_set_connectable:
* @service: a #CamelNetworkService
- * @connectable: a #GSocketConnectable, or %NULL
+ * @connectable: (nullable): a #GSocketConnectable, or %NULL
*
* Sets the socket endpoint for the network service to which @service is
* a client. If @connectable is %NULL, a #GSocketConnectable is derived
@@ -923,7 +924,7 @@ camel_network_service_get_host_reachable (CamelNetworkService *service)
* connection attempt is cancelled, the function sets @error and returns
* %NULL.
*
- * Returns: (transfer full): a #GIOStream, or %NULL
+ * Returns: (transfer full) (nullable): a #GIOStream, or %NULL
*
* Since: 3.2
**/
@@ -955,7 +956,8 @@ camel_network_service_connect_sync (CamelNetworkService *service,
* This should typically be called after issuing a STARTTLS command
* to a server to initiate a Transport Layer Security handshake.
*
- * Returns: (transfer full): the new #GTlsClientConnection, or %NULL on error
+ * Returns: (transfer full) (nullable): the new #GTlsClientConnection,
+ * or %NULL on error
*
* Since: 3.12
**/
diff --git a/src/camel/camel-network-settings.c b/src/camel/camel-network-settings.c
index 326e3bdc7..1cc35cb20 100644
--- a/src/camel/camel-network-settings.c
+++ b/src/camel/camel-network-settings.c
@@ -104,7 +104,7 @@ camel_network_settings_default_init (CamelNetworkSettingsInterface *iface)
* Returns the mechanism name used to authenticate to a network service.
* Often this refers to a SASL mechanism such as "LOGIN" or "GSSAPI".
*
- * Returns: the authentication mechanism name
+ * Returns: (nullable): the authentication mechanism name
*
* Since: 3.4
**/
@@ -125,7 +125,7 @@ camel_network_settings_get_auth_mechanism (CamelNetworkSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelNetworkSettings:auth-mechanism
+ * Returns: (nullable): a newly-allocated copy of #CamelNetworkSettings:auth-mechanism
*
* Since: 3.4
**/
@@ -150,7 +150,7 @@ camel_network_settings_dup_auth_mechanism (CamelNetworkSettings *settings)
/**
* camel_network_settings_set_auth_mechanism:
* @settings: a #CamelNetworkSettings
- * @auth_mechanism: an authentication mechanism name, or %NULL
+ * @auth_mechanism: (nullable): an authentication mechanism name, or %NULL
*
* Sets the mechanism name used to authenticate to a network service.
* Often this refers to a SASL mechanism such as "LOGIN" or "GSSAPI".
@@ -271,7 +271,7 @@ camel_network_settings_dup_host_ensure_ascii (CamelNetworkSettings *settings)
/**
* camel_network_settings_set_host:
* @settings: a #CamelNetworkSettings
- * @host: a host name, or %NULL
+ * @host: (nullable): a host name, or %NULL
*
* Sets the host name used to authenticate to a network service. The
* #CamelNetworkSettings:host property is automatically stripped of
@@ -452,7 +452,7 @@ camel_network_settings_dup_user (CamelNetworkSettings *settings)
/**
* camel_network_settings_set_user:
* @settings: a #CamelNetworkSettings
- * @user: a user name, or %NULL
+ * @user: (nullable): a user name, or %NULL
*
* Sets the user name used to authenticate to a network service. The
* #CamelNetworkSettings:user property is automatically stripped of
diff --git a/src/camel/camel-offline-folder.c b/src/camel/camel-offline-folder.c
index 270fd18b3..5b7a88731 100644
--- a/src/camel/camel-offline-folder.c
+++ b/src/camel/camel-offline-folder.c
@@ -582,7 +582,7 @@ camel_offline_folder_can_downsync (CamelOfflineFolder *folder)
/**
* camel_offline_folder_downsync_sync:
* @folder: a #CamelOfflineFolder
- * @expression: search expression describing which set of messages
+ * @expression: (nullable): search expression describing which set of messages
* to downsync (%NULL for all)
* @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
@@ -644,7 +644,7 @@ offline_folder_downsync_thread (GTask *task,
/**
* camel_offline_folder_downsync:
* @folder: a #CamelOfflineFolder
- * @expression: search expression describing which set of messages
+ * @expression: (nullable): search expression describing which set of messages
* to downsync (%NULL for all)
* @io_priority: the I/O priority of the request
* @cancellable: optional #GCancellable object, or %NULL
diff --git a/src/camel/camel-provider.c b/src/camel/camel-provider.c
index 915c65f87..9f2ad3879 100644
--- a/src/camel/camel-provider.c
+++ b/src/camel/camel-provider.c
@@ -466,7 +466,7 @@ camel_provider_list (gboolean load)
* The returned #CamelProvider is owned by Camel and should not be
* modified or freed.
*
- * Returns: a #CamelProvider for @protocol, or %NULL
+ * Returns: (nullable): a #CamelProvider for @protocol, or %NULL
**/
CamelProvider *
camel_provider_get (const gchar *protocol,
diff --git a/src/camel/camel-sasl.c b/src/camel/camel-sasl.c
index b3da1df3b..8882693df 100644
--- a/src/camel/camel-sasl.c
+++ b/src/camel/camel-sasl.c
@@ -575,7 +575,7 @@ camel_sasl_get_service_name (CamelSasl *sasl)
/**
* camel_sasl_challenge_sync:
* @sasl: a #CamelSasl
- * @token: a token, or %NULL
+ * @token: (nullable): a token, or %NULL
* @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
*
@@ -586,8 +586,8 @@ camel_sasl_get_service_name (CamelSasl *sasl)
*
* Free the returned #GByteArray with g_byte_array_free().
*
- * Returns: (transfer full): the SASL response or %NULL. If an error occurred, @error will
- * also be set.
+ * Returns: (transfer full) (nullable): the SASL response or %NULL. If an error
+ * occurred, @error will also be set.
**/
GByteArray *
camel_sasl_challenge_sync (CamelSasl *sasl,
@@ -643,7 +643,7 @@ sasl_challenge_thread (GTask *task,
/**
* camel_sasl_challenge:
* @sasl: a #CamelSasl
- * @token: a token, or %NULL
+ * @token: (nullable): a token, or %NULL
* @io_priority: the I/O priority of the request
* @cancellable: optional #GCancellable object, or %NULL
* @callback: a #GAsyncReadyCallback to call when the request is satisfied
@@ -699,8 +699,8 @@ camel_sasl_challenge (CamelSasl *sasl,
* Finishes the operation started with camel_sasl_challenge(). Free the
* returned #GByteArray with g_byte_array_free().
*
- * Returns: (transfer full): the SASL response or %NULL. If an error occurred, @error will
- * also be set.
+ * Returns: (transfer full) (nullable): the SASL response or %NULL. If an
+ * error occurred, @error will also be set.
*
* Since: 3.0
**/
diff --git a/src/camel/camel-search-sql-sexp.c b/src/camel/camel-search-sql-sexp.c
index 288aab7ab..c6a79825f 100644
--- a/src/camel/camel-search-sql-sexp.c
+++ b/src/camel/camel-search-sql-sexp.c
@@ -831,8 +831,9 @@ static struct {
* Converts a search expression to an SQL 'WHERE' part statement,
* without the 'WHERE' keyword.
*
- * Returns: (transfer full): a newly allocated string, an SQL 'WHERE' part statement,
- * or %NULL, when could not convert it. Free it with g_free(), when done with it.
+ * Returns: (transfer full) (nullable): a newly allocated string, an SQL
+ * 'WHERE' part statement, or %NULL, when could not convert it. Free it with
+ * g_free(), when done with it.
*
* Since: 2.26
**/
diff --git a/src/camel/camel-service.c b/src/camel/camel-service.c
index 650b5b284..bd8ba1606 100644
--- a/src/camel/camel-service.c
+++ b/src/camel/camel-service.c
@@ -1210,7 +1210,7 @@ camel_service_get_connection_status (CamelService *service)
* Compare this with camel_service_get_name(), which returns a built-in
* description of the type of service (IMAP, SMTP, etc.).
*
- * Returns: the display name for @service, or %NULL
+ * Returns: (nullable): the display name for @service, or %NULL
*
* Since: 3.2
**/
@@ -1231,7 +1231,7 @@ camel_service_get_display_name (CamelService *service)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelService:display-name
+ * Returns: (nullable): a newly-allocated copy of #CamelService:display-name
*
* Since: 3.12
**/
@@ -1256,7 +1256,7 @@ camel_service_dup_display_name (CamelService *service)
/**
* camel_service_set_display_name:
* @service: a #CamelService
- * @display_name: a valid UTF-8 string, or %NULL
+ * @display_name: (nullable): a valid UTF-8 string, or %NULL
*
* Assigns a UTF-8 display name to @service. The display name is intended
* for use in a user interface and should generally be given a user-defined
@@ -1469,7 +1469,7 @@ camel_service_get_provider (CamelService *service)
* The returned #GProxyResolver is referenced for thread-safety and must
* be unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): a #GProxyResolver, or %NULL
+ * Returns: (transfer full) (nullable): a #GProxyResolver, or %NULL
*
* Since: 3.12
**/
@@ -1493,7 +1493,7 @@ camel_service_ref_proxy_resolver (CamelService *service)
/**
* camel_service_set_proxy_resolver:
* @service: a #CamelService
- * @proxy_resolver: a #GProxyResolver, or %NULL for the default
+ * @proxy_resolver: (nullable): a #GProxyResolver, or %NULL for the default
*
* Sets the #GProxyResolver for @service. If an application needs to
* override this, it should do so prior to calling functions on @service
@@ -1591,7 +1591,7 @@ camel_service_ref_settings (CamelService *service)
/**
* camel_service_set_settings:
* @service: a #CamelService
- * @settings: an instance derviced from #CamelSettings, or %NULL
+ * @settings: (nullable): an instance derviced from #CamelSettings, or %NULL
*
* Associates a new #CamelSettings instance with the service.
* The @settings instance must match the settings type defined in
diff --git a/src/camel/camel-session.c b/src/camel/camel-session.c
index 688dc2a71..883134142 100644
--- a/src/camel/camel-session.c
+++ b/src/camel/camel-session.c
@@ -896,7 +896,7 @@ camel_session_ref_network_monitor (CamelSession *session)
* The returned #CamelService is referenced for thread-safety and must be
* unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): a #CamelService instance, or %NULL
+ * Returns: (transfer full) (nullable): a #CamelService instance, or %NULL
*
* Since: 3.2
**/
@@ -960,7 +960,7 @@ camel_session_remove_service (CamelSession *session,
* The returned #CamelService is referenced for thread-safety and must be
* unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): a #CamelService instance, or %NULL
+ * Returns: (transfer full) (nullable): a #CamelService instance, or %NULL
*
* Since: 3.6
**/
@@ -1001,7 +1001,7 @@ camel_session_ref_service (CamelSession *session,
*
* Note this function is significantly slower than camel_session_ref_service().
*
- * Returns: (transfer full): a #CamelService instance, or %NULL
+ * Returns: (transfer full) (nullable): a #CamelService instance, or %NULL
*
* Since: 3.6
**/
@@ -1155,7 +1155,7 @@ camel_session_remove_services (CamelSession *session)
* the user did not provide the information. The caller must g_free()
* the information returned when it is done with it.
*
- * Returns: the authentication information or %NULL
+ * Returns: (nullable): the authentication information or %NULL
**/
gchar *
camel_session_get_password (CamelSession *session,
@@ -1471,7 +1471,7 @@ camel_session_get_filter_driver (CamelSession *session,
* must implement the interface and install a #CamelJunkFilter instance for
* junk filtering to take place.
*
- * Returns: (transfer none): a #CamelJunkFilter, or %NULL
+ * Returns: (transfer none) (nullable): a #CamelJunkFilter, or %NULL
*
* Since: 3.2
**/
@@ -1486,7 +1486,7 @@ camel_session_get_junk_filter (CamelSession *session)
/**
* camel_session_set_junk_filter:
* @session: a #CamelSession
- * @junk_filter: a #CamelJunkFilter, or %NULL
+ * @junk_filter: (nullable): a #CamelJunkFilter, or %NULL
*
* Installs the #CamelJunkFilter instance used to classify messages as
* junk or not junk during filtering.
diff --git a/src/camel/camel-store-summary.c b/src/camel/camel-store-summary.c
index 7938f4e58..b5db33622 100644
--- a/src/camel/camel-store-summary.c
+++ b/src/camel/camel-store-summary.c
@@ -400,7 +400,7 @@ camel_store_summary_array_free (CamelStoreSummary *summary,
* The returned #CamelStoreInfo is referenced for thread-safety and should be
* unreferenced with camel_store_summary_info_unref() when finished with it.
*
- * Returns: the summary item, or %NULL if the @path name is not
+ * Returns: (nullable): the summary item, or %NULL if the @path name is not
* available
**/
CamelStoreInfo *
diff --git a/src/camel/camel-stream-fs.c b/src/camel/camel-stream-fs.c
index c64601659..656c4bbad 100644
--- a/src/camel/camel-stream-fs.c
+++ b/src/camel/camel-stream-fs.c
@@ -304,7 +304,7 @@ camel_stream_fs_new_with_fd (gint fd)
* Creates a new #CamelStreamFs corresponding to the named file, flags,
* and mode.
*
- * Returns: the new stream, or %NULL on error.
+ * Returns: (nullable): the new stream, or %NULL on error.
**/
CamelStream *
camel_stream_fs_new_with_name (const gchar *name,
diff --git a/src/camel/camel-string-utils.c b/src/camel/camel-string-utils.c
index 2dfcdf23d..11b215fbb 100644
--- a/src/camel/camel-string-utils.c
+++ b/src/camel/camel-string-utils.c
@@ -143,7 +143,7 @@ string_pool_init (void)
/**
* camel_pstring_add:
- * @string: string to add to the string pool
+ * @string: (nullable): string to add to the string pool
* @own: whether the string pool will own the memory pointed to by
* @string, if @string is not yet in the pool
*
@@ -153,7 +153,7 @@ string_pool_init (void)
*
* Unreference the returned string with camel_pstring_free().
*
- * Returns: a canonicalized copy of @string
+ * Returns: (nullable): a canonicalized copy of @string
**/
const gchar *
camel_pstring_add (gchar *string,
@@ -198,7 +198,7 @@ camel_pstring_add (gchar *string,
/**
* camel_pstring_peek:
- * @string: string to fetch from the string pool
+ * @string: (nullable): string to fetch from the string pool
*
* Returns the canonicalized copy of @string without increasing its
* reference count in the string pool. If necessary, @string is first
@@ -206,7 +206,7 @@ camel_pstring_add (gchar *string,
*
* The %NULL and empty strings are special cased to constant values.
*
- * Returns: a canonicalized copy of @string
+ * Returns: (nullable): a canonicalized copy of @string
*
* Since: 2.24
**/
@@ -243,7 +243,7 @@ camel_pstring_peek (const gchar *string)
/**
* camel_pstring_contains:
- * @string: string to look up in the string pool
+ * @string: (nullable): string to look up in the string pool
*
* Returns whether the @string exists in the string pool.
*
@@ -278,7 +278,7 @@ camel_pstring_contains (const gchar *string)
/**
* camel_pstring_strdup:
- * @string: string to copy
+ * @string: (nullable): string to copy
*
* Create a new pooled string entry for @strings. A pooled string
* is a table where common strings are canonicalized. They are also
@@ -288,7 +288,7 @@ camel_pstring_contains (const gchar *string)
*
* Unreference the returned string with camel_pstring_free().
*
- * Returns: a canonicalized copy of @string
+ * Returns: (nullable): a canonicalized copy of @string
**/
const gchar *
camel_pstring_strdup (const gchar *string)
@@ -298,7 +298,7 @@ camel_pstring_strdup (const gchar *string)
/**
* camel_pstring_free:
- * @string: string to free
+ * @string: (nullable): string to free
*
* Unreferences a pooled string. If the string's reference count drops to
* zero it will be deallocated. %NULL and the empty string are special cased.
diff --git a/src/camel/camel-uid-cache.c b/src/camel/camel-uid-cache.c
index 6e4167f46..c839b5297 100644
--- a/src/camel/camel-uid-cache.c
+++ b/src/camel/camel-uid-cache.c
@@ -45,7 +45,7 @@ struct _uid_state {
* doesn't already exist, the UID cache will be empty. Otherwise, if
* it does exist but can't be read, the function will return %NULL.
*
- * Returns: a new UID cache, or %NULL
+ * Returns: (nullable): a new UID cache, or %NULL
**/
CamelUIDCache *
camel_uid_cache_new (const gchar *filename)
diff --git a/src/camel/camel-url.c b/src/camel/camel-url.c
index 49dfe786a..15a40df0b 100644
--- a/src/camel/camel-url.c
+++ b/src/camel/camel-url.c
@@ -305,7 +305,7 @@ copy_param (GQuark key_id,
*
* Parses an absolute URL.
*
- * Returns: a #CamelURL if it can be parsed, or %NULL otherwise
+ * Returns: (nullable): a #CamelURL if it can be parsed, or %NULL otherwise
**/
CamelURL *
camel_url_new (const gchar *url_string,
@@ -597,7 +597,7 @@ camel_url_set_param (CamelURL *url,
*
* Get the value of the specified param on the URL.
*
- * Returns: the value of a param if found or %NULL otherwise
+ * Returns: (nullable): the value of a param if found or %NULL otherwise
**/
const gchar *
camel_url_get_param (CamelURL *url,
@@ -647,7 +647,7 @@ append_url_encoded (GString *str,
/**
* camel_url_encode:
* @part: a URL part
- * @escape_extra: additional characters beyond " \"%#<>{}|\^[]`"
+ * @escape_extra: (nullable): additional characters beyond " \"%#<>{}|\^[]`"
* to escape (or %NULL)
*
* This %-encodes the given URL part and returns the escaped version
diff --git a/src/camel/camel-vee-store.c b/src/camel/camel-vee-store.c
index 3723dd965..bd57f7dc9 100644
--- a/src/camel/camel-vee-store.c
+++ b/src/camel/camel-vee-store.c
@@ -605,8 +605,8 @@ camel_vee_store_get_vee_data_cache (CamelVeeStore *vstore)
* camel_vee_store_get_unmatched_folder:
* @vstore: a #CamelVeeStore
*
- * Returns: (transfer none): the Unmatched folder instance, or %NULL,
- * when it's disabled.
+ * Returns: (transfer none) (nullable): the Unmatched folder instance,
+ * or %NULL, when it's disabled.
*
* Since: 3.6
**/
diff --git a/src/camel/camel-weak-ref-group.c b/src/camel/camel-weak-ref-group.c
index 0194d1c5d..2f4a0530f 100644
--- a/src/camel/camel-weak-ref-group.c
+++ b/src/camel/camel-weak-ref-group.c
@@ -205,8 +205,8 @@ camel_weak_ref_group_set (CamelWeakRefGroup *group,
* camel_weak_ref_group_get:
* @group: a #CamelWeakRefGroup
*
- * Returns: (transfer full): A referenced object associated with @group,
- * or %NULL, when no object had been set to it. Use g_object_unref()
+ * Returns: (transfer full) (nullable): A referenced object associated with
+ * @group, or %NULL, when no object had been set to it. Use g_object_unref()
* to free it, when no longer needed.
*
* Since: 3.24
diff --git a/src/camel/camel.c b/src/camel/camel.c
index 3fbc17c9a..f6d820156 100644
--- a/src/camel/camel.c
+++ b/src/camel/camel.c
@@ -322,8 +322,8 @@ camel_binding_bind_property (gpointer source,
* from the @source to the @target, or %NULL to use the default
* @transform_from: (scope notified) (nullable): the transformation function
* from the @target to the @source, or %NULL to use the default
- * @user_data: custom data to be passed to the transformation functions,
- * or %NULL
+ * @user_data: (nullable): custom data to be passed to the transformation
+ * functions, or %NULL
* @notify: function to be called when disposing the binding, to free the
* resources used by the transformation functions
*
diff --git a/src/camel/providers/imapx/camel-imapx-folder.c b/src/camel/providers/imapx/camel-imapx-folder.c
index 793e4d175..2f9819378 100644
--- a/src/camel/providers/imapx/camel-imapx-folder.c
+++ b/src/camel/providers/imapx/camel-imapx-folder.c
@@ -1322,7 +1322,7 @@ camel_imapx_folder_new (CamelStore *store,
* The returned #CamelIMAPXMailbox is referenced for thread-safety and
* should be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #CamelIMAPXMailbox, or %NULL
+ * Returns: (nullable): a #CamelIMAPXMailbox, or %NULL
*
* Since: 3.12
**/
@@ -1384,7 +1384,7 @@ camel_imapx_folder_set_mailbox (CamelIMAPXFolder *folder,
* The returned #CamelIMAPXMailbox is referenced for thread-safety and
* should be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #CamelIMAPXMailbox, or %NULL
+ * Returns: (nullable): a #CamelIMAPXMailbox, or %NULL
*
* Since: 3.12
**/
diff --git a/src/camel/providers/imapx/camel-imapx-list-response.c
b/src/camel/providers/imapx/camel-imapx-list-response.c
index c0eb4b51d..e1ed35534 100644
--- a/src/camel/providers/imapx/camel-imapx-list-response.c
+++ b/src/camel/providers/imapx/camel-imapx-list-response.c
@@ -292,7 +292,7 @@ imapx_list_response_parse_extended_item (CamelIMAPXInputStream *stream,
* stores the response data in a new #CamelIMAPXListResponse. If an error
* occurs, the function sets @error and returns %NULL.
*
- * Returns: a #CamelIMAPXListResponse, or %NULL
+ * Returns: (nullable): a #CamelIMAPXListResponse, or %NULL
*
* Since: 3.10
**/
@@ -783,7 +783,7 @@ camel_imapx_list_response_dup_attributes (CamelIMAPXListResponse *response)
* The returned #GVariant is referenced for thread-safety and should
* be unreferenced with g_variant_unref() when finished with it.
*
- * Returns: a #GVariant, or %NULL
+ * Returns: (nullable): a #GVariant, or %NULL
*
* Since: 3.10
**/
@@ -815,7 +815,7 @@ camel_imapx_list_response_ref_extended_item (CamelIMAPXListResponse *response,
* renamed. See <ulink url="http://tools.ietf.org/html/rfc5465#section-5.4";>
* RFC 5465 Section 5.4</ulink> for further details.
*
- * Returns: the old mailbox name, or %NULL
+ * Returns: (nullable): the old mailbox name, or %NULL
*
* Since: 3.12
**/
diff --git a/src/camel/providers/imapx/camel-imapx-mailbox.c b/src/camel/providers/imapx/camel-imapx-mailbox.c
index dbf9740cd..34708edbb 100644
--- a/src/camel/providers/imapx/camel-imapx-mailbox.c
+++ b/src/camel/providers/imapx/camel-imapx-mailbox.c
@@ -796,7 +796,7 @@ camel_imapx_mailbox_set_permanentflags (CamelIMAPXMailbox *mailbox,
* The returned newly-allocated, %NULL-terminated string array should
* be freed with g_strfreev() when finished with it.
*
- * Returns: the last known "QUOTAROOT" value
+ * Returns: (nullable): the last known "QUOTAROOT" value
*
* Since: 3.12
**/
@@ -920,7 +920,7 @@ camel_imapx_mailbox_take_message_map (CamelIMAPXMailbox *mailbox,
* camel_imapx_mailbox_get_msn_for_uid:
* @mailbox: a #CamelIMAPXMailbox
* @uid: a message's unique identifier
- * @out_msn: return location for the message's sequence number, or %NULL
+ * @out_msn: (nullable): return location for the message's sequence number, or %NULL
*
* Given a message's unique identifier (@uid), write the message's sequence
* number to @out_msn and return %TRUE. If the unique identifier is unknown
diff --git a/src/camel/providers/imapx/camel-imapx-namespace-response.c
b/src/camel/providers/imapx/camel-imapx-namespace-response.c
index f935187f1..0038e6a95 100644
--- a/src/camel/providers/imapx/camel-imapx-namespace-response.c
+++ b/src/camel/providers/imapx/camel-imapx-namespace-response.c
@@ -196,7 +196,7 @@ repeat:
* successful, stores the response data in a new #CamelIMAPXNamespaceResponse.
* If an error occurs, the function sets @error and returns %NULL.
*
- * Returns: a #CamelIMAPXNamespaceResponse, or %NULL
+ * Returns: (nullable): a #CamelIMAPXNamespaceResponse, or %NULL
*
* Since: 3.12
**/
@@ -380,7 +380,7 @@ camel_imapx_namespace_response_remove (CamelIMAPXNamespaceResponse *response,
* The returned #CamelIMAPXNamespace is referenced for thread-safety and
* should be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #CamelIMAPXNamespace, or %NULL
+ * Returns: (nullable): a #CamelIMAPXNamespace, or %NULL
*
* Since: 3.12
**/
@@ -507,7 +507,7 @@ imapx_namespace_response_rank_candidates (gconstpointer a,
* The returned #CamelIMAPXNamespace is referenced for thread-safety and
* should be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #CamelIMAPXNamespace, or %NULL
+ * Returns: (nullable): a #CamelIMAPXNamespace, or %NULL
*
* Since: 3.12
**/
diff --git a/src/camel/providers/imapx/camel-imapx-search.c b/src/camel/providers/imapx/camel-imapx-search.c
index 2a34b389c..180822293 100644
--- a/src/camel/providers/imapx/camel-imapx-search.c
+++ b/src/camel/providers/imapx/camel-imapx-search.c
@@ -680,7 +680,7 @@ camel_imapx_search_new (CamelIMAPXStore *imapx_store)
* The returned #CamelIMAPXStore is referenced for thread-safety and
* must be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #CamelIMAPXStore, or %NULL
+ * Returns: (nullable): a #CamelIMAPXStore, or %NULL
*
* Since: 3.8
**/
@@ -721,7 +721,7 @@ camel_imapx_search_ref_store (CamelIMAPXSearch *search)
/**
* camel_imapx_search_set_store:
* @search: a #CamelIMAPXSearch
- * @imapx_store: a #CamelIMAPXStore, or %NULL
+ * @imapx_store: (nullable): a #CamelIMAPXStore, or %NULL
*
* Sets a #CamelIMAPXStore to use for server-side searches. Generally
* this is set for the duration of a single search when online, and then
diff --git a/src/camel/providers/imapx/camel-imapx-server.c b/src/camel/providers/imapx/camel-imapx-server.c
index 2d0193657..74f947fec 100644
--- a/src/camel/providers/imapx/camel-imapx-server.c
+++ b/src/camel/providers/imapx/camel-imapx-server.c
@@ -3855,7 +3855,7 @@ camel_imapx_server_ref_settings (CamelIMAPXServer *server)
* The returned #GInputStream is referenced for thread-safety and must
* be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #GInputStream, or %NULL
+ * Returns: (nullable): a #GInputStream, or %NULL
*
* Since: 3.12
**/
@@ -3887,7 +3887,7 @@ camel_imapx_server_ref_input_stream (CamelIMAPXServer *is)
* The returned #GOutputStream is referenced for thread-safety and must
* be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #GOutputStream, or %NULL
+ * Returns: (nullable): a #GOutputStream, or %NULL
*
* Since: 3.12
**/
@@ -3920,7 +3920,7 @@ camel_imapx_server_ref_output_stream (CamelIMAPXServer *is)
* The returned #CamelIMAPXMailbox is reference for thread-safety and
* should be unreferenced with g_object_unref() when finished with it.
*
- * Returns: a #CamelIMAPXMailbox, or %NULL
+ * Returns: (nullable): a #CamelIMAPXMailbox, or %NULL
*
* Since: 3.12
**/
@@ -7375,7 +7375,7 @@ camel_imapx_server_stop_idle_sync (CamelIMAPXServer *is,
* untagged response code. Must be
* all-uppercase with underscores allowed
* (see RFC 3501)
- * @desc: a #CamelIMAPXUntaggedRespHandlerDesc handler description
+ * @desc: (nullable): a #CamelIMAPXUntaggedRespHandlerDesc handler description
* structure. The descriptor structure is expected to
* remain stable over the lifetime of the #CamelIMAPXServer
* instance it was registered with. It is the responsibility
@@ -7389,7 +7389,7 @@ camel_imapx_server_stop_idle_sync (CamelIMAPXServer *is,
* code is implemented with just some new code to be run before
* or after the original handler code
*
- * Returns: the #CamelIMAPXUntaggedRespHandlerDesc previously
+ * Returns: (nullable): the #CamelIMAPXUntaggedRespHandlerDesc previously
* registered for this untagged response, if any,
* NULL otherwise.
*
diff --git a/src/camel/providers/imapx/camel-imapx-server.h b/src/camel/providers/imapx/camel-imapx-server.h
index fb937b17c..c6e0b2537 100644
--- a/src/camel/providers/imapx/camel-imapx-server.h
+++ b/src/camel/providers/imapx/camel-imapx-server.h
@@ -78,7 +78,7 @@ typedef gboolean (* CamelIMAPXUntaggedRespHandler) (CamelIMAPXServer *server,
* all-uppercase with underscores allowed
* (see RFC 3501)
* @handler: an untagged response handler function for #CamelIMAPXServer
- * @next_response: the IMAP untagged code to call a registered
+ * @next_response: (nullable): the IMAP untagged code to call a registered
* handler for directly after successfully
* running @handler. If not NULL, @skip_stream_when_done
* for the current handler has no effect
diff --git a/src/camel/providers/imapx/camel-imapx-settings.c
b/src/camel/providers/imapx/camel-imapx-settings.c
index 632e351c0..702c52603 100644
--- a/src/camel/providers/imapx/camel-imapx-settings.c
+++ b/src/camel/providers/imapx/camel-imapx-settings.c
@@ -1202,7 +1202,7 @@ camel_imapx_settings_set_filter_junk_inbox (CamelIMAPXSettings *settings,
*
* Returns the custom IMAP namespace in which to find folders.
*
- * Returns: the custom IMAP namespace, or %NULL
+ * Returns: (nullable): the custom IMAP namespace, or %NULL
*
* Since: 3.2
**/
@@ -1223,7 +1223,7 @@ camel_imapx_settings_get_namespace (CamelIMAPXSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelIMAPXSettings:namespace
+ * Returns: (nullable): a newly-allocated copy of #CamelIMAPXSettings:namespace
*
* Since: 3.4
**/
@@ -1248,7 +1248,7 @@ camel_imapx_settings_dup_namespace (CamelIMAPXSettings *settings)
/**
* camel_imapx_settings_set_namespace:
* @settings: a #CamelIMAPXSettings
- * @namespace_: an IMAP namespace, or %NULL
+ * @namespace_: (nullable): an IMAP namespace, or %NULL
*
* Sets the custom IMAP namespace in which to find folders. If @namespace_
* is %NULL, the default namespace is used.
@@ -1287,7 +1287,7 @@ camel_imapx_settings_set_namespace (CamelIMAPXSettings *settings,
* Returns the path to a real, non-virtual Junk folder to be used instead
* of Camel's standard virtual Junk folder.
*
- * Returns: path to a real junk folder
+ * Returns: (nullable): path to a real junk folder
*
* Since: 3.8
**/
@@ -1308,7 +1308,7 @@ camel_imapx_settings_get_real_junk_path (CamelIMAPXSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelIMAPXSettings:real-junk-path
+ * Returns: (nullable): a newly-allocated copy of #CamelIMAPXSettings:real-junk-path
*
* Since: 3.8
**/
@@ -1333,7 +1333,7 @@ camel_imapx_settings_dup_real_junk_path (CamelIMAPXSettings *settings)
/**
* camel_imapx_settings_set_real_junk_path:
* @settings: a #CamelIMAPXSettings
- * @real_junk_path: path to a real Junk folder, or %NULL
+ * @real_junk_path: (nullable): path to a real Junk folder, or %NULL
*
* Sets the path to a real, non-virtual Junk folder to be used instead of
* Camel's standard virtual Junk folder.
@@ -1367,7 +1367,7 @@ camel_imapx_settings_set_real_junk_path (CamelIMAPXSettings *settings,
* Returns the path to a real, non-virtual Trash folder to be used instead
* of Camel's standard virtual Trash folder.
*
- * Returns: path to a real Trash folder
+ * Returns: (nullable): path to a real Trash folder
*
* Since: 3.8
**/
@@ -1388,7 +1388,7 @@ camel_imapx_settings_get_real_trash_path (CamelIMAPXSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelIMAPXsettings:real-trash-path
+ * Returns: (nullable): a newly-allocated copy of #CamelIMAPXsettings:real-trash-path
*
* Since: 3.8
**/
@@ -1413,7 +1413,7 @@ camel_imapx_settings_dup_real_trash_path (CamelIMAPXSettings *settings)
/**
* camel_imapx_settings_set_real_trash_path:
* @settings: a #CamelIMAPXSettings
- * @real_trash_path: path to a real Trash folder, or %NULL
+ * @real_trash_path: (nullable): path to a real Trash folder, or %NULL
*
* Sets the path to a real, non-virtual Trash folder to be used instead of
* Camel's standard virtual Trash folder.
@@ -1453,7 +1453,7 @@ camel_imapx_settings_set_real_trash_path (CamelIMAPXSettings *settings,
* this option menas or how to use it. Probably not worth exposing in a
* graphical interface.
*
- * Returns: shell command for connecting to the server, or %NULL
+ * Returns: (nullable): shell command for connecting to the server, or %NULL
*
* Since: 3.2
**/
@@ -1474,7 +1474,7 @@ camel_imapx_settings_get_shell_command (CamelIMAPXSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelIMAPXSettings:shell-command
+ * Returns: (nullable): a newly-allocated copy of #CamelIMAPXSettings:shell-command
*
* Since: 3.4
**/
@@ -1499,7 +1499,7 @@ camel_imapx_settings_dup_shell_command (CamelIMAPXSettings *settings)
/**
* camel_imapx_settings_set_shell_command:
* @settings: a #CamelIMAPXSettings
- * @shell_command: shell command for connecting to the server, or %NULL
+ * @shell_command: (nullable): shell command for connecting to the server, or %NULL
*
* Sets an optional shell command used to establish an input/output stream
* with an IMAP server. Normally the input/output stream is established
diff --git a/src/camel/providers/imapx/camel-imapx-status-response.c
b/src/camel/providers/imapx/camel-imapx-status-response.c
index c5140e809..c2b49df58 100644
--- a/src/camel/providers/imapx/camel-imapx-status-response.c
+++ b/src/camel/providers/imapx/camel-imapx-status-response.c
@@ -94,7 +94,7 @@ camel_imapx_status_response_init (CamelIMAPXStatusResponse *response)
* stores the response data in a new #CamelIMAPXStatusResponse. If an error
* occurs, the function sets @error and returns %NULL.
*
- * Returns: a #CamelIMAPXStatusResponse, or %NULL
+ * Returns: (nullable): a #CamelIMAPXStatusResponse, or %NULL
*
* Since: 3.10
**/
diff --git a/src/camel/providers/imapx/camel-imapx-store-summary.c
b/src/camel/providers/imapx/camel-imapx-store-summary.c
index 0b4386322..5901bdafa 100644
--- a/src/camel/providers/imapx/camel-imapx-store-summary.c
+++ b/src/camel/providers/imapx/camel-imapx-store-summary.c
@@ -280,7 +280,7 @@ camel_imapx_store_summary_init (CamelIMAPXStoreSummary *summary)
* and should be unreferenced with camel_store_summary_info_unref()
* when finished with it.
*
- * Returns: a #CamelIMAPXStoreInfo, or %NULL
+ * Returns: (nullable): a #CamelIMAPXStoreInfo, or %NULL
**/
CamelIMAPXStoreInfo *
camel_imapx_store_summary_mailbox (CamelStoreSummary *summary,
diff --git a/src/camel/providers/imapx/camel-imapx-store.c b/src/camel/providers/imapx/camel-imapx-store.c
index a4ef9bea3..140f35745 100644
--- a/src/camel/providers/imapx/camel-imapx-store.c
+++ b/src/camel/providers/imapx/camel-imapx-store.c
@@ -3810,7 +3810,7 @@ camel_imapx_store_ref_mailbox (CamelIMAPXStore *imapx_store,
* camel_imapx_store_list_mailboxes:
* @imapx_store: a #CamelIMAPXStore
* @namespace_: a #CamelIMAPXNamespace
- * @pattern: mailbox name with possible wildcards, or %NULL
+ * @pattern: (nullable): mailbox name with possible wildcards, or %NULL
*
* Returns a list of #CamelIMAPXMailbox instances which match @namespace and
* @pattern. The @pattern may contain wildcard characters '*' and '%', which
diff --git a/src/camel/providers/imapx/camel-imapx-utils.c b/src/camel/providers/imapx/camel-imapx-utils.c
index 8b0146fd0..86f3bf123 100644
--- a/src/camel/providers/imapx/camel-imapx-utils.c
+++ b/src/camel/providers/imapx/camel-imapx-utils.c
@@ -2947,7 +2947,7 @@ exit:
*
* If an error occurs, the function sets @error and returns %NULL.
*
- * Returns: a newly-allocated mailbox name, or %NULL
+ * Returns: (nullable): a newly-allocated mailbox name, or %NULL
*
* Since: 3.10
**/
diff --git a/src/camel/providers/nntp/camel-nntp-store.c b/src/camel/providers/nntp/camel-nntp-store.c
index 16bb3ec36..bd59dc016 100644
--- a/src/camel/providers/nntp/camel-nntp-store.c
+++ b/src/camel/providers/nntp/camel-nntp-store.c
@@ -1874,7 +1874,7 @@ camel_nntp_store_ref_summary (CamelNNTPStore *nntp_store)
* Returns the currently selected newsgroup name, or %NULL if no newsgroup
* is selected.
*
- * Returns: the currently selected newsgroup name, or %NULL
+ * Returns: (nullable): the currently selected newsgroup name, or %NULL
**/
const gchar *
camel_nntp_store_get_current_group (CamelNNTPStore *nntp_store)
@@ -1893,7 +1893,7 @@ camel_nntp_store_get_current_group (CamelNNTPStore *nntp_store)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated string, or %NULL
+ * Returns: (nullable): a newly-allocated string, or %NULL
**/
gchar *
camel_nntp_store_dup_current_group (CamelNNTPStore *nntp_store)
@@ -1916,7 +1916,7 @@ camel_nntp_store_dup_current_group (CamelNNTPStore *nntp_store)
/**
* camel_nntp_store_set_current_group:
* @nntp_store: a #CamelNNTPStore
- * @current_group: a newsgroup name
+ * @current_group: (nullable): a newsgroup name
*
* Sets the name of the currently selected newsgroup.
**/
diff --git a/src/camel/providers/pop3/camel-pop3-engine.c b/src/camel/providers/pop3/camel-pop3-engine.c
index 0652ba948..3ae140440 100644
--- a/src/camel/providers/pop3/camel-pop3-engine.c
+++ b/src/camel/providers/pop3/camel-pop3-engine.c
@@ -128,7 +128,7 @@ read_greeting (CamelPOP3Engine *pe,
* Returns a NULL stream. A null stream is always at eof, and
* always returns success for all reads and writes.
*
- * Returns: the stream
+ * Returns: (nullable): the stream
**/
CamelPOP3Engine *
camel_pop3_engine_new (CamelStream *source,
diff --git a/src/camel/providers/pop3/camel-pop3-store.c b/src/camel/providers/pop3/camel-pop3-store.c
index 8a7d2bb42..2e6fa8876 100644
--- a/src/camel/providers/pop3/camel-pop3-store.c
+++ b/src/camel/providers/pop3/camel-pop3-store.c
@@ -1159,7 +1159,7 @@ camel_pop3_store_expunge (CamelPOP3Store *store,
* The returned #CamelStream is referenced for thread-safety and must be
* unreferenced when finished with it.
*
- * Returns: a #CamelStream, or %NULL
+ * Returns: (nullable): a #CamelStream, or %NULL
**/
CamelStream *
camel_pop3_store_cache_add (CamelPOP3Store *store,
@@ -1201,7 +1201,7 @@ camel_pop3_store_cache_add (CamelPOP3Store *store,
* The returned #CamelStream is referenced for thread-safety and must be
* unreferenced when finished with it.
*
- * Returns: a #CamelStream, or %NULL
+ * Returns: (nullable): a #CamelStream, or %NULL
**/
CamelStream *
camel_pop3_store_cache_get (CamelPOP3Store *store,
diff --git a/src/camel/providers/sendmail/camel-sendmail-settings.c
b/src/camel/providers/sendmail/camel-sendmail-settings.c
index b4dc1203e..872206877 100644
--- a/src/camel/providers/sendmail/camel-sendmail-settings.c
+++ b/src/camel/providers/sendmail/camel-sendmail-settings.c
@@ -312,7 +312,7 @@ camel_sendmail_settings_set_use_custom_args (CamelSendmailSettings *settings,
*
* Returns the custom binary to run, instead of sendmail.
*
- * Returns: the custom binary to run, instead of sendmail, or %NULL
+ * Returns: (nullable): the custom binary to run, instead of sendmail, or %NULL
*
* Since: 3.8
**/
@@ -333,7 +333,7 @@ camel_sendmail_settings_get_custom_binary (CamelSendmailSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelSendmailSettings:custom-binary
+ * Returns: (nullable): a newly-allocated copy of #CamelSendmailSettings:custom-binary
*
* Since: 3.8
**/
@@ -358,7 +358,7 @@ camel_sendmail_settings_dup_custom_binary (CamelSendmailSettings *settings)
/**
* camel_sendmail_settings_set_custom_binary:
* @settings: a #CamelSendmailSettings
- * @custom_binary: a custom binary name, or %NULL
+ * @custom_binary: (nullable): a custom binary name, or %NULL
*
* Sets the custom binary name to run, instead of sendmail.
*
@@ -395,7 +395,8 @@ camel_sendmail_settings_set_custom_binary (CamelSendmailSettings *settings,
*
* Returns the custom arguments to use, instead of default arguments.
*
- * Returns: the custom arguments to use, instead of default arguments, or %NULL
+ * Returns: (nullable): the custom arguments to use, instead of default
+ * arguments, or %NULL
*
* Since: 3.8
**/
@@ -416,7 +417,7 @@ camel_sendmail_settings_get_custom_args (CamelSendmailSettings *settings)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated copy of #CamelSendmailSettings:custom-args
+ * Returns: (nullable): a newly-allocated copy of #CamelSendmailSettings:custom-args
*
* Since: 3.8
**/
@@ -441,7 +442,7 @@ camel_sendmail_settings_dup_custom_args (CamelSendmailSettings *settings)
/**
* camel_sendmail_settings_set_custom_args:
* @settings: a #CamelSendmailSettings
- * @custom_args: a custom arguments, or %NULL
+ * @custom_args: (nullable): a custom arguments, or %NULL
*
* Sets the custom arguments to use, instead of default arguments.
*
diff --git a/src/libebackend/e-cache.c b/src/libebackend/e-cache.c
index 7710e9ad0..4d89cb25e 100644
--- a/src/libebackend/e-cache.c
+++ b/src/libebackend/e-cache.c
@@ -301,8 +301,8 @@ e_cache_column_values_remove_all (ECacheColumnValues *other_columns)
* The returned pointer is owned by @other_columns and is valid until
* the value is overwritten of the @other_columns freed.
*
- * Returns: Stored value for the column named @name, or %NULL, if
- * no such column values is stored.
+ * Returns: (nullable): Stored value for the column named @name,
+ * or %NULL, if no such column values is stored.
*
* Since: 3.26
**/
@@ -397,9 +397,9 @@ e_cache_offline_change_new (const gchar *uid,
* e_cache_offline_change_copy:
* @change: (nullable): a source #ECacheOfflineChange to copy, or %NULL
*
- * Returns: (transfer full): Copy of the given @change. Free it with
- * e_cache_offline_change_free() when no longer needed.
- * If the @change is %NULL, then returns %NULL as well.
+ * Returns: (transfer full) (nullable): Copy of the given @change.
+ * Free it with e_cache_offline_change_free() when no longer
+ * needed. If the @change is %NULL, then returns %NULL as well.
*
* Since: 3.26
**/
@@ -467,8 +467,8 @@ e_cache_column_info_new (const gchar *name,
* e_cache_column_info_copy:
* @info: (nullable): a source #ECacheColumnInfo to copy, or %NULL
*
- * Returns: (transfer full): Copy of the given @info. Free it with
- * e_cache_column_info_free() when no longer needed.
+ * Returns: (transfer full) (nullable): Copy of the given @info.
+ * Free it with e_cache_column_info_free() when no longer needed.
* If the @info is %NULL, then returns %NULL as well.
*
* Since: 3.26
diff --git a/src/libebackend/e-collection-backend.c b/src/libebackend/e-collection-backend.c
index eb22cb0be..a7b4db421 100644
--- a/src/libebackend/e-collection-backend.c
+++ b/src/libebackend/e-collection-backend.c
@@ -1480,7 +1480,8 @@ e_collection_backend_get_cache_dir (ECollectionBackend *backend)
*
* The returned string should be freed with g_free() when no longer needed.
*
- * Returns: a newly-allocated resource ID for @child_source, or %NULL
+ * Returns: (nullable): a newly-allocated resource ID for @child_source,
+ * or %NULL
*
* Since: 3.6
**/
@@ -1545,7 +1546,8 @@ e_collection_backend_dup_resource_id (ECollectionBackend *backend,
* g_list_free_full (list, g_object_unref);
* ]|
*
- * Returns: (element-type ESource) (transfer full): a list of previously used sources
+ * Returns: (element-type ESource) (transfer full) (nullable): a list
+ * of previously used sources
*
* Since: 3.6
**/
diff --git a/src/libebackend/e-data-factory.c b/src/libebackend/e-data-factory.c
index 63b3ccf9b..7905be0e1 100644
--- a/src/libebackend/e-data-factory.c
+++ b/src/libebackend/e-data-factory.c
@@ -1268,7 +1268,8 @@ e_data_factory_init (EDataFactory *data_factory)
* Unreference the #EBackendFactory with g_object_unref() when finished
* with it.
*
- * Returns: (transfer full): the #EBackendFactory for @hash_key, or %NULL
+ * Returns: (transfer full) (nullable): the #EBackendFactory for @hash_key,
+ * or %NULL
*
* Since: 3.6
**/
@@ -1738,7 +1739,7 @@ e_data_factory_use_backend_per_process (EDataFactory *data_factory)
* Free the returned pointer with g_object_unref(), if not NULL and no longer
* needed.
*
- * Returns: (transfer full): a newly-created #EBackend
+ * Returns: (transfer full) (nullable): a newly-created #EBackend
**/
EBackend *
e_data_factory_create_backend (EDataFactory *data_factory,
diff --git a/src/libebackend/e-file-cache.c b/src/libebackend/e-file-cache.c
index a94e5f300..d386cbafe 100644
--- a/src/libebackend/e-file-cache.c
+++ b/src/libebackend/e-file-cache.c
@@ -332,7 +332,7 @@ find_object_in_hash (gpointer key,
* Returns the object corresponding to @key. If no such object exists
* in @cache, the function returns %NULL.
*
- * Returns: the object corresponding to @key
+ * Returns: (nullable): the object corresponding to @key
*/
const gchar *
e_file_cache_get_object (EFileCache *cache,
diff --git a/src/libebackend/e-server-side-source.c b/src/libebackend/e-server-side-source.c
index 6f646f11c..f0baf674a 100644
--- a/src/libebackend/e-server-side-source.c
+++ b/src/libebackend/e-server-side-source.c
@@ -1788,7 +1788,7 @@ e_server_side_source_get_user_dir (void)
/**
* e_server_side_source_new_user_file:
- * @uid: unique identifier for a data source, or %NULL
+ * @uid: (nullable): unique identifier for a data source, or %NULL
*
* Generates a unique file name for a new user-specific data source.
* If @uid is non-%NULL it will be used in the basename of the file,
@@ -1840,7 +1840,7 @@ e_server_side_source_new_user_file (const gchar *uid)
* If the base name of @file is missing a '.source' extension, the
* function sets @error and returns %NULL.
*
- * Returns: the unique identity string for @file, or %NULL
+ * Returns: (nullable): the unique identity string for @file, or %NULL
*
* Since: 3.6
**/
@@ -1875,7 +1875,7 @@ e_server_side_source_uid_from_file (GFile *file,
/**
* e_server_side_source_new:
* @server: an #ESourceRegistryServer
- * @file: a #GFile, or %NULL
+ * @file: (nullable): a #GFile, or %NULL
* @error: return location for a #GError, or %NULL
*
* Creates a new #EServerSideSource which belongs to @server. If @file
@@ -1883,7 +1883,7 @@ e_server_side_source_uid_from_file (GFile *file,
* initialized from the file content. If a read error occurs or the file
* contains syntax errors, the function sets @error and returns %NULL.
*
- * Returns: a new #EServerSideSource, or %NULL
+ * Returns: (nullable): a new #EServerSideSource, or %NULL
*
* Since: 3.6
**/
@@ -1925,7 +1925,7 @@ e_server_side_source_new (ESourceRegistryServer *server,
/**
* e_server_side_source_new_memory_only:
* @server: an #ESourceRegistryServer
- * @uid: a unique identifier, or %NULL
+ * @uid: (nullable): a unique identifier, or %NULL
* @error: return location for a #GError, or %NULL
*
* Creates a memory-only #EServerSideSource which belongs to @server.
@@ -1941,7 +1941,7 @@ e_server_side_source_new (ESourceRegistryServer *server,
* function sets @error and returns %NULL. Although at this time there
* are no known error conditions for memory-only data sources.
*
- * Returns: a new memory-only #EServerSideSource, or %NULL
+ * Returns: (nullable): a new memory-only #EServerSideSource, or %NULL
*
* Since: 3.6
**/
@@ -2449,7 +2449,7 @@ e_server_side_source_ref_oauth2_support (EServerSideSource *source)
/**
* e_server_side_source_set_oauth2_support:
* @source: an #EServerSideSource
- * @oauth2_support: an #EOAuth2Support object, or %NULL
+ * @oauth2_support: (nullable): an #EOAuth2Support object, or %NULL
*
* Indicates whether @source supports OAuth 2.0 authentication.
*
diff --git a/src/libebackend/e-source-registry-server.c b/src/libebackend/e-source-registry-server.c
index 0baeaf0fe..4fe4759a5 100644
--- a/src/libebackend/e-source-registry-server.c
+++ b/src/libebackend/e-source-registry-server.c
@@ -1941,7 +1941,7 @@ e_source_registry_server_ref_source (ESourceRegistryServer *server,
/**
* e_source_registry_server_list_sources:
* @server: an #ESourceRegistryServer
- * @extension_name: an extension name, or %NULL
+ * @extension_name: (nullable): an extension name, or %NULL
*
* Returns a list of registered sources, sorted by display name. If
* @extension_name is given, restrict the list to sources having that
diff --git a/src/libedataserver/e-collator.c b/src/libedataserver/e-collator.c
index 3bb4574a1..06f4e9c42 100644
--- a/src/libedataserver/e-collator.c
+++ b/src/libedataserver/e-collator.c
@@ -463,7 +463,8 @@ e_collator_unref (ECollator *collator)
*
* This function will first ensure that @str is valid UTF-8 encoded.
*
- * Returns: (transfer full): A collation key for @str, or %NULL on failure with @error set.
+ * Returns: (transfer full) (nullable): A collation key for @str, or
+ * %NULL on failure with @error set.
*
* Since: 3.12
*/
diff --git a/src/libedataserver/e-credentials.c b/src/libedataserver/e-credentials.c
index 0b478d345..7e67ed7a2 100644
--- a/src/libedataserver/e-credentials.c
+++ b/src/libedataserver/e-credentials.c
@@ -301,7 +301,7 @@ decode_string (const gchar *encoded)
* e_credentials_set:
* @credentials: an #ECredentials
* @key: a key string
- * @value: a value string
+ * @value: (nullable): a value string
*
* Sets value for @key, if @value is %NULL or an empty string then @key is
* removed. The value is supposed to be in a clear form (unencoded).
diff --git a/src/libedataserver/e-data-server-util.c b/src/libedataserver/e-data-server-util.c
index d52809bd7..c1a792019 100644
--- a/src/libedataserver/e-data-server-util.c
+++ b/src/libedataserver/e-data-server-util.c
@@ -397,8 +397,8 @@ stripped_char (gunichar ch)
* and @haystack are UTF-8 strings. Both strings are stripped and
* decomposed for comparison, and case is ignored.
*
- * Returns: A pointer to the first instance of @needle in @haystack, or
- * %NULL if either of the strings are not legal UTF-8 strings.
+ * Returns: (nullable): A pointer to the first instance of @needle in @haystack,
+ * or %NULL if either of the strings are not legal UTF-8 strings.
**/
const gchar *
e_util_utf8_strstrcasedecomp (const gchar *haystack,
@@ -504,11 +504,11 @@ e_util_utf8_strcasecmp (const gchar *s1,
/**
* e_util_utf8_remove_accents:
- * @str: a UTF-8 string, or %NULL
+ * @str: (nullable): a UTF-8 string, or %NULL
*
* Returns a newly-allocated copy of @str with accents removed.
*
- * Returns: a newly-allocated string
+ * Returns: (nullable): a newly-allocated string
*
* Since: 2.28
**/
@@ -587,7 +587,7 @@ e_util_utf8_decompose (const gchar *text)
/**
* e_util_utf8_make_valid:
- * @str: a UTF-8 string
+ * @str: (nullable): a UTF-8 string
*
* Returns a newly-allocated copy of @str, with invalid characters
* replaced by Unicode replacement characters (U+FFFD).
@@ -608,7 +608,7 @@ e_util_utf8_make_valid (const gchar *str)
/**
* e_util_utf8_data_make_valid:
- * @data: UTF-8 binary data
+ * @data: (nullable): UTF-8 binary data
* @data_bytes: length of the binary data
*
* Returns a newly-allocated NULL-terminated string with invalid characters
@@ -698,7 +698,7 @@ e_util_utf8_normalize (const gchar *str)
/**
* e_util_ensure_gdbus_string:
- * @str: a possibly invalid UTF-8 string, or %NULL
+ * @str: (nullable): a possibly invalid UTF-8 string, or %NULL
* @gdbus_str: return location for the corrected string
*
* If @str is a valid UTF-8 string, the function returns @str and does
@@ -953,7 +953,7 @@ e_filename_make_safe (gchar *string)
* e_filename_mkdir_encoded:
* @basepath: base path of a file name; this is left unchanged
* @fileprefix: prefix for the filename; this is encoded
- * @filename: file name to use; this is encoded; can be %NULL
+ * @filename: (nullable): file name to use; this is encoded; can be %NULL
* @fileindex: used when @filename is NULL, then the filename
* is generated as "file" + fileindex
*
@@ -961,7 +961,7 @@ e_filename_make_safe (gchar *string)
* and makes sure the path @basepath exists. If creation of
* the path fails, then NULL is returned.
*
- * Returns: Full local path like g_build_filename() except that @fileprefix
+ * Returns: (nullable): Full local path like g_build_filename() except that @fileprefix
* and @filename are encoded to create a proper file elements for
* a file system. Free returned pointer with g_free().
*
@@ -1477,7 +1477,7 @@ e_binding_bind_property (gpointer source,
* from the @source to the @target, or %NULL to use the default
* @transform_from: (scope notified) (nullable): the transformation function
* from the @target to the @source, or %NULL to use the default
- * @user_data: custom data to be passed to the transformation functions,
+ * @user_data: (nullable): custom data to be passed to the transformation functions,
* or %NULL
* @notify: function to be called when disposing the binding, to free the
* resources used by the transformation functions
@@ -1872,7 +1872,8 @@ e_async_closure_free (EAsyncClosure *closure)
/**
* e_async_closure_callback: (skip)
- * @object: a #GObject or %NULL, it is not used by the function at all
+ * @object: (nullable): a #GObject or %NULL, it is not used by the function
+ * at all
* @result: a #GAsyncResult
* @closure: an #EAsyncClosure
*
diff --git a/src/libedataserver/e-flag.c b/src/libedataserver/e-flag.c
index 894e56729..fc857f719 100644
--- a/src/libedataserver/e-flag.c
+++ b/src/libedataserver/e-flag.c
@@ -141,7 +141,7 @@ e_flag_wait (EFlag *flag)
/**
* e_flag_timed_wait: (skip)
* @flag: an #EFlag
- * @abs_time: a #GTimeVal, determining the final time
+ * @abs_time: (nullable): a #GTimeVal, determining the final time
*
* Blocks until @flag is set, or until the time specified by @abs_time.
* If @flag is already set, the function returns immediately. The return
diff --git a/src/libedataserver/e-free-form-exp.c b/src/libedataserver/e-free-form-exp.c
index 519d01eb3..b06c4d186 100644
--- a/src/libedataserver/e-free-form-exp.c
+++ b/src/libedataserver/e-free-form-exp.c
@@ -272,7 +272,7 @@ ffe_finish_and_or_not (GString *sexp)
* The @symbols is a NULL-terminated array of known symbols. The NULL should
* be set for the symbol's name.
*
- * Returns: converted @free_form_exp into S-Expression, %NULL on error.
+ * Returns: (nullable): converted @free_form_exp into S-Expression, %NULL on error.
* Free the returned string with a g_free(), when done with it.
*
* Since: 3.16
diff --git a/src/libedataserver/e-gdata-oauth2-authorizer.c b/src/libedataserver/e-gdata-oauth2-authorizer.c
index 6b379eee2..038ca86db 100644
--- a/src/libedataserver/e-gdata-oauth2-authorizer.c
+++ b/src/libedataserver/e-gdata-oauth2-authorizer.c
@@ -383,7 +383,7 @@ e_gdata_oauth2_authorizer_supported (void)
* and @service_type. The function always returns %NULL when
* e_gdata_oauth2_authorizer_supported() returns %FALSE.
*
- * Returns: (transfer full): a new #EGDataOAuth2Authorizer, or %NULL when
+ * Returns: (transfer full) (nullable): a new #EGDataOAuth2Authorizer, or %NULL when
* the #EGDataOAuth2Authorizer is not supported.
*
* Since: 3.28
@@ -408,7 +408,7 @@ e_gdata_oauth2_authorizer_new (ESource *source,
* e_gdata_oauth2_authorizer_ref_source:
* @oauth2_authorizer: an #EGDataOAuth2Authorizer
*
- * Returns: (transfer full): an #ESource, for which the @oauth2_authorizer
+ * Returns: (transfer full) (nullable): an #ESource, for which the @oauth2_authorizer
* had been created, or %NULL. Free returned non-NULL object with g_object_unref(),
* when done with it.
*
diff --git a/src/libedataserver/e-soup-session.c b/src/libedataserver/e-soup-session.c
index 381b9f88d..13e0327f3 100644
--- a/src/libedataserver/e-soup-session.c
+++ b/src/libedataserver/e-soup-session.c
@@ -798,7 +798,7 @@ e_soup_session_preset_request (SoupRequestHTTP *request)
*
* See also e_soup_session_new_request_uri().
*
- * Returns: (transfer full): a new #SoupRequestHTTP, or %NULL on error
+ * Returns: (transfer full) (nullable): a new #SoupRequestHTTP, or %NULL on error
*
* Since: 3.26
**/
diff --git a/src/libedataserver/e-source-credentials-provider.c
b/src/libedataserver/e-source-credentials-provider.c
index b1ead1440..96490e1a5 100644
--- a/src/libedataserver/e-source-credentials-provider.c
+++ b/src/libedataserver/e-source-credentials-provider.c
@@ -375,7 +375,7 @@ e_source_credentials_provider_unregister_impl (ESourceCredentialsProvider *provi
*
* Returns referenced #ESource with the given @uid, or %NULL, when it could not be found.
*
- * Returns: (transfer full): Referenced #ESource with the given @uid, or %NULL, when it
+ * Returns: (transfer full) (nullable): Referenced #ESource with the given @uid, or %NULL, when it
* could not be found. Unref the returned #ESource with g_object_unref(), when no longer needed.
*
* Since: 3.16
@@ -407,8 +407,9 @@ e_source_credentials_provider_ref_source (ESourceCredentialsProvider *provider,
* sources. When ther eis no such parent source, a %NULL is returned, which
* means the @source holds credentials for itself.
*
- * Returns: (transfer full): referenced parent #ESource, which holds credentials, or %NULL. Unref
- * the returned non-NULL #ESource with g_object_unref(), when no longer needed.
+ * Returns: (transfer full) (nullable): referenced parent #ESource, which holds
+ * credentials, or %NULL. Unref the returned non-NULL #ESource with
+ * g_object_unref(), when no longer needed.
*
* Since: 3.16
**/
diff --git a/src/libedataserver/e-source-proxy.c b/src/libedataserver/e-source-proxy.c
index 84d5ccd5a..c20859361 100644
--- a/src/libedataserver/e-source-proxy.c
+++ b/src/libedataserver/e-source-proxy.c
@@ -1622,7 +1622,8 @@ e_source_proxy_set_socks_port (ESourceProxy *extension,
*
* Free the returned proxy URIs with g_strfreev() when finished with them.
*
- * Returns: (transfer full): a %NULL-terminated array of proxy URIs, or %NULL
+ * Returns: (transfer full) (nullable): a %NULL-terminated array of proxy URIs,
+ * or %NULL
*
* Since: 3.12
**/
@@ -1838,7 +1839,8 @@ e_source_proxy_lookup (ESource *source,
*
* Free the returned proxy URIs with g_strfreev() when finished with them.
*
- * Returns: (transfer full): a %NULL-terminated array of proxy URIs, or %NULL
+ * Returns: (transfer full) (nullable): a %NULL-terminated array of proxy
+ * URIs, or %NULL
*
* Since: 3.12
**/
diff --git a/src/libedataserver/e-source-registry.c b/src/libedataserver/e-source-registry.c
index 44a5b4b4c..a639082d6 100644
--- a/src/libedataserver/e-source-registry.c
+++ b/src/libedataserver/e-source-registry.c
@@ -1792,7 +1792,7 @@ e_source_registry_init (ESourceRegistry *registry)
* Since 3.12 a singleton will be returned. No strong reference is kept
* internally, so it is the caller's responsibility to keep one.
*
- * Returns: a new #ESourceRegistry, or %NULL
+ * Returns: (nullable): a new #ESourceRegistry, or %NULL
*
* Since: 3.6
**/
@@ -1886,7 +1886,7 @@ e_source_registry_new (GCancellable *cancellable,
* If an error occurs in connecting to the D-Bus service, the function
* sets @error and returns %NULL.
*
- * Returns: a new #ESourceRegistry, or %NULL
+ * Returns: (nullable): a new #ESourceRegistry, or %NULL
*
* Since: 3.6
**/
@@ -3471,7 +3471,8 @@ source_registry_ref_any_mail_identity (ESourceRegistry *registry)
* The returned #ESource is referenced for thread-safety and must be
* unreferenced with g_object_unref() when finished with it.
*
- * Returns: (transfer full): the default mail identity #ESource, or %NULL
+ * Returns: (transfer full) (nullable): the default mail identity #ESource,
+ * or %NULL
*
* Since: 3.6
**/
diff --git a/src/libedataserver/e-source.c b/src/libedataserver/e-source.c
index b2fb6102d..8943ad346 100644
--- a/src/libedataserver/e-source.c
+++ b/src/libedataserver/e-source.c
@@ -2538,7 +2538,7 @@ __e_source_private_replace_dbus_object (ESource *source,
*
* FIXME: Elaborate on scratch sources.
*
- * Returns: a new #ESource, or %NULL on error
+ * Returns: (nullable): a new #ESource, or %NULL on error
*
* Since: 3.6
**/
@@ -2569,7 +2569,7 @@ e_source_new (GDBusObject *dbus_object,
* or else from the thread-default #GMainContext at the time this function is
* called.
*
- * Returns: a new scratch #ESource, or %NULL on error
+ * Returns: (nullable): a new scratch #ESource, or %NULL on error
*
* Since: 3.6
**/
diff --git a/src/libedataserver/e-webdav-discover.c b/src/libedataserver/e-webdav-discover.c
index 50633b219..79980200b 100644
--- a/src/libedataserver/e-webdav-discover.c
+++ b/src/libedataserver/e-webdav-discover.c
@@ -1100,7 +1100,7 @@ e_webdav_discovered_source_copy (EWebDAVDiscoveredSource *discovered_source)
/**
* e_webdav_discovered_source_free:
- * @discovered_source: an #EWebDAVDiscoveredSource to free
+ * @discovered_source: (nullable): an #EWebDAVDiscoveredSource to free
*
* Frees the @discovered_source. Function does nothing, when it's %NULL.
*
diff --git a/src/libedataserver/e-webdav-session.c b/src/libedataserver/e-webdav-session.c
index 83c89f517..17b23b081 100644
--- a/src/libedataserver/e-webdav-session.c
+++ b/src/libedataserver/e-webdav-session.c
@@ -116,7 +116,7 @@ e_webdav_resource_new (EWebDAVResourceKind kind,
* e_webdav_resource_copy:
* @src: (nullable): an #EWebDAVResource to make a copy of
*
- * Returns: (transfer full): A new #EWebDAVResource prefilled with
+ * Returns: (transfer full) (nullable): A new #EWebDAVResource prefilled with
* the same values as @src, or %NULL, when @src is %NULL.
* Free it with e_webdav_resource_free(), when no longer needed.
*
@@ -240,8 +240,8 @@ e_webdav_property_change_new_remove (const gchar *ns_uri,
* e_webdav_property_change_copy:
* @src: (nullable): an #EWebDAVPropertyChange to make a copy of
*
- * Returns: (transfer full): A new #EWebDAVPropertyChange prefilled with
- * the same values as @src, or %NULL, when @src is %NULL.
+ * Returns: (transfer full) (nullable): A new #EWebDAVPropertyChange prefilled
+ * with the same values as @src, or %NULL, when @src is %NULL.
* Free it with e_webdav_property_change_free(), when no longer needed.
*
* Since: 3.26
@@ -410,7 +410,7 @@ e_webdav_privilege_new (const gchar *ns_uri,
* e_webdav_privilege_copy:
* @src: (nullable): an #EWebDAVPrivilege to make a copy of
*
- * Returns: (transfer full): A new #EWebDAVPrivilege prefilled with
+ * Returns: (transfer full) (nullable): A new #EWebDAVPrivilege prefilled with
* the same values as @src, or %NULL, when @src is %NULL.
* Free it with e_webdav_privilege_free(), when no longer needed.
*
@@ -504,8 +504,8 @@ e_webdav_access_control_entry_new (EWebDAVACEPrincipalKind principal_kind,
* e_webdav_access_control_entry_copy:
* @src: (nullable): an #EWebDAVAccessControlEntry to make a copy of
*
- * Returns: (transfer full): A new #EWebDAVAccessControlEntry prefilled with
- * the same values as @src, or %NULL, when @src is %NULL.
+ * Returns: (transfer full) (nullable): A new #EWebDAVAccessControlEntry
+ * prefilled with the same values as @src, or %NULL, when @src is %NULL.
* Free it with e_webdav_access_control_entry_free(), when no longer needed.
*
* Since: 3.26
@@ -659,8 +659,8 @@ e_webdav_session_new (ESource *source)
*
* The string is valid until the next request is executed.
*
- * Returns: (transfer none): a DAV error from the last request, or %NULL, when
- * no error had been recognized.
+ * Returns: (transfer none) (nullable): a DAV error from the last request,
+ * or %NULL, when no error had been recognized.
*
* Since: 3.36
**/
diff --git a/src/libedataserver/e-xml-hash-utils.c b/src/libedataserver/e-xml-hash-utils.c
index 90536e0e8..1596da92f 100644
--- a/src/libedataserver/e-xml-hash-utils.c
+++ b/src/libedataserver/e-xml-hash-utils.c
@@ -186,8 +186,8 @@ struct EXmlHash {
* Creates a new #EXmlHash from the file @filename. If @filename does
* not already exist, an empty #EXmlHash will be created.
*
- * Returns: (transfer full): The new #EXmlHash structure, or %NULL if unable to parse
- * @filename.
+ * Returns: (transfer full) (nullable): The new #EXmlHash structure,
+ * or %NULL if unable to parse @filename.
**/
EXmlHash *
e_xmlhash_new (const gchar *filename)
diff --git a/src/libedataserver/e-xml-utils.c b/src/libedataserver/e-xml-utils.c
index a80fb1b48..6b736a91f 100644
--- a/src/libedataserver/e-xml-utils.c
+++ b/src/libedataserver/e-xml-utils.c
@@ -70,7 +70,7 @@ e_xml_initialize_in_main (void)
* structure. If the XML file cannot be read or its contents are malformed,
* the function returns %NULL.
*
- * Returns: (transfer full): an XML document structure, or %NULL
+ * Returns: (transfer full) (nullable): an XML document structure, or %NULL
**/
xmlDoc *
e_xml_parse_file (const gchar *filename)
diff --git a/src/libedataserver/eds-version.c b/src/libedataserver/eds-version.c
index c59562676..c3e1af21c 100644
--- a/src/libedataserver/eds-version.c
+++ b/src/libedataserver/eds-version.c
@@ -35,10 +35,10 @@ const guint eds_micro_version = EDS_MICRO_VERSION;
* use is compatible with the version of Evolution-Data-Server the
* application or module was compiled against.
*
- * Returns: %NULL if the Evolution-Data-Server library is compatible with
- * the given version, or a string describing the version mismatch. The
- * returned string is owned by libedataserver and must not be modified or
- * freed.
+ * Returns: (nullable): %NULL if the Evolution-Data-Server library is
+ * compatible with the given version, or a string describing the version
+ * mismatch. The returned string is owned by libedataserver and must not be
+ * modified or freed.
*
* Since: 2.24
**/
diff --git a/src/libedataserverui/e-credentials-prompter.c b/src/libedataserverui/e-credentials-prompter.c
index 3532eedf8..1a82ab13d 100644
--- a/src/libedataserverui/e-credentials-prompter.c
+++ b/src/libedataserverui/e-credentials-prompter.c
@@ -1145,8 +1145,8 @@ e_credentials_prompter_class_init (ECredentialsPrompterClass *class)
* window for it. If the result of the call is %NULL, then it tries
* to get the window from the default GtkApplication.
*
- * Returns: (transfer none): a #GtkWindow, to be used as a dialog parent,
- * or %NULL.
+ * Returns: (transfer none) (nullable): a #GtkWindow, to be used as a
+ * dialog parent, or %NULL.
*
* Since: 3.16
**/
@@ -1167,8 +1167,8 @@ e_credentials_prompter_class_init (ECredentialsPrompterClass *class)
* window for it. If the result of the call is %NULL, then it tries
* to get the window from the default GtkApplication.
*
- * Returns: (transfer none): a #GtkWindow, to be used as a dialog parent,
- * or %NULL.
+ * Returns: (transfer none) (nullable): a #GtkWindow, to be used as a
+ * dialog parent, or %NULL.
*
* Since: 3.42
**/
@@ -1401,7 +1401,8 @@ credentials_prompter_guess_dialog_parent (ECredentialsPrompter *prompter)
* registered or the current callbacks don't have any suitable window, then there's
* chosen the last active window from the default GApplication, if any available.
*
- * Returns: (transfer none): a #GtkWindow, to be used as a dialog parent, or %NULL.
+ * Returns: (transfer none) (nullable): a #GtkWindow, to be used as a dialog parent,
+ * or %NULL.
*
* Since: 3.16
**/
@@ -1433,7 +1434,8 @@ e_credentials_prompter_get_dialog_parent (ECredentialsPrompter *prompter)
* window, then there's chosen the last active window from the default GApplication,
* if any available.
*
- * Returns: (transfer none): a #GtkWindow, to be used as a dialog parent, or %NULL.
+ * Returns: (transfer none) (nullable): a #GtkWindow, to be used as a dialog parent,
+ * or %NULL.
*
* Since: 3.42
**/
diff --git a/src/libedataserverui/e-webdav-discover-widget.c b/src/libedataserverui/e-webdav-discover-widget.c
index 812a2f513..c1679630a 100644
--- a/src/libedataserverui/e-webdav-discover-widget.c
+++ b/src/libedataserverui/e-webdav-discover-widget.c
@@ -435,10 +435,10 @@ e_webdav_discover_content_get_selected (GtkWidget *content,
* Get currently selected user address in the @content, if the server returned any.
* This value has meaning only with calendar sources.
*
- * Returns: (transfer full): currently selected user address. The returned string
- * is newly allocated and should be freed with g_free() when no longer needed.
- * If there are none addresses provided by the server, or no calendar sources
- * were found, then %NULL is returned instead.
+ * Returns: (transfer full) (nullable): currently selected user address. The
+ * returned string is newly allocated and should be freed with g_free() when
+ * no longer needed. If there are none addresses provided by the server, or
+ * no calendar sources were found, then %NULL is returned instead.
*
* Since: 3.18
**/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
