pidgin/pidgin

Add a bunch of missing docs.

2019-12-19, Elliott Sales de Andrade
056a71665e06
Parents 7a330cab3546
Children 2a80cd63e914
Add a bunch of missing docs.
7 files changed, 123 insertions(+), 41 deletions(-)
  • +4 -0
    libpurple/attention.h
  • +5 -0
    libpurple/buddyicon.h
  • +6 -0
    libpurple/buddylist.h
  • +14 -8
    libpurple/connection.h
  • +11 -11
    libpurple/core.h
  • +5 -0
    libpurple/debug.h
  • +78 -22
    libpurple/notify.h
    • --- 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), \