pidgin/pidgin

Fix error parameter annotations

19 months ago, Elliott Sales de Andrade
7e1dd7e9efbb
Parents 4371fa2ce648
Children e0a90a0a5bb2
Fix error parameter annotations

The `(optional)` annotation causes a warning because the parameter is not marked as `(out)`. Additionally, the annotations have no effect on the generated documentation.

When a function takes `GError **error`, then the GObject introspection data includes `throws="1"`.
When gi-docgen sees that annotation, it inserts a standard text about it, so what we write there doesn't matter too much. It will only be seen by people reading the header file directly, so I have inserted a consistent text in those places.

Testing Done:
Compiled and saw fewer warnings from gobject-introspection.

Reviewed at https://reviews.imfreedom.org/r/2019/
12 files changed, 28 insertions(+), 29 deletions(-)
  • +1 -1
    libpurple/buddyicon.h
  • +3 -3
    libpurple/connection.h
  • +1 -1
    libpurple/core.h
  • +1 -1
    libpurple/image.h
  • +1 -1
    libpurple/protocols/ircv3/purpleircv3parser.h
  • +8 -8
    libpurple/purplecredentialmanager.h
  • +4 -4
    libpurple/purplecredentialprovider.h
  • +2 -2
    libpurple/purpleprotocolmanager.h
  • +3 -3
    libpurple/purplesqlite3.h
  • +1 -1
    libpurple/purpleui.h
  • +2 -2
    libpurple/purplewhiteboardmanager.h
  • +1 -2
    libpurple/queuedoutputstream.h
    • --- a/libpurple/buddyicon.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/buddyicon.h Fri Nov 04 00:20:18 2022 -0500
    @@ -169,7 +169,7 @@
    * purple_buddy_icon_save_to_filename:
    * @icon: The #PurpleBuddyIcon instance.
    * @filename: The filename to write.
    - * @error: (out) (optional): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Writes the contents of @icon to @filename.
    *
    --- a/libpurple/connection.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/connection.h Fri Nov 04 00:20:18 2022 -0500
    @@ -187,7 +187,7 @@
    /**
    * purple_connection_connect:
    * @connection: The instance.
    - * @error: (optional): An optional return address for a [type@GLib.GError].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Tells the connection to connect. This is done by calling the
    * [vfunc@Purple.Connection.connect] function. State is managed by this
    @@ -210,7 +210,7 @@
    /**
    * purple_connection_disconnect:
    * @connection: The instance.
    - * @error: (optional): An optional return address for a [type@GLib.GError].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Tells the connection to disconnect. This is done by calling the
    * [vfunc@Purple.Connection.disconnect] function. State is managed by this
    @@ -442,7 +442,7 @@
    /**
    * purple_connection_take_error:
    * @pc: Connection the error is associated with
    - * @error: (transfer full): Error information
    + * @error: Return address for a #GError, or %NULL.
    *
    * Closes a connection similar to [method@Purple.Connection.error], but takes a
    * [type@GLib.Error] which is then converted to purple error codes.
    --- a/libpurple/core.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/core.h Fri Nov 04 00:20:18 2022 -0500
    @@ -38,7 +38,7 @@
    /**
    * purple_core_init:
    * @ui: (transfer full): The [class@Purple.Ui] of the UI using the core.
    - * @error: (optional) (nullable): A return address for a [type@GLib.GError].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Initializes the core of purple.
    *
    --- a/libpurple/image.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/image.h Fri Nov 04 00:20:18 2022 -0500
    @@ -69,7 +69,7 @@
    /**
    * purple_image_new_from_file:
    * @path: the path to the image file.
    - * @error: (optional) (out): An optional return address for a #GError
    + * @error: Return address for a #GError, or %NULL.
    *
    * Loads an image file as a new #PurpleImage object. The @path must exists, be
    * readable and should point to a valid image file. If you don't set @be_eager
    --- a/libpurple/protocols/ircv3/purpleircv3parser.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/protocols/ircv3/purpleircv3parser.h Fri Nov 04 00:20:18 2022 -0500
    @@ -57,7 +57,7 @@
    * purple_ircv3_parser_parse:
    * @parser: The instance.
    * @buffer: The buffer to parse.
    - * @error: (nullable) (out): A return address for a [boxed@Glib.GError].
    + * @error: Return address for a #GError, or %NULL.
    * @data: (nullable): Optional data to pass to the handler.
    *
    * Parses @buffer with @parser.
    --- a/libpurple/purplecredentialmanager.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/purplecredentialmanager.h Fri Nov 04 00:20:18 2022 -0500
    @@ -83,7 +83,7 @@
    * purple_credential_manager_register:
    * @manager: The #PurpleCredentialManager instance.
    * @provider: The #PurpleCredentialProvider to register.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Registers @provider with @manager.
    *
    @@ -98,7 +98,7 @@
    * purple_credential_manager_unregister:
    * @manager: The #PurpleCredentialManager instance.
    * @provider: The #PurpleCredentialProvider to unregister.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Unregisters @provider from @manager.
    *
    @@ -114,7 +114,7 @@
    * @manager: The #PurpleCredentialManager instance.
    * @id: The id of the #PurpleCredentialProvider to use or %NULL to disable the
    * active provider.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Changes the active #PurpleCredentialProvider of @manager to provider with an
    * id of @id.
    @@ -164,7 +164,7 @@
    * @manager: The #PurpleCredentialManager instance.
    * @result: The #GAsyncResult from the previous
    * purple_credential_manager_read_password_async() call.
    - * @error: (out) (optional): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes a previous call to purple_credential_manager_read_password_async().
    *
    @@ -197,7 +197,7 @@
    * @manager: The #PurpleCredentialManager instance.
    * @result: The #GAsyncResult from the previous
    * purple_credential_provider_write_password_async() call.
    - * @error: (out) (optional) (nullable): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes a previous call to purple_credential_manager_write_password_async().
    *
    @@ -229,7 +229,7 @@
    * @manager: The #PurpleCredentialManager instance.
    * @result: The #GAsyncResult from the previous
    * purple_credential_provider_clear_password_async() call.
    - * @error: (out) (optional) (nullable): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes a previous call to
    * purple_credential_provider_clear_password_async().
    @@ -244,7 +244,7 @@
    /**
    * purple_credential_manager_read_settings:
    * @manager: The #PurpleCredentialManager instance.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Reads settings from the active #PurpleCredentialProvider of @manager.
    *
    @@ -260,7 +260,7 @@
    * @manager: The #PurpleCredentialManager instance.
    * @fields: (transfer full): Modified settings from
    * purple_credential_manager_read_settings().
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Write @fields to the active #PurpleCredentialProvider of @manager.
    *
    --- a/libpurple/purplecredentialprovider.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/purplecredentialprovider.h Fri Nov 04 00:20:18 2022 -0500
    @@ -139,7 +139,7 @@
    /**
    * purple_credential_provider_is_valid:
    * @provider: The #PurpleCredentialProvider instance.
    - * @error: (out) (optional) (nullable): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Checks whether or not @provider is setup correctly. This is primarily meant
    * for #purple_credential_provider_register_provider to call to avoid
    @@ -171,7 +171,7 @@
    * @provider: The #PurpleCredentialProvider instance.
    * @result: The #GAsyncResult from the previous
    * purple_credential_provider_read_password_async() call.
    - * @error: (out) (optional) (nullable): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes a previous call to purple_credential_provider_read_password_async().
    *
    @@ -203,7 +203,7 @@
    * @provider: The #PurpleCredentialProvider instance.
    * @result: The #GAsyncResult from the previous
    * purple_credential_provider_write_password_async() call.
    - * @error: (out) (optional) (nullable): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes a previous call to
    * purple_credential_provider_write_password_async().
    @@ -235,7 +235,7 @@
    * @provider: The #PurpleCredentialProvider instance.
    * @result: The #GAsyncResult from the previous
    * purple_credential_provider_clear_password_async() call.
    - * @error: (out) (optional) (nullable): Return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes a previous call to
    * purple_credential_provider_clear_password_async().
    --- a/libpurple/purpleprotocolmanager.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/purpleprotocolmanager.h Fri Nov 04 00:20:18 2022 -0500
    @@ -78,7 +78,7 @@
    * purple_protocol_manager_register:
    * @manager: The #PurpleProtocolManager instance.
    * @protocol: The #PurpleProtocol to register.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Registers @protocol with @manager.
    *
    @@ -93,7 +93,7 @@
    * purple_protocol_manager_unregister:
    * @manager: The #PurpleProtocolManager instance.
    * @protocol: The #PurpleProtocol to unregister.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Unregisters @protocol from @manager.
    *
    --- a/libpurple/purplesqlite3.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/purplesqlite3.h Fri Nov 04 00:20:18 2022 -0500
    @@ -58,7 +58,7 @@
    /**
    * purple_sqlite3_get_schema_version:
    * @db: The sqlite3 connection.
    - * @error: (nullable): A return address for a [type@GLib.Error].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Attempts to read the result of `PRAGMA user_version` which this API uses to
    * store the schema version.
    @@ -74,7 +74,7 @@
    * @db: The sqlite3 connection.
    * @migrations: (array zero-terminated=1): A list of SQL statements, each item
    * being its own migration.
    - * @error: (nullable): A return address for a [type@GLib.Error].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Runs the given migrations in the order they are given. The index of each
    * migration plus 1 is assumed is to be the version number of the migration,
    @@ -116,7 +116,7 @@
    * @path: The base path in @resource to use.
    * @migrations: (array zero-terminated=1): The list of migrations in the order
    * to run them.
    - * @error: (nullable): A return address for a [type@GLib.Error].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Runs the given migrations in the order they are given. The index of each
    * migration plus 1 is assumed to be the version number of the migration, which
    --- a/libpurple/purpleui.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/purpleui.h Fri Nov 04 00:20:18 2022 -0500
    @@ -159,7 +159,7 @@
    /**
    * purple_ui_start:
    * @ui: The instance.
    - * @error: (optional) (nullable): A return address for a [type@GLib.GError].
    + * @error: Return address for a #GError, or %NULL.
    *
    * Tells @ui that libpurple is done initializing and that @ui should continue
    * its initialization.
    --- a/libpurple/purplewhiteboardmanager.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/purplewhiteboardmanager.h Fri Nov 04 00:20:18 2022 -0500
    @@ -78,7 +78,7 @@
    * purple_whiteboard_manager_register:
    * @manager: The #PurpleWhiteboardManager instance.
    * @whiteboard: The #PurpleWhiteboard to register.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Registers @whiteboard with @manager.
    *
    @@ -93,7 +93,7 @@
    * purple_whiteboard_manager_unregister:
    * @manager: The #PurpleWhiteboardManager instance.
    * @whiteboard: The #PurpleWhiteboard to unregister.
    - * @error: (out) (optional) (nullable): A return address for a #GError.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Unregisters @whiteboard from @manager.
    *
    --- a/libpurple/queuedoutputstream.h Thu Nov 03 22:53:41 2022 -0500
    +++ b/libpurple/queuedoutputstream.h Fri Nov 04 00:20:18 2022 -0500
    @@ -88,8 +88,7 @@
    * purple_queued_output_stream_push_bytes_finish:
    * @stream: The instance.
    * @result: The [iface@Gio.AsyncResult] of this operation.
    - * @error: (nullable): A [type@Glib.Error] location to store the error, or
    - * %NULL to ignore.
    + * @error: Return address for a #GError, or %NULL.
    *
    * Finishes pushing bytes asynchronously.
    *