Mercurial > pidgin3 / changeset

changeset

Fix error parameter annotations

Fri, 04 Nov 2022 00:20:18 -0500

author
Elliott Sales de Andrade <quantum.analyst@gmail.com>
date
Fri, 04 Nov 2022 00:20:18 -0500
changeset 41881
7e1dd7e9efbb
parent 41880
4371fa2ce648
child 41882
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/

libpurple/buddyicon.h file | annotate | diff | comparison | revisions
libpurple/connection.h file | annotate | diff | comparison | revisions
libpurple/core.h file | annotate | diff | comparison | revisions
libpurple/image.h file | annotate | diff | comparison | revisions
libpurple/protocols/ircv3/purpleircv3parser.h file | annotate | diff | comparison | revisions
libpurple/purplecredentialmanager.h file | annotate | diff | comparison | revisions
libpurple/purplecredentialprovider.h file | annotate | diff | comparison | revisions
libpurple/purpleprotocolmanager.h file | annotate | diff | comparison | revisions
libpurple/purplesqlite3.h file | annotate | diff | comparison | revisions
libpurple/purpleui.h file | annotate | diff | comparison | revisions
libpurple/purplewhiteboardmanager.h file | annotate | diff | comparison | revisions
libpurple/queuedoutputstream.h file | annotate | diff | comparison | revisions 
--- 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.
  *

Mercurial Repository: pidgin3

mercurial