pidgin/pidgin

Add a bunch of missing docs.

14 months ago, Elliott Sales de Andrade
056a71665e06
Parents 7a330cab3546
Children 2a80cd63e914
Add a bunch of missing docs.
--- a/libpurple/attention.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/attention.h Thu Dec 19 02:32:25 2019 -0500
@@ -198,6 +198,10 @@
/**
* PurpleProtocolAttentionInterface:
+ * @send: Called to send an attention message. See
+ * purple_protocol_attention_send().
+ * @get_types: Called to list the protocol's attention types. See
+ * purple_protocol_attention_get_types().
*
* The protocol attention interface.
*
--- a/libpurple/buddyicon.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/buddyicon.h Thu Dec 19 02:32:25 2019 -0500
@@ -488,6 +488,11 @@
/**
* purple_buddy_icon_spec_get_scaled_size:
+ * @spec: The buddy icon spec.
+ * @width: (inout): On input, the suggested width. On output, the width
+ * constrained by the spec.
+ * @height: (inout): On input, the suggested height. On output, the height
+ * constrained by the spec.
*
* Gets display size for a buddy icon
*/
--- a/libpurple/buddylist.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/buddylist.h Thu Dec 19 02:32:25 2019 -0500
@@ -68,6 +68,12 @@
* @update: This will update a node in the buddy list.
* @remove: This removes a node from the list
* @set_visible: Hides or unhides the buddy list.
+ * @request_add_buddy: Called when information is needed to add a buddy to the
+ * buddy list. See purple_blist_request_add_buddy().
+ * @request_add_chat: Called when information is needed to add a chat to the
+ * buddy list. See purple_blist_request_add_chat().
+ * @request_add_group: Called when information is needed to add a group to the
+ * buddy list. See purple_blist_request_add_group().
* @save_node: This is called when a node has been modified and should be
* saved.
* <sbr/>Implementation of this method is
--- a/libpurple/connection.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/connection.h Thu Dec 19 02:32:25 2019 -0500
@@ -363,7 +363,7 @@
/**
* purple_connection_is_disconnecting:
- * @param gc The connection.
+ * @gc: The connection.
*
* Checks, if connection is in disconnecting state.
*
@@ -487,6 +487,8 @@
/**
* purple_connection_ssl_error:
+ * @gc: The connection.
+ * @ssl_error: The SSL error type.
*
* Closes a connection due to an SSL error; this is basically a shortcut to
* turning the #PurpleSslErrorType into a #PurpleConnectionError and a
@@ -531,18 +533,22 @@
/**
* purple_connection_error_is_fatal:
+ * @reason: The connection error to check.
*
* Reports whether a disconnection reason is fatal (in which case the account
* should probably not be automatically reconnected) or transient (so
* auto-reconnection is a good idea).
+ *
* For instance, #PURPLE_CONNECTION_ERROR_NETWORK_ERROR is a temporary error,
- * which might be caused by losing the network connection, so <literal>
- * purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_NETWORK_ERROR)</literal>
- * is %FALSE. On the other hand,
- * #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED probably indicates a
- * misconfiguration of the account which needs the user to go fix it up, so
- * <literal> purple_connection_error_is_fatal
- * (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)</literal> is %TRUE.
+ * which might be caused by losing the network connection, so <code>
+ * purple_connection_error_is_fatal(PURPLE_CONNECTION_ERROR_NETWORK_ERROR)
+ * </code> is %FALSE.
+ *
+ * On the other hand, #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED probably
+ * indicates a misconfiguration of the account which needs the user to go fix
+ * it up, so <code>
+ * purple_connection_error_is_fatal(PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)
+ * </code> is %TRUE.
*
* Returns: %TRUE if the account should not be automatically reconnected, and
* %FALSE otherwise.
--- a/libpurple/core.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/core.h Thu Dec 19 02:32:25 2019 -0500
@@ -107,22 +107,22 @@
/**
* purple_core_quit_cb:
+ * @unused: This argument is for consistency with a timeout callback. It is
+ * otherwise unused.
*
- * Calls purple_core_quit(). This can be used as the function
- * passed to g_timeout_add() when you want to shutdown Purple
- * in a specified amount of time. When shutting down Purple
- * from a plugin, you must use this instead of purple_core_quit();
- * for an immediate exit, use a timeout value of 0:
+ * Calls purple_core_quit(). This can be used as the function passed to
+ * g_timeout_add() when you want to shutdown Purple in a specified amount of
+ * time. When shutting down Purple from a plugin, you must use this instead of
+ * purple_core_quit(); for an immediate exit, use a timeout value of 0:
*
* <programlisting>
- * g_timeout_add(0, purple_core_quitcb, NULL)
+ * g_timeout_add(0, purple_core_quit_cb, NULL)
* </programlisting>
*
- * This is ensures that code from your plugin is not being
- * executed when purple_core_quit() is called. If the plugin
- * called purple_core_quit() directly, you would get a core dump
- * after purple_core_quit() executes and control returns to your
- * plugin because purple_core_quit() frees all plugins.
+ * This ensures that code from your plugin is not being executed when
+ * purple_core_quit() is called. If the plugin called purple_core_quit()
+ * directly, you would get a core dump after purple_core_quit() executes and
+ * control returns to your plugin because purple_core_quit() frees all plugins.
*/
gboolean purple_core_quit_cb(gpointer unused);
--- a/libpurple/debug.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/debug.h Thu Dec 19 02:32:25 2019 -0500
@@ -62,13 +62,18 @@
/**
* PurpleDebugUiInterface:
+ * @print: Called to output a debug string to the UI.
+ * @is_enabled: Returns if debug printing is enabled in the UI for a @level and
+ * @category.
*
* Debug UI operations.
*/
struct _PurpleDebugUiInterface
{
+ /*< private >*/
GTypeInterface parent_iface;
+ /*< public >*/
void (*print)(PurpleDebugUi *self,
PurpleDebugLevel level, const char *category,
const char *arg_s);
--- a/libpurple/notify.h Thu Dec 19 00:51:06 2019 -0500
+++ b/libpurple/notify.h Thu Dec 19 02:32:25 2019 -0500
@@ -182,9 +182,19 @@
char *label;
};
-
/**
* PurpleNotifyUiOps:
+ * @notify_message: UI op for purple_notify_message().
+ * @notify_email: UI op for purple_notify_email().
+ * @notify_emails: UI op for purple_notify_emails().
+ * @notify_formatted: UI op for purple_notify_formatted().
+ * @notify_searchresults: UI op for purple_notify_searchresults().
+ * @notify_searchresults_new_rows: UI op for
+ * purple_notify_searchresults_new_rows().
+ * @notify_userinfo: UI op for purple_notify_userinfo().
+ * @notify_uri: UI op for purple_notify_uri().
+ * @close_notify: UI op for purple_notify_close() and
+ * purple_notify_close_with_handle().
*
* Notification UI operations.
*/
@@ -562,45 +572,72 @@
/**
* purple_notify_user_info_add_pair_html:
- * @user_info: The PurpleNotifyUserInfo
- * @label: A label, which for example might be displayed by a
- * UI with a colon after it ("Status:"). Do not include
- * a colon. If NULL, value will be displayed without a
- * label.
- * @value: The value, which might be displayed by a UI after
- * the label. This should be valid HTML. If you want
- * to insert plaintext then use
- * purple_notify_user_info_add_pair_plaintext(), instead.
- * If this is NULL the label will still be displayed;
- * the UI should treat label as independent and not
- * include a colon if it would otherwise.
+ * @user_info: The PurpleNotifyUserInfo
+ * @label: A label, which for example might be displayed by a UI with a colon
+ * after it ("Status:"). Do not include a colon. If %NULL, value will be
+ * displayed without a label.
+ * @value: The value, which might be displayed by a UI after the label. This
+ * should be valid HTML. If you want to insert plaintext then use
+ * purple_notify_user_info_add_pair_plaintext(), instead. If this is
+ * %NULL the label will still be displayed; the UI should treat label as
+ * independent and not include a colon if it would otherwise.
*
- * Add a label/value pair to a PurpleNotifyUserInfo object.
- * PurpleNotifyUserInfo keeps track of the order in which pairs are added.
+ * Add a label/value pair to a #PurpleNotifyUserInfo object.
+ * #PurpleNotifyUserInfo keeps track of the order in which pairs are added.
*/
void purple_notify_user_info_add_pair_html(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_add_pair_plaintext:
+ * @user_info: The PurpleNotifyUserInfo
+ * @label: A label, which for example might be displayed by a UI with a colon
+ * after it ("Status:"). Do not include a colon. If %NULL, value will be
+ * displayed without a label.
+ * @value: The value, which might be displayed by a UI after the label. This
+ * will be escaped to produce valid HTML. If you want to insert HTML
+ * then use purple_notify_user_info_add_pair_html(), instead. If this is
+ * %NULL the label will still be displayed; the UI should treat label as
+ * independent and not include a colon if it would otherwise.
*
- * Like purple_notify_user_info_add_pair_html, but value should be plaintext
+ * Add a label/value pair to a #PurpleNotifyUserInfo object.
+ * #PurpleNotifyUserInfo keeps track of the order in which pairs are added.
+ *
+ * Like purple_notify_user_info_add_pair_html(), but value should be plaintext
* and will be escaped using g_markup_escape_text().
*/
void purple_notify_user_info_add_pair_plaintext(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_prepend_pair_html:
+ * @user_info: The PurpleNotifyUserInfo
+ * @label: A label, which for example might be displayed by a UI with a colon
+ * after it ("Status:"). Do not include a colon. If %NULL, value will be
+ * displayed without a label.
+ * @value: The value, which might be displayed by a UI after the label. This
+ * should be valid HTML. If you want to insert plaintext then use
+ * purple_notify_user_info_prepend_pair_plaintext(), instead. If this is
+ * %NULL the label will still be displayed; the UI should treat label as
+ * independent and not include a colon if it would otherwise.
*
- * Like purple_notify_user_info_add_pair_html, but the pair is inserted
+ * Like purple_notify_user_info_add_pair_html(), but the pair is inserted
* at the beginning of the list.
*/
void purple_notify_user_info_prepend_pair_html(PurpleNotifyUserInfo *user_info, const char *label, const char *value);
/**
* purple_notify_user_info_prepend_pair_plaintext:
+ * @user_info: The PurpleNotifyUserInfo
+ * @label: A label, which for example might be displayed by a UI with a colon
+ * after it ("Status:"). Do not include a colon. If %NULL, value will be
+ * displayed without a label.
+ * @value: The value, which might be displayed by a UI after the label. This
+ * will be escaped to produce valid HTML. If you want to insert HTML
+ * then use purple_notify_user_info_prepend_pair_html(), instead. If
+ * this is %NULL the label will still be displayed; the UI should treat
+ * label as independent and not include a colon if it would otherwise.
*
- * Like purple_notify_user_info_prepend_pair_html, but value should be plaintext
- * and will be escaped using g_markup_escape_text().
+ * Like purple_notify_user_info_prepend_pair_html(), but value should be
+ * plaintext and will be escaped using g_markup_escape_text().
*
* Since: 3.0.0
*/
@@ -688,6 +725,7 @@
/**
* purple_notify_user_info_remove_last_item:
+ * @user_info: The PurpleNotifyUserInfo
*
* Remove the last item which was added to a PurpleNotifyUserInfo. This
* could be used to remove a section header which is not needed.
@@ -802,8 +840,14 @@
/**
* purple_notify_info:
+ * @handle: The plugin or connection handle.
+ * @title: The title of the message.
+ * @primary: The main point of the message.
+ * @secondary: The secondary information.
+ * @cpar: The #PurpleRequestCommonParameters associated with this request, or
+ * %NULL if none is.
*
- * A wrapper for purple_notify_message that displays an information message.
+ * A wrapper for purple_notify_message() that displays an information message.
*/
#define purple_notify_info(handle, title, primary, secondary, cpar) \
purple_notify_message((handle), PURPLE_NOTIFY_MSG_INFO, (title), \
@@ -811,8 +855,14 @@
/**
* purple_notify_warning:
+ * @handle: The plugin or connection handle.
+ * @title: The title of the message.
+ * @primary: The main point of the message.
+ * @secondary: The secondary information.
+ * @cpar: The #PurpleRequestCommonParameters associated with this request, or
+ * %NULL if none is.
*
- * A wrapper for purple_notify_message that displays a warning message.
+ * A wrapper for purple_notify_message() that displays a warning message.
*/
#define purple_notify_warning(handle, title, primary, secondary, cpar) \
purple_notify_message((handle), PURPLE_NOTIFY_MSG_WARNING, (title), \
@@ -820,8 +870,14 @@
/**
* purple_notify_error:
+ * @handle: The plugin or connection handle.
+ * @title: The title of the message.
+ * @primary: The main point of the message.
+ * @secondary: The secondary information.
+ * @cpar: The #PurpleRequestCommonParameters associated with this request, or
+ * %NULL if none is.
*
- * A wrapper for purple_notify_message that displays an error message.
+ * A wrapper for purple_notify_message() that displays an error message.
*/
#define purple_notify_error(handle, title, primary, secondary, cpar) \
purple_notify_message((handle), PURPLE_NOTIFY_MSG_ERROR, (title), \