/pidgin/main: 65c1912ee2c8: Add (scope) annotation to callback p...
Ankit Vani
a at nevitus.org
Wed Apr 2 23:56:39 EDT 2014
Changeset: 65c1912ee2c8f6f338c602ae20ca273286a6fc8a
Author: Ankit Vani <a at nevitus.org>
Date: 2014-04-03 09:26 +0530
Branch: default
URL: https://hg.pidgin.im/pidgin/main/rev/65c1912ee2c8
Description:
Add (scope) annotation to callback parameters (account.h to proxy.h)
diffstat:
libpurple/account.h | 41 +++++++++++++------------
libpurple/certificate.h | 26 ++++++++--------
libpurple/cmds.h | 65 ++++++++++++++++++++--------------------
libpurple/dnsquery.h | 2 +-
libpurple/dnssrv.h | 20 ++++++------
libpurple/e2ee.h | 2 +-
libpurple/eventloop.h | 16 ++++-----
libpurple/http.h | 30 +++++++++---------
libpurple/keyring.h | 78 +++++++++++++++++++++++++++++++++++++-----------
libpurple/network.h | 58 ++++++++++++++++++------------------
libpurple/notify.h | 41 +++++++++++++------------
libpurple/plugin.h | 5 +-
libpurple/pounce.h | 2 +-
libpurple/prefs.h | 2 +-
libpurple/proxy.h | 48 +++++++++++++++---------------
15 files changed, 240 insertions(+), 196 deletions(-)
diffs (truncated from 882 to 300 lines):
diff --git a/libpurple/account.h b/libpurple/account.h
--- a/libpurple/account.h
+++ b/libpurple/account.h
@@ -160,9 +160,9 @@ void purple_account_connect(PurpleAccoun
/**
* purple_account_set_register_callback:
- * @account: The account for which this callback should be used
- * @cb: The callback
- * @user_data: The user data passed to the callback
+ * @account: The account for which this callback should be used
+ * @cb: (scope call): The callback
+ * @user_data: The user data passed to the callback
*
* Sets the callback for successful registration.
*/
@@ -189,8 +189,9 @@ void purple_account_register_completed(P
/**
* purple_account_unregister:
* @account: The account to unregister.
- * @cb: Optional callback to be called when unregistration is complete
- * @user_data: user data to pass to the callback
+ * @cb: (scope call): Optional callback to be called when unregistration is
+ * complete
+ * @user_data: user data to pass to the callback
*
* Unregisters an account (deleting it from the server).
*/
@@ -260,8 +261,8 @@ void purple_account_request_add(PurpleAc
* @alias: The optional alias of the remote user.
* @message: The optional message sent by the user wanting to add you.
* @on_list: Is the remote user already on the buddy list?
- * @auth_cb: The callback called when the local user accepts
- * @deny_cb: The callback called when the local user rejects
+ * @auth_cb: (scope call): The callback called when the local user accepts
+ * @deny_cb: (scope call): The callback called when the local user rejects
* @user_data: Data to be passed back to the above callbacks
*
* Notifies the user that a remote user has wants to add the local user
@@ -295,8 +296,8 @@ void purple_account_request_close(void *
/**
* purple_account_request_password:
* @account: The account to request the password for.
- * @ok_cb: The callback for the OK button.
- * @cancel_cb: The callback for the cancel button.
+ * @ok_cb: (scope call): The callback for the OK button.
+ * @cancel_cb: (scope call): The callback for the cancel button.
* @user_data: User data to be passed into callbacks.
*
* Requests a password from the user for the account. Does not set the
@@ -335,7 +336,7 @@ void purple_account_set_username(PurpleA
* purple_account_set_password:
* @account: The account.
* @password: The password.
- * @cb: A callback for once the password is saved.
+ * @cb: (scope call): A callback for once the password is saved.
* @data: A pointer to be passed to the callback.
*
* Sets the account's password.
@@ -494,12 +495,12 @@ void purple_account_set_status_list(Purp
* purple_account_set_public_alias:
* @account: The account
* @alias: The new public alias for this account or %NULL
- * to unset the alias/nickname (or return it to
- * a protocol-specific "default", like the username)
- * @success_cb: A callback which will be called if the alias
- * is successfully set on the server (or %NULL).
- * @failure_cb: A callback which will be called if the alias
- * is not successfully set on the server (or %NULL).
+ * to unset the alias/nickname (or return it to
+ * a protocol-specific "default", like the username)
+ * @success_cb: (scope call): A callback which will be called if the alias
+ * is successfully set on the server (or %NULL).
+ * @failure_cb: (scope call): A callback which will be called if the alias
+ * is not successfully set on the server (or %NULL).
*
* Set a server-side (public) alias for this account. The account
* must already be connected.
@@ -514,9 +515,9 @@ void purple_account_set_public_alias(Pur
/**
* purple_account_get_public_alias:
* @account: The account
- * @success_cb: A callback which will be called with the alias
- * @failure_cb: A callback which will be called if the protocol is
- * unable to retrieve the server-side alias.
+ * @success_cb: (scope call): A callback which will be called with the alias
+ * @failure_cb: (scope call): A callback which will be called if the protocol is
+ * unable to retrieve the server-side alias.
*
* Fetch the server-side (public) alias for this account. The account
* must already be connected.
@@ -694,7 +695,7 @@ const char *purple_account_get_username(
/**
* purple_account_get_password:
* @account: The account.
- * @cb: The callback to give the password.
+ * @cb: (scope call): The callback to give the password.
* @data: A pointer passed to the callback.
*
* Reads the password for the account.
diff --git a/libpurple/certificate.h b/libpurple/certificate.h
--- a/libpurple/certificate.h
+++ b/libpurple/certificate.h
@@ -363,19 +363,19 @@ G_BEGIN_DECLS
/**
* purple_certificate_verify:
- * @verifier: Verification logic to use.
- * See purple_certificate_find_verifier().
- * @subject_name: Name that should match the first certificate in the
- * chain for the certificate to be valid. Will be strdup'd
- * into the Request struct
- * @cert_chain: Certificate chain to check. If there is more than one
- * certificate in the chain (X.509), the peer's
- * certificate comes first, then the issuer/signer's
- * certificate, etc. The whole list is duplicated into the
- * Request struct.
- * @cb: Callback function to be called with whether the
- * certificate was approved or not.
- * @cb_data: User-defined data for the above.
+ * @verifier: Verification logic to use.
+ * See purple_certificate_find_verifier().
+ * @subject_name: Name that should match the first certificate in the
+ * chain for the certificate to be valid. Will be strdup'd
+ * into the Request struct
+ * @cert_chain: Certificate chain to check. If there is more than one
+ * certificate in the chain (X.509), the peer's
+ * certificate comes first, then the issuer/signer's
+ * certificate, etc. The whole list is duplicated into the
+ * Request struct.
+ * @cb: (scope call): Callback function to be called with whether the
+ * certificate was approved or not.
+ * @cb_data: User-defined data for the above.
*
* Constructs a verification request and passed control to the specified Verifier
*
diff --git a/libpurple/cmds.h b/libpurple/cmds.h
--- a/libpurple/cmds.h
+++ b/libpurple/cmds.h
@@ -131,46 +131,47 @@ G_BEGIN_DECLS
* @cmd: The command. This should be a UTF-8 (or ASCII) string, with no spaces
* or other white space.
* @args: A string of characters describing to libpurple how to parse this
- * command's arguments. If what the user types doesn't match this
- * pattern, libpurple will keep looking for another command, unless
- * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @f.
- * This string should contain no whitespace, and use a single
- * character for each argument. The recognized characters are:
- * <itemizedlist>
- * <listitem><literal>'w'</literal>: Matches a single word.</listitem>
- * <listitem><literal>'W'</literal>: Matches a single word, with
- * formatting.</listitem>
- * <listitem><literal>'s'</literal>: Matches the rest of the
- * arguments after this point,
- * as a single string.</listitem>
- * <listitem><literal>'S'</literal>: Same as <literal>'s'</literal>
- * but with formatting.</listitem>
- * </itemizedlist>
- * If args is the empty string, then the command accepts no
- * arguments. The args passed to the callback @func will be a %NULL
- * terminated array of %NULL terminated strings, and will always
- * match the number of arguments asked for, unless
- * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
+ * command's arguments. If what the user types doesn't match this
+ * pattern, libpurple will keep looking for another command, unless
+ * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @f.
+ * This string should contain no whitespace, and use a single
+ * character for each argument. The recognized characters are:
+ * <itemizedlist>
+ * <listitem><literal>'w'</literal>: Matches a single word.</listitem>
+ * <listitem><literal>'W'</literal>: Matches a single word, with
+ * formatting.</listitem>
+ * <listitem><literal>'s'</literal>: Matches the rest of the
+ * arguments after this point,
+ * as a single string.</listitem>
+ * <listitem><literal>'S'</literal>: Same as <literal>'s'</literal>
+ * but with formatting.</listitem>
+ * </itemizedlist>
+ * If args is the empty string, then the command accepts no
+ * arguments. The args passed to the callback @func will be a %NULL
+ * terminated array of %NULL terminated strings, and will always
+ * match the number of arguments asked for, unless
+ * #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed.
* @p: This is the priority. Higher priority commands will be run first,
- * and usually the first command will stop any others from being
- * called.
+ * and usually the first command will stop any others from being
+ * called.
* @f: Flags specifying various options about this command, combined with
- * <literal>|</literal> (bitwise OR). You need to at least pass one of
- * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
- * order for the command to ever actually be called.
+ * <literal>|</literal> (bitwise OR). You need to at least pass one of
+ * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in
+ * order for the command to ever actually be called.
* @protocol_id: If the #PURPLE_CMD_FLAG_PRPL_ONLY flag is set, this is the id
* of the protocol to which the command applies (such as
* <literal>"prpl-msn"</literal>). If the flag is not set, this
* parameter is ignored; pass %NULL (or a humourous string of
* your choice!).
- * @func: This is the function to call when someone enters this command.
+ * @func: (scope call): This is the function to call when someone enters this
+ * command.
* @helpstr: a whitespace sensitive, UTF-8, HTML string describing how to
- * use the command. The preferred format of this string is the
- * command's name, followed by a space and any arguments it
- * accepts (if it takes any arguments, otherwise no space),
- * followed by a colon, two spaces, and a description of the
- * command in sentence form. Do not include a slash before the
- * command name.
+ * use the command. The preferred format of this string is the
+ * command's name, followed by a space and any arguments it
+ * accepts (if it takes any arguments, otherwise no space),
+ * followed by a colon, two spaces, and a description of the
+ * command in sentence form. Do not include a slash before the
+ * command name.
* @data: User defined data to pass to the #PurpleCmdFunc @f.
*
* Register a new command with the core.
diff --git a/libpurple/dnsquery.h b/libpurple/dnsquery.h
--- a/libpurple/dnsquery.h
+++ b/libpurple/dnsquery.h
@@ -115,7 +115,7 @@ GType purple_dnsquery_ui_ops_get_type(vo
* @account: The account that the query is being done for (or NULL)
* @hostname: The hostname to resolve.
* @port: A port number which is stored in the struct sockaddr.
- * @callback: The callback function to call after resolving.
+ * @callback: (scope call): The callback function to call after resolving.
* @data: Extra data to pass to the callback function.
*
* Perform an asynchronous DNS query.
diff --git a/libpurple/dnssrv.h b/libpurple/dnssrv.h
--- a/libpurple/dnssrv.h
+++ b/libpurple/dnssrv.h
@@ -114,34 +114,34 @@ GType purple_srv_txt_query_ui_ops_get_ty
/**
* purple_srv_resolve:
- * @account: The account that the query is being done for (or NULL)
+ * @account: The account that the query is being done for (or %NULL)
* @protocol: Name of the protocol (e.g. "sip")
* @transport: Name of the transport ("tcp" or "udp")
* @domain: Domain name to query (e.g. "blubb.com")
- * @cb: A callback which will be called with the results
+ * @cb: (scope call): A callback which will be called with the results
* @extradata: Extra data to be passed to the callback
*
* Queries an SRV record.
*
- * Returns: NULL if there was an error, otherwise return a reference to
- * a data structure that can be used to cancel the pending
- * DNS query, if needed.
+ * Returns: %NULL if there was an error, otherwise return a reference to
+ * a data structure that can be used to cancel the pending
+ * DNS query, if needed.
*/
PurpleSrvTxtQueryData *purple_srv_resolve(PurpleAccount *account, const char *protocol, const char *transport, const char *domain, PurpleSrvCallback cb, gpointer extradata);
/**
* purple_txt_resolve:
- * @account: The account that the query is being done for (or NULL)
+ * @account: The account that the query is being done for (or %NULL)
* @owner: Name of the protocol (e.g. "_xmppconnect")
* @domain: Domain name to query (e.g. "blubb.com")
- * @cb: A callback which will be called with the results
+ * @cb: (scope call): A callback which will be called with the results
* @extradata: Extra data to be passed to the callback
*
* Queries an TXT record.
*
- * Returns: NULL if there was an error, otherwise return a reference to
- * a data structure that can be used to cancel the pending
- * DNS query, if needed.
+ * Returns: %NULL if there was an error, otherwise return a reference to
+ * a data structure that can be used to cancel the pending
+ * DNS query, if needed.
*/
PurpleSrvTxtQueryData *purple_txt_resolve(PurpleAccount *account, const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
diff --git a/libpurple/e2ee.h b/libpurple/e2ee.h
--- a/libpurple/e2ee.h
+++ b/libpurple/e2ee.h
@@ -216,7 +216,7 @@ purple_e2ee_provider_get_name(PurpleE2ee
/**
* purple_e2ee_provider_set_conv_menu_cb:
* @provider: The E2EE provider.
- * @conv_menu_cb: The callback.
+ * @conv_menu_cb: (scope call): The callback.
*
* Sets the conversation menu callback for the E2EE provider.
*
diff --git a/libpurple/eventloop.h b/libpurple/eventloop.h
--- a/libpurple/eventloop.h
+++ b/libpurple/eventloop.h
@@ -158,10 +158,9 @@ G_BEGIN_DECLS
/**
* purple_timeout_add:
- * @interval: The time between calls of the function, in
- * milliseconds.
More information about the Commits
mailing list