pidgin/pidgin

A bunch of documentation cleanups

2020-11-05, Gary Kramlich
6f198a69ac48
Parents 28964322556c
Children e48ab6b7e367
A bunch of documentation cleanups

Testing Done:
Build the docs, verified via libpurple-undocumented.txt

Reviewed at https://reviews.imfreedom.org/r/195/
27 files changed, 248 insertions(+), 86 deletions(-)
  • +0 -1
    doc/reference/libpurple/libpurple-docs.xml
  • +1 -0
    doc/reference/libpurple/meson.build
  • +5 -2
    libpurple/purplekeyvaluepair.h
  • +3 -0
    libpurple/purplemarkup.h
  • +2 -1
    libpurple/purplepresence.h
  • +6 -6
    libpurple/purpleprotocolfactory.h
  • +5 -1
    libpurple/purpleprotocolim.h
  • +5 -1
    libpurple/purpleprotocolmedia.h
  • +4 -1
    libpurple/purpleprotocolprivacy.h
  • +6 -4
    libpurple/purpleuiinfo.h
  • +7 -3
    libpurple/request-datasheet.h
  • +10 -4
    libpurple/request.h
  • +18 -3
    libpurple/roomlist.h
  • +9 -3
    libpurple/savedstatuses.h
  • +8 -3
    libpurple/server.h
  • +23 -3
    libpurple/signals.h
  • +35 -13
    libpurple/status.h
  • +14 -7
    libpurple/stun.h
  • +9 -3
    libpurple/theme-loader.h
  • +9 -3
    libpurple/theme-manager.h
  • +9 -3
    libpurple/theme.h
  • +8 -3
    libpurple/upnp.h
  • +7 -6
    libpurple/util.h
  • +6 -3
    libpurple/version.h.in
  • +12 -3
    libpurple/whiteboard.h
  • +18 -3
    libpurple/xfer.h
  • +9 -3
    libpurple/xmlnode.h
    • --- a/doc/reference/libpurple/libpurple-docs.xml Thu Nov 05 20:36:51 2020 -0600
    +++ b/doc/reference/libpurple/libpurple-docs.xml Thu Nov 05 20:40:01 2020 -0600
    @@ -90,7 +90,6 @@
    <xi:include href="xml/core.xml" />
    <xi:include href="xml/status.xml" />
    <xi:include href="xml/stun.xml" />
    - <xi:include href="xml/tests.xml" />
    <xi:include href="xml/theme.xml" />
    <xi:include href="xml/theme-loader.xml" />
    <xi:include href="xml/theme-manager.xml" />
    --- a/doc/reference/libpurple/meson.build Thu Nov 05 20:36:51 2020 -0600
    +++ b/doc/reference/libpurple/meson.build Thu Nov 05 20:40:01 2020 -0600
    @@ -6,6 +6,7 @@
    'plugins',
    'protocols',
    'tests',
    + 'tests.h',
    'win32',
    'backend-fs2.h',
    'glibcompat.h',
    --- a/libpurple/purplekeyvaluepair.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purplekeyvaluepair.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -28,9 +29,11 @@
    /**
    * SECTION:purplekeyvaluepair
    - * @section_id: libpurple-key-value-pair
    + * @section_id: libpurple-keyvaluepair
    * @short_description: <filename>purplekeyvaluepair.h</filename>
    * @title: Key Value Pairs
    + *
    + * A simple key value pair data structure.
    */
    #include <glib.h>
    --- a/libpurple/purplemarkup.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purplemarkup.h Thu Nov 05 20:40:01 2020 -0600
    @@ -34,7 +34,10 @@
    /**
    * SECTION:purplemarkup
    * @section_id: libpurple-purplemarkup
    + * @short_description: Text Markup API
    * @title: Text Markup API
    + *
    + * Helper functions for handling markup.
    */
    /**
    --- a/libpurple/purplepresence.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purplepresence.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +1,5 @@
    /*
    - * 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
    @@ -30,6 +30,7 @@
    /**
    * SECTION:purplepresence
    * @section_id: libpurple-purplepresence
    + * @short_description: Presence Objects
    * @title: Presence Object API
    *
    * This file contains the base #PurplePresence type which is used by
    --- a/libpurple/purpleprotocolfactory.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purpleprotocolfactory.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -16,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -28,10 +28,10 @@
    #define PURPLE_PROTOCOL_FACTORY_H
    /**
    - * SECTION:protocol-factory
    - * @section_id: purple-protocol-factory
    + * SECTION:purpleprotocolfactory
    + * @section_id: libpurple-purpleprotocolfactory
    + * @short_description: <filename>purpleprotocolfactory.h</filename>
    * @title: ProtocolFactoryInterface
    - * @short_description: <filename>purpleprotocolfactory.h</filename>
    *
    * A interface where protocols can expose subclasses of libpurple objects.
    */
    --- a/libpurple/purpleprotocolim.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purpleprotocolim.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -31,6 +32,9 @@
    * @section_id: libpurple-purpleprotocolim
    * @short_description: Protocol Instant Message Interface
    * @title: ProtocolIM Interface
    + *
    + * #PurpleProtocolIM describes the API that protocols need to implement for
    + * handling one on one conversations.
    */
    #include <glib.h>
    --- a/libpurple/purpleprotocolmedia.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purpleprotocolmedia.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -31,6 +32,9 @@
    * @section_id: libpurple-purpleprotocolmedia
    * @short_description: Protocol Media Interface
    * @title: ProtocolMedia Interface
    + *
    + * #PurpleProtocolMedia describes the multimedia api that is available for
    + * protocols.
    */
    #include <glib.h>
    --- a/libpurple/purpleprotocolprivacy.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purpleprotocolprivacy.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -31,6 +32,8 @@
    * @section_id: libpurple-purpleprotocolprivacy
    * @short_description: Protocol Privacy Interface
    * @title: ProtocolPrivacy Interface
    + *
    + * #PurpleProtocolPrivacy describes the privacy API available to protocols.
    */
    #include <glib.h>
    --- a/libpurple/purpleuiinfo.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/purpleuiinfo.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -16,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -30,8 +30,10 @@
    /**
    * SECTION:purpleuiinfo
    * @section_id: libpurple-ui-info
    - * @short_description: <filename>purpleuiinfo.h</filename>
    + * @short_description: User Interface Information
    * @title: A simple class that contains information about a user interface.
    + *
    + * #PurpleUiInfo keeps track of basic information about the user interface.
    */
    #include <glib.h>
    --- a/libpurple/request-datasheet.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/request-datasheet.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,14 @@
    #ifndef PURPLE_REQUEST_DATA_H
    #define PURPLE_REQUEST_DATA_H
    +
    /**
    * SECTION:request-datasheet
    * @section_id: libpurple-request-datasheet
    * @short_description: <filename>request-datasheet.h</filename>
    * @title: Request Datasheet API
    + *
    + * Request Datasheet is a UI abstracted table.
    */
    #include <glib.h>
    --- a/libpurple/request.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/request.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,14 @@
    #ifndef PURPLE_REQUEST_H
    #define PURPLE_REQUEST_H
    +
    /**
    * SECTION:request
    * @section_id: libpurple-request
    * @short_description: <filename>request.h</filename>
    * @title: Request API
    + *
    + * The request API is an abstract procedural ui builder.
    */
    #include <stdlib.h>
    @@ -1018,7 +1022,7 @@
    gboolean purple_request_field_is_visible(const PurpleRequestField *field);
    /**
    - * purple_request_field_get_type_hint:
    + * purple_request_field_get_field_type_hint:
    * @field: The field.
    *
    * Returns the field's type hint.
    @@ -2364,6 +2368,8 @@
    /**
    * purple_request_ui_ops_get_type:
    *
    + * The standard _get_type function for #PurpleRequestUiOps.
    + *
    * Returns: The #GType for the #PurpleRequestUiOps boxed structure.
    */
    GType purple_request_ui_ops_get_type(void);
    --- a/libpurple/roomlist.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/roomlist.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,15 @@
    #ifndef PURPLE_ROOMLIST_H
    #define PURPLE_ROOMLIST_H
    +
    /**
    * SECTION:roomlist
    * @section_id: libpurple-roomlist
    * @short_description: <filename>roomlist.h</filename>
    * @title: Room List API
    + *
    + * The room list API describes how to display and populate a list of rooms in
    + * a protocol abstract way.
    */
    /**
    @@ -154,6 +159,8 @@
    /**
    * purple_roomlist_get_type:
    *
    + * The standard _get_type function for #PurpleRoomlist.
    + *
    * Returns: The #GType for the Room List object.
    */
    G_DECLARE_FINAL_TYPE(PurpleRoomlist, purple_roomlist, PURPLE, ROOMLIST, GObject)
    @@ -367,6 +374,8 @@
    /**
    * purple_protocol_roomlist_iface_get_type:
    *
    + * The standard _get_type function for #PurpleProtocolRoomlistInterface.
    + *
    * Returns: The #GType for the protocol roomlist interface.
    *
    * Since: 3.0.0
    @@ -434,6 +443,8 @@
    /**
    * purple_roomlist_room_get_type:
    *
    + * The standard _get_type function for #PurpleRoomlistRoom.
    + *
    * Returns: The #GType for the #PurpleRoomlistRoom boxed structure.
    */
    GType purple_roomlist_room_get_type(void);
    @@ -536,6 +547,8 @@
    /**
    * purple_roomlist_field_get_type:
    *
    + * The standard _get_type function for #PurpleRoomlistField.
    + *
    * Returns: The #GType for the #PurpleRoomlistField boxed structure.
    */
    GType purple_roomlist_field_get_type(void);
    @@ -593,6 +606,8 @@
    /**
    * purple_roomlist_ui_ops_get_type:
    *
    + * The standard _get_type function for #PurpleRoomlistUiOps.
    + *
    * Returns: The #GType for the #PurpleRoomlistUiOps boxed structure.
    */
    GType purple_roomlist_ui_ops_get_type(void);
    --- a/libpurple/savedstatuses.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/savedstatuses.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,12 +26,15 @@
    #ifndef PURPLE_SAVEDSTATUSES_H
    #define PURPLE_SAVEDSTATUSES_H
    +
    /**
    * SECTION:savedstatuses
    * @section_id: libpurple-savedstatuses
    * @short_description: <filename>savedstatuses.h</filename>
    * @title: Saved Status API
    * @see_also: <link linkend="chapter-signals-savedstatus">Saved Status signals</link>
    + *
    + * The saved statuses API manages statuses that are saved to disk.
    */
    #define PURPLE_TYPE_SAVEDSTATUS (purple_savedstatus_get_type())
    @@ -78,6 +82,8 @@
    /**
    * purple_savedstatus_get_type:
    *
    + * The standard _get_type function for #PurpleSavedStatus.
    + *
    * Returns: The #GType for the #PurpleSavedStatus boxed structure.
    */
    /* TODO Boxing of PurpleSavedStatus is a temporary solution to having a GType
    --- a/libpurple/server.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/server.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,15 @@
    #ifndef PURPLE_SERVER_H
    #define PURPLE_SERVER_H
    +
    /**
    * SECTION:server
    * @section_id: libpurple-server
    * @short_description: <filename>server.h</filename>
    * @title: Server API
    + *
    + * The server API is used by protocol plugins to tell libpurple when certain
    + * things have happened.
    */
    #include "accounts.h"
    --- a/libpurple/signals.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/signals.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,12 +26,16 @@
    #ifndef PURPLE_SIGNALS_H
    #define PURPLE_SIGNALS_H
    +
    /**
    * SECTION:signals
    * @section_id: libpurple-signals
    * @short_description: <filename>signals.h</filename>
    * @title: Purple-signals API
    * @see_also: <link linkend="chapter-tut-signals">Signals tutorial</link>
    + *
    + * The signals API is similar to GObject signals, but works on classes where
    + * GObject signals work on instances.
    */
    #include <glib.h>
    @@ -44,7 +49,22 @@
    */
    #define PURPLE_CALLBACK(func) ((PurpleCallback)(func))
    +/**
    + * PurpleCallback:
    + *
    + * A generic function pointer type to represent a callback function.
    + */
    typedef void (*PurpleCallback)(void);
    +
    +/**
    + * PurpleSignalMarshalFunc:
    + * @cb: The #PurpleCallback to call.
    + * @args: The arguments to the function.
    + * @data: Userdata to pass to @cb.
    + * @return_val: (optional) (nullable): A return address for a return value.
    + *
    + * A generic function pointer type used to register signals.
    + */
    typedef void (*PurpleSignalMarshalFunc)(PurpleCallback cb, va_list args,
    void *data, void **return_val);
    --- a/libpurple/status.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/status.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -16,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -26,11 +26,15 @@
    #ifndef PURPLE_STATUS_H
    #define PURPLE_STATUS_H
    +
    /**
    * SECTION:status
    * @section_id: libpurple-status
    * @short_description: <filename>status.h</filename>
    * @title: Status Object API
    + *
    + * The status API is what keeps track of all status for all accounts as well as
    + * all contacts.
    */
    /**
    @@ -41,7 +45,7 @@
    #define PURPLE_TYPE_STATUS (purple_status_get_type())
    typedef struct _PurpleStatus PurpleStatus;
    -/**
    +/*
    * PURPLE_TYPE_STATUS_TYPE:
    *
    * The standard _get_type macro for #PurpleStatusType.
    @@ -77,10 +81,20 @@
    */
    #define PURPLE_TYPE_MOOD (purple_mood_get_type())
    +/**
    + * PurpleMood:
    + * @mood: A string representing the mood.
    + * @description: A short description of the mood.
    + *
    + * A structure to represent a mood.
    + */
    typedef struct {
    + /*< public >*/
    const char *mood;
    const char *description;
    - gpointer *padding;
    +
    + /*< private >*/
    + gpointer padding[4];
    } PurpleMood;
    /**
    @@ -241,7 +255,9 @@
    /**
    * purple_status_type_get_type:
    *
    - * Returns: The #GType for the #PurpleStatusType boxed structure.
    + * The standard _get_type function for #PurpleStatusType.
    + *
    + * Returns: The #GType for #PurpleStatusType.
    */
    GType purple_status_type_get_type(void);
    @@ -457,6 +473,8 @@
    /**
    * purple_status_attribute_get_type:
    *
    + * The standard _get_type function for #PurpleStatusAttribute.
    + *
    * Returns: The #GType for the #PurpleStatusAttribute boxed structure.
    */
    GType purple_status_attribute_get_type(void);
    @@ -519,6 +537,8 @@
    /**
    * purple_mood_get_type:
    *
    + * The standard _get_type function for #PurpleMood.
    + *
    * Returns: The #GType for the #PurpleMood boxed structure.
    */
    GType purple_mood_get_type(void);
    @@ -530,7 +550,9 @@
    /**
    * purple_status_get_type:
    *
    - * Returns: The #GType for the Status object.
    + * The standard _get_type function for #PurpleStatus.
    + *
    + * Returns: The #GType for #PurpleStatus.
    */
    G_DECLARE_FINAL_TYPE(PurpleStatus, purple_status, PURPLE, STATUS, GObject)
    @@ -574,12 +596,13 @@
    va_list args);
    /**
    - * purple_status_set_active_with_attrs_list:
    + * purple_status_set_active_with_attrs_dict:
    * @status: The status.
    * @active: The active state.
    - * @attrs: (element-type utf8 gpointer): A hash table of attributes to set on the status.
    - * This hash table's keys are valid attribute names for this PurpleStatusType.
    - * The hash table is not modified or freed by this function.
    + * @attrs: (element-type utf8 gpointer): A hash table of attributes to set on
    + * the status. This hash table's keys are valid attribute names for
    + * this PurpleStatusType. The hash table is not modified or freed by
    + * this function.
    *
    * Sets whether or not a status is active.
    *
    @@ -587,8 +610,7 @@
    *
    * Since: 3.0.0
    */
    -void purple_status_set_active_with_attrs_dict(PurpleStatus *status, gboolean active,
    - GHashTable *attrs);
    +void purple_status_set_active_with_attrs_dict(PurpleStatus *status, gboolean active, GHashTable *attrs);
    /**
    * purple_status_get_status_type:
    --- a/libpurple/stun.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/stun.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,17 +26,17 @@
    #ifndef PURPLE_STUN_H
    #define PURPLE_STUN_H
    +
    /**
    * SECTION:stun
    * @section_id: libpurple-stun
    * @short_description: <filename>stun.h</filename>
    * @title: STUN API
    + *
    + * The STUN API is an implementation of Session Traversal Utilities for NAT,
    + * that is used to help us determine our public IP address.
    */
    -/******************************************************************************
    - * STUN API
    - *****************************************************************************/
    -
    typedef struct _PurpleStunNatDiscovery PurpleStunNatDiscovery;
    /**
    @@ -111,6 +112,12 @@
    */
    PurpleStunNatDiscovery *purple_stun_discover(PurpleStunCallback cb);
    +/**
    + * purple_stun_init:
    + *
    + * Initializes the STUN API. This is called by libpurple and you should not be
    + * calling it yourself.
    + */
    void purple_stun_init(void);
    G_END_DECLS
    --- a/libpurple/theme-loader.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/theme-loader.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,14 @@
    #ifndef PURPLE_THEME_LOADER_H
    #define PURPLE_THEME_LOADER_H
    +
    /**
    * SECTION:theme-loader
    * @section_id: libpurple-theme-loader
    * @short_description: <filename>theme-loader.h</filename>
    * @title: Theme Loader Abstact Class
    + *
    + * The base class for all theme loaders.
    */
    #include <glib.h>
    @@ -65,6 +69,8 @@
    /**
    * purple_theme_loader_get_type:
    *
    + * The standard _get_type function for #GType's.
    + *
    * Returns: The #GType for theme loader.
    */
    G_DECLARE_DERIVABLE_TYPE(PurpleThemeLoader, purple_theme_loader, PURPLE,
    --- a/libpurple/theme-manager.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/theme-manager.h Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -16,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -26,11 +26,15 @@
    #ifndef PURPLE_THEME_MANAGER_H
    #define PURPLE_THEME_MANAGER_H
    +
    /**
    * SECTION:theme-manager
    * @section_id: libpurple-theme-manager
    * @short_description: <filename>theme-manager.h</filename>
    * @title: Theme Manager API
    + *
    + * The theme manager manages of all the available themes and allows you to load
    + * them.
    */
    #include <glib-object.h>
    @@ -55,6 +59,8 @@
    /**
    * purple_theme_manager_get_type:
    *
    + * The standard _get_type function for #GType's.
    + *
    * Returns: The #GType for theme manager.
    */
    G_DECLARE_FINAL_TYPE(PurpleThemeManager, purple_theme_manager, PURPLE,
    --- a/libpurple/theme.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/theme.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -30,6 +31,9 @@
    * @section_id: libpurple-theme
    * @short_description: <filename>theme.h</filename>
    * @title: Theme Abstact Class
    + *
    + * The theme API represents the common abilities for all of our supported
    + * themes.
    */
    #include <glib.h>
    @@ -61,6 +65,8 @@
    /**
    * purple_theme_get_type:
    *
    + * The standard _get_type function for #GType's.
    + *
    * Returns: The #GType for a theme.
    */
    G_DECLARE_DERIVABLE_TYPE(PurpleTheme, purple_theme, PURPLE, THEME, GObject)
    --- a/libpurple/upnp.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/upnp.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,15 @@
    #ifndef PURPLE_UPNP_H
    #define PURPLE_UPNP_H
    +
    /**
    * SECTION:upnp
    * @section_id: libpurple-upnp
    * @short_description: <filename>upnp.h</filename>
    * @title: Universal Plug N Play API
    + *
    + * The UPNP API allows us to use Universal Plug and Play to determine a user's
    + * public IP address as well as open port forwards.
    */
    typedef struct _PurpleUPnPMappingAddRemove PurpleUPnPMappingAddRemove;
    --- a/libpurple/util.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/util.h Thu Nov 05 20:40:01 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,11 +17,7 @@
    * 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
    - *
    - * TODO Rename the functions so that they live somewhere in the purple
    - * namespace.
    + * along with this program; if not, see <https://www.gnu.org/licenses/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -33,6 +31,9 @@
    * @section_id: libpurple-util
    * @short_description: <filename>util.h</filename>
    * @title: Utility Functions
    + *
    + * The utility API is a cesspool please don't add more stuff here. Namespace
    + * new functions properly and don't put them here.
    */
    #include <stdio.h>
    --- a/libpurple/version.h.in Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/version.h.in Thu Nov 05 20:40:01 2020 -0600
    @@ -1,5 +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
    @@ -16,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -32,6 +32,9 @@
    * @section_id: libpurple-version
    * @short_description: <filename>version.h</filename>
    * @title: Purple Versioning
    + *
    + * A collection of constants and functions for handling versioning of libpurple.
    + *
    */
    /**
    --- a/libpurple/whiteboard.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/whiteboard.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -25,11 +26,15 @@
    #ifndef PURPLE_WHITEBOARD_H
    #define PURPLE_WHITEBOARD_H
    +
    /**
    * SECTION:whiteboard
    * @section_id: libpurple-whiteboard
    * @short_description: <filename>whiteboard.h</filename>
    * @title: Whiteboard Object
    + *
    + * The #PurpleWhiteboard API describes all interactions with whiteboards or
    + * shared drawing spaces with other users.
    */
    /**
    @@ -139,6 +144,8 @@
    /**
    * purple_whiteboard_get_type:
    *
    + * The standard _get_type function for #PurpleWhiteboard.
    + *
    * Returns: The #GType for the #PurpleWhiteboard object.
    */
    G_DECLARE_FINAL_TYPE(PurpleWhiteboard, purple_whiteboard, PURPLE, WHITEBOARD,
    @@ -147,6 +154,8 @@
    /**
    * purple_whiteboard_ui_ops_get_type:
    *
    + * The standard _get_type function for #PurpleWhiteboardUiOps.
    + *
    * Returns: The #GType for the #PurpleWhiteboardUiOps boxed structure.
    */
    GType purple_whiteboard_ui_ops_get_type(void);
    --- a/libpurple/xfer.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/xfer.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -31,6 +32,8 @@
    * @short_description: <filename>xfer.h</filename>
    * @title: File Transfer API
    * @see_also: <link linkend="chapter-signals-xfer">File Transfer signals</link>
    + *
    + * The Xfer API is used to manage file transfers.
    */
    /**
    @@ -99,6 +102,14 @@
    * The standard _get_type macro for #PurpleXfer.
    */
    #define PURPLE_TYPE_XFER (purple_xfer_get_type())
    +
    +/**
    + * purple_xfer_get_type:
    + *
    + * The standard _get_type function for #PurpleXfer.
    + *
    + * Returns: The #GType for #PurpleXfer.
    + */
    G_DECLARE_DERIVABLE_TYPE(PurpleXfer, purple_xfer, PURPLE, XFER, GObject)
    /**
    @@ -748,6 +759,8 @@
    /**
    * purple_xfer_ui_ops_get_type:
    *
    + * The standard _get_type function for #GType's.
    + *
    * Returns: The #GType for the #PurpleXferUiOps boxed structure.
    */
    GType purple_xfer_ui_ops_get_type(void);
    @@ -816,6 +829,8 @@
    /**
    * purple_protocol_xfer_get_type:
    *
    + * The standard _get_type function for #GType's.
    + *
    * Returns: The #GType for the protocol xfer interface.
    */
    G_DECLARE_INTERFACE(PurpleProtocolXfer, purple_protocol_xfer, PURPLE,
    --- a/libpurple/xmlnode.h Thu Nov 05 20:36:51 2020 -0600
    +++ b/libpurple/xmlnode.h Thu Nov 05 20:40:01 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,8 +17,7 @@
    * 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/>.
    */
    #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
    @@ -30,6 +31,9 @@
    * @section_id: libpurple-xmlnode
    * @short_description: <filename>xmlnode.h</filename>
    * @title: XML DOM functions
    + *
    + * XmlNode is a simplified API for handling XML. An XmlNode represents an XML
    + * element and has API for children as well as attributes.
    */
    #include <glib.h>
    @@ -90,6 +94,8 @@
    /**
    * purple_xmlnode_get_type:
    *
    + * The standard _get_type function for registered #GType's.
    + *
    * Returns: The #GType for the #PurpleXmlNode boxed structure.
    */
    GType purple_xmlnode_get_type(void);