diff options
author | Michael McClurg <michael.mcclurg@outlook.com> | 2022-01-27 15:46:47 +0100 |
---|---|---|
committer | Milan Crha <mcrha@redhat.com> | 2022-01-27 15:46:47 +0100 |
commit | 617739e67b095dc7ca4623adf6f1f592ee528d55 (patch) | |
tree | 693fa975133e58a61b60ba8db15d8a9ddf835179 | |
parent | 5e23edcd8b8b39bee6b9338d9c60037f87e50abd (diff) | |
download | evolution-data-server-617739e67b095dc7ca4623adf6f1f592ee528d55.tar.gz |
M!79 - Add nullable annotations into developer documentation
Closes https://gitlab.gnome.org/GNOME/evolution-data-server/-/merge_requests/79
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 **/ |