pidgin/pidgin

Clean up a bunch doc issues.

2020-11-19, Gary Kramlich
55230eededd8
Parents f2f4d445ff7b
Children 4c3a1b5aef6b
Clean up a bunch doc issues.

Testing Done:
Built the docs a million times verifying the fixes.

Reviewed at https://reviews.imfreedom.org/r/229/
13 files changed, 51 insertions(+), 69 deletions(-)
  • +1 -0
    doc/reference/libpurple/meson.build
  • +0 -1
    doc/reference/libpurple/ui_ops.xml
  • +2 -2
    libpurple/account.h
  • +1 -1
    libpurple/core.h
  • +1 -1
    libpurple/media-gst.h
  • +5 -7
    libpurple/network.h
  • +4 -14
    libpurple/purple.h.in
  • +0 -7
    libpurple/purpleattentiontype.h
  • +2 -2
    libpurple/purplecredentialmanager.h
  • +2 -2
    libpurple/purpleimconversation.h
  • +1 -1
    libpurple/purpleprotocolattention.h
  • +0 -31
    libpurple/status.c
  • +32 -0
    libpurple/status.h
    • --- a/doc/reference/libpurple/meson.build Tue Nov 17 22:05:15 2020 -0600
    +++ b/doc/reference/libpurple/meson.build Thu Nov 19 20:07:44 2020 -0600
    @@ -11,6 +11,7 @@
    'backend-fs2.h',
    'glibcompat.h',
    'internal.h',
    + 'purple.h',
    'purpleprivate.h',
    ]
    --- a/doc/reference/libpurple/ui_ops.xml Tue Nov 17 22:05:15 2020 -0600
    +++ b/doc/reference/libpurple/ui_ops.xml Thu Nov 19 20:07:44 2020 -0600
    @@ -19,7 +19,6 @@
    <listitem><link linkend="PurpleNotifyUiOps"><literal>PurpleNotifyUiOps</literal></link></listitem>
    <listitem><link linkend="PurpleRequestUiOps"><literal>PurpleRequestUiOps</literal></link></listitem>
    <listitem><link linkend="PurpleRoomlistUiOps"><literal>PurpleRoomlistUiOps</literal></link></listitem>
    -<listitem><link linkend="PurpleSoundUiOps"><literal>PurpleSoundUiOps</literal></link></listitem>
    <listitem><link linkend="PurpleWhiteboardUiOps"><literal>PurpleWhiteboardUiOps</literal></link></listitem>
    <listitem><link linkend="PurpleXferUiOps"><literal>PurpleXferUiOps</literal></link></listitem>
    </itemizedlist>
    --- a/libpurple/account.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/account.h Thu Nov 19 20:07:44 2020 -0600
    @@ -442,14 +442,14 @@
    * <literal>"message"</literal> followed by
    * <literal>"hello, talk to me!"</literal>.)
    *
    - * Variadic version of purple_account_set_status_list().
    + * Variadic version of purple_account_set_status_attrs().
    */
    void purple_account_set_status(PurpleAccount *account, const char *status_id,
    gboolean active, ...) G_GNUC_NULL_TERMINATED;
    /**
    - * purple_account_set_status_list:
    + * purple_account_set_status_attrs:
    * @account: The account.
    * @status_id: The ID of the status.
    * @active: Whether @a status_id is to be activated (%TRUE) or
    --- a/libpurple/core.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/core.h Thu Nov 19 20:07:44 2020 -0600
    @@ -55,7 +55,7 @@
    * during their initialization.
    * @ui_init: Called after all of libpurple has been initialized. The UI
    * should use this hook to set all other necessary
    - * <link linkend="chapter-ui-ops"><literal>UiOps structures</literal></link>.
    + * <link linkend="chapter-ui-ops"><literal>UiOps structures</literal></link>.
    * @quit: Called after most of libpurple has been uninitialized.
    * @get_ui_info: Called by purple_core_get_ui_info(); should return the
    * information documented there.
    --- a/libpurple/media-gst.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/media-gst.h Thu Nov 19 20:07:44 2020 -0600
    @@ -232,7 +232,7 @@
    *
    * Returns current set of media formats limiting the output from video source.
    *
    - * Returns: #GstCaps limiting the video source's formats.
    + * Returns: GstCaps limiting the video source's formats.
    */
    GstCaps *purple_media_manager_get_video_caps(PurpleMediaManager *manager);
    --- a/libpurple/network.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/network.h Thu Nov 19 20:07:44 2020 -0600
    @@ -126,14 +126,12 @@
    * purple_network_get_my_ip_from_gio:
    * @sockconn: The socket connection to use to help figure out the IP, or %NULL.
    *
    - * Returns the IP address that should be used anywhere a
    - * public IP addresses is needed (listening for an incoming
    - * file transfer, etc).
    + * Returns the IP address that should be used anywhere a public IP address is
    + * needed (listening for an incoming file transfer, etc).
    *
    - * If the user has manually specified an IP address via
    - * preferences, then this IP is returned. Otherwise the
    - * IP address returned by purple_network_get_local_system_ip_from_gio()
    - * is returned.
    + * If the user has manually specified an IP address via preferences, then this
    + * IP is returned. Otherwise STUN, UPNP, NAT-PMP, and finally GIO will be
    + * attempted to discover the local IP address depending on what's available.
    *
    * Returns: The local IP address to be used.
    */
    --- a/libpurple/purple.h.in Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/purple.h.in Thu Nov 19 20:07:44 2020 -0600
    @@ -1,4 +1,6 @@
    -/* purple
    +/*
    + * Purple - Internet Messaging Library
    + * Copyright (C) Pidgin Developers <devel@pidgin.im>
    *
    * Purple is the legal property of its developers, whose names are too numerous
    * to list here. Please refer to the COPYRIGHT file distributed with this
    @@ -15,23 +17,11 @@
    * GNU General Public License for more details.
    *
    * You should have received a copy of the GNU General Public License
    - * along with this program; if not, write to the Free Software
    - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
    + * along with this program; if not, see <https://www.gnu.org/licenses/>.
    */
    #ifndef PURPLE_PURPLE_H
    #define PURPLE_PURPLE_H
    -/**
    - * SECTION:purple
    - * @section_id: libpurple-purple
    - * @short_description: <filename>purple.h</filename>
    - * @title: Header files and defines
    - *
    - * This file contains all the necessary preprocessor directives to include
    - * libpurple's headers and other preprocessor directives required for plugins
    - * or UIs to build. Including this file eliminates the need to directly
    - * include any other libpurple files.
    - */
    #include <glib.h>
    --- a/libpurple/purpleattentiontype.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/purpleattentiontype.h Thu Nov 19 20:07:44 2020 -0600
    @@ -49,13 +49,6 @@
    G_BEGIN_DECLS
    /**
    - * PURPLE_TYPE_PROTOCOL_ATTENTION:
    - *
    - * The standard _get_type macro for #PurpleProtocolAttention.
    - */
    -#define PURPLE_TYPE_PROTOCOL_ATTENTION (purple_protocol_attention_get_type())
    -
    -/**
    * purple_attention_type_get_type:
    *
    * Returns: The #GType for the #PurpleAttentionType boxed structure.
    --- a/libpurple/purplecredentialmanager.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/purplecredentialmanager.h Thu Nov 19 20:07:44 2020 -0600
    @@ -255,7 +255,7 @@
    /**
    * purple_credential_manager_read_settings:
    - * @manager: The #PurpleCredentialManagerInstance.
    + * @manager: The #PurpleCredentialManager instance.
    * @error: (out) (optional) (nullable): A return address for a #GError.
    *
    * Reads settings from the active #PurpleCredentialProvider of @manager.
    @@ -269,7 +269,7 @@
    /**
    * purple_credential_manager_write_settings:
    - * @provider: The #PurpleCredentialManager instance.
    + * @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.
    --- a/libpurple/purpleimconversation.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/purpleimconversation.h Thu Nov 19 20:07:44 2020 -0600
    @@ -30,8 +30,8 @@
    #include <glib-object.h>
    /**
    - * SECTION:imconversation
    - * @section_id: libpurple-imconversation
    + * SECTION:purpleimconversation
    + * @section_id: libpurple-purpleimconversation
    * @title: IM Conversation Objects
    */
    --- a/libpurple/purpleprotocolattention.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/purpleprotocolattention.h Thu Nov 19 20:07:44 2020 -0600
    @@ -101,7 +101,7 @@
    /**
    * purple_protocol_attention_send_attention:
    * @attention: The #PurpleProtocolAttention instance.
    - * @gc: The #PurpleConnection to send on
    + * @pc: The #PurpleConnection to send on
    * @username: The name of the user to send the attention to.
    * @type: The type of attention to send.
    *
    --- a/libpurple/status.c Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/status.c Thu Nov 19 20:07:44 2020 -0600
    @@ -64,37 +64,6 @@
    GValue *value_type;
    };
    -/**
    - * PurpleStatus:
    - *
    - * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType.
    - * If you're familiar with object-oriented programming languages
    - * then this should be immediately clear. Say, for example, that
    - * one of your AIM buddies has set himself as "away." You have a
    - * PurpleBuddy node for this person in your buddy list. Purple wants
    - * to mark this buddy as "away," so it creates a new PurpleStatus.
    - * The PurpleStatus has its PurpleStatusType set to the "away" state
    - * for the oscar protocol. The PurpleStatus also contains the buddy's
    - * away message. PurpleStatuses are sometimes saved, depending on
    - * the context. The current PurpleStatuses associated with each of
    - * your accounts are saved so that the next time you start Purple,
    - * your accounts will be set to their last known statuses. There
    - * is also a list of saved statuses that are written to the
    - * status.xml file. Also, each PurpleStatus has a "saveable" boolean.
    - * If "saveable" is set to FALSE then the status is NEVER saved.
    - * All PurpleStatuses should be inside a PurplePresence.
    - *
    - * A PurpleStatus is either "independent" or "exclusive."
    - * Independent statuses can be active or inactive and they don't
    - * affect anything else. However, you can only have one exclusive
    - * status per PurplePresence. If you activate one exclusive status,
    - * then the previous exclusive status is automatically deactivated.
    - *
    - * A PurplePresence is like a collection of PurpleStatuses (plus some
    - * other random info).
    - *
    - * See <link linkend="libpurple-presence">Presence API</link>
    - */
    struct _PurpleStatus
    {
    GObject parent;
    --- a/libpurple/status.h Tue Nov 17 22:05:15 2020 -0600
    +++ b/libpurple/status.h Thu Nov 19 20:07:44 2020 -0600
    @@ -72,6 +72,38 @@
    * The standard _get_type macro for #PurpleStatusAttribute.
    */
    #define PURPLE_TYPE_STATUS_ATTRIBUTE (purple_status_attribute_get_type())
    +
    +/**
    + * PurpleStatus:
    + *
    + * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType.
    + * If you're familiar with object-oriented programming languages
    + * then this should be immediately clear. Say, for example, that
    + * one of your AIM buddies has set himself as "away." You have a
    + * PurpleBuddy node for this person in your buddy list. Purple wants
    + * to mark this buddy as "away," so it creates a new PurpleStatus.
    + * The PurpleStatus has its PurpleStatusType set to the "away" state
    + * for the oscar protocol. The PurpleStatus also contains the buddy's
    + * away message. PurpleStatuses are sometimes saved, depending on
    + * the context. The current PurpleStatuses associated with each of
    + * your accounts are saved so that the next time you start Purple,
    + * your accounts will be set to their last known statuses. There
    + * is also a list of saved statuses that are written to the
    + * status.xml file. Also, each PurpleStatus has a "saveable" boolean.
    + * If "saveable" is set to FALSE then the status is NEVER saved.
    + * All PurpleStatuses should be inside a PurplePresence.
    + *
    + * A PurpleStatus is either "independent" or "exclusive."
    + * Independent statuses can be active or inactive and they don't
    + * affect anything else. However, you can only have one exclusive
    + * status per PurplePresence. If you activate one exclusive status,
    + * then the previous exclusive status is automatically deactivated.
    + *
    + * A PurplePresence is like a collection of PurpleStatuses (plus some
    + * other random info).
    + *
    + * See <link linkend="libpurple-purplepresence">Presence API</link>
    + */
    typedef struct _PurpleStatusAttribute PurpleStatusAttribute;
    /**