A bunch of random libpurple documentation fixes
Testing Done:
Build the docs and verified the fixes in `build/doc/reference/libpurple/libpurple-undocumented.txt`
Reviewed at https://reviews.imfreedom.org/r/872/
--- a/ChangeLog.API Tue Aug 03 23:51:44 2021 -0500
+++ b/ChangeLog.API Wed Aug 04 04:40:54 2021 -0500
@@ -353,6 +353,7 @@
* purple_certificate_get_fingerprint_sha256
* Purple Cipher API (PurpleCipherContext and friends).
Use GLib's GHmac or GChecksum instead.
* purple_connection_error_reason
* purple_connection_new_unregister
--- a/doc/reference/libpurple/libpurple-docs.xml Tue Aug 03 23:51:44 2021 -0500
+++ b/doc/reference/libpurple/libpurple-docs.xml Wed Aug 04 04:40:54 2021 -0500
@@ -60,8 +60,6 @@
<xi:include href="xml/plugins.xml" />
<xi:include href="xml/prefs.xml" />
<xi:include href="xml/pluginpref.xml" />
- <xi:include href="xml/protocol.xml" />- <xi:include href="xml/protocols.xml" /> <xi:include href="xml/proxy.xml" />
<xi:include href="xml/purple-gio.xml" />
<xi:include href="xml/purpleaccountoption.xml" />
@@ -74,25 +72,13 @@
<xi:include href="xml/purpleconversation.xml" />
<xi:include href="xml/purpleconversationmanager.xml" />
<xi:include href="xml/purpleconversationuiops.xml" />
- <xi:include href="xml/purplecredentialmanager.xml" />- <xi:include href="xml/purplecredentialprovider.xml" /> <xi:include href="xml/purpledebugui.xml" />
<xi:include href="xml/purpleimconversation.xml" />
<xi:include href="xml/purplekeyvaluepair.xml" />
<xi:include href="xml/purplemarkup.xml" />
- <xi:include href="xml/purplenoopcredentialprovider.xml" /> <xi:include href="xml/purpleoptions.xml" />
<xi:include href="xml/purpleplugininfo.xml" />
<xi:include href="xml/purplepresence.xml" />
- <xi:include href="xml/purpleprotocolattention.xml" />- <xi:include href="xml/purpleprotocolchat.xml" />- <xi:include href="xml/purpleprotocolclient.xml" />- <xi:include href="xml/purpleprotocolfactory.xml" />- <xi:include href="xml/purpleprotocolim.xml" />- <xi:include href="xml/purpleprotocolmanager.xml" />- <xi:include href="xml/purpleprotocolmedia.xml" />- <xi:include href="xml/purpleprotocolprivacy.xml" />- <xi:include href="xml/purpleprotocolserver.xml" /> <xi:include href="xml/purplewhiteboard.xml" />
<xi:include href="xml/purplewhiteboardops.xml" />
<xi:include href="xml/purplewhiteboarduiops.xml" />
@@ -117,6 +103,30 @@
<xi:include href="xml/util.xml" />
+ <part id="Credentials"> + <title>Credentials</title> + <xi:include href="xml/purplecredentialmanager.xml" /> + <xi:include href="xml/purplecredentialprovider.xml" /> + <xi:include href="xml/purplenoopcredentialprovider.xml" /> + <title>Protocols</title> + <xi:include href="xml/protocol.xml" /> + <xi:include href="xml/protocols.xml" /> + <xi:include href="xml/purpleprotocolattention.xml" /> + <xi:include href="xml/purpleprotocolchat.xml" /> + <xi:include href="xml/purpleprotocolclient.xml" /> + <xi:include href="xml/purpleprotocolfactory.xml" /> + <xi:include href="xml/purpleprotocolim.xml" /> + <xi:include href="xml/purpleprotocolmanager.xml" /> + <xi:include href="xml/purpleprotocolmedia.xml" /> + <xi:include href="xml/purpleprotocolprivacy.xml" /> + <xi:include href="xml/purpleprotocolserver.xml" /> <title>Submodules</title>
@@ -172,7 +182,6 @@
<xi:include href="signals_log.xml" />
<xi:include href="signals_notify.xml" />
<xi:include href="signals_plugin.xml" />
- <xi:include href="signals_protocol.xml" /> <xi:include href="signals_savedstatus.xml" />
<xi:include href="signals_jabber.xml" />
--- a/doc/reference/libpurple/meson.build Tue Aug 03 23:51:44 2021 -0500
+++ b/doc/reference/libpurple/meson.build Wed Aug 04 04:40:54 2021 -0500
@@ -53,7 +53,6 @@
- 'signals_protocol.xml', 'signals_savedstatus.xml',
--- a/doc/reference/libpurple/signals_protocol.xml Tue Aug 03 23:51:44 2021 -0500
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,63 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [-<chapter id="chapter-signals-protocol">-<title>Protocol signals</title>-<refsect1 id="protocols.signals" role="signal_proto">-<title role="signal_proto.title">List of signals</title>- "<link linkend="protocols-protocol-added">protocol-added</link>"- "<link linkend="protocols-protocol-removed">protocol-removed</link>"-<refsect1 id="protocols.signal-details" role="signals">-<title role="signals.title">Signal details</title>-<refsect2 id="protocols-protocol-added" role="signal">- <title>The <literal>"protocol-added"</literal> signal</title>-void user_function (PurpleProtocol *protocol,-Emitted when a protocol is added.- <variablelist role="params">- <term><parameter>protocol</parameter> :</term>- <listitem><simpara>The protocol that was added.</simpara></listitem>- <term><parameter>user_data</parameter> :</term>- <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>-<refsect2 id="protocols-protocol-removed" role="signal">- <title>The <literal>"protocol-removed"</literal> signal</title>-void user_function (PurpleProtocol *protocol,-Emitted when a protocol is removed.- <variablelist role="params">- <term><parameter>protocol</parameter> :</term>- <listitem><simpara>The protocol that was removed.</simpara></listitem>- <term><parameter>user_data</parameter> :</term>- <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>--- a/libpurple/buddy.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/buddy.h Wed Aug 04 04:40:54 2021 -0500
@@ -53,11 +53,23 @@
#include "purplepresence.h"
+ * PURPLE_BUDDY_IS_ONLINE: + * @b: The #PurpleBuddy instance. + * Checks whether @b is online or not. #define PURPLE_BUDDY_IS_ONLINE(b) \
&& purple_account_is_connected(purple_buddy_get_account(PURPLE_BUDDY(b))) \
&& purple_presence_is_online(purple_buddy_get_presence(PURPLE_BUDDY(b))))
+ * PURPLE_BLIST_NODE_NAME: + * @n: The #PurpleBlistNode instance. #define PURPLE_BLIST_NODE_NAME(n) \
(PURPLE_IS_CHAT(n) ? purple_chat_get_name(PURPLE_CHAT(n)) : \
PURPLE_IS_BUDDY(n) ? purple_buddy_get_name(PURPLE_BUDDY(n)) : NULL)
--- a/libpurple/cmds.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/cmds.h Wed Aug 04 04:40:54 2021 -0500
@@ -80,8 +80,6 @@
-#define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func) * @conversation: The #PurpleConversation where the command is being run.
--- a/libpurple/protocol.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/protocol.h Wed Aug 04 04:40:54 2021 -0500
@@ -39,7 +39,25 @@
* #PurpleProtocol is the base type for all protocols in libpurple.
+ * PURPLE_TYPE_PROTOCOL: + * The standard _TYPE_ macro for #PurpleProtocol. #define PURPLE_TYPE_PROTOCOL (purple_protocol_get_type())
+ * purple_protocol_get_type: + * Gets the #GType for #PurpleProtocol. + * Returns: The #GType of #PurpleProtocol. G_DECLARE_DERIVABLE_TYPE(PurpleProtocol, purple_protocol, PURPLE, PROTOCOL,
--- a/libpurple/protocols.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/protocols.h Wed Aug 04 04:40:54 2021 -0500
@@ -30,7 +30,6 @@
* @section_id: libpurple-protocols
* @short_description: <filename>protocols.h</filename>
* @title: Protocols Subsystem API
- * @see_also: <link linkend="chapter-signals-protocol">Protocol signals</link> /**************************************************************************/
--- a/libpurple/purpleattachment.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleattachment.h Wed Aug 04 04:40:54 2021 -0500
@@ -39,6 +39,14 @@
+ * PURPLE_TYPE_ATTACHMENT: + * The standard _TYPE_ macro for #PurpleAttachment. #define PURPLE_TYPE_ATTACHMENT purple_attachment_get_type()
@@ -57,7 +65,6 @@
* Called when iterating #PurpleAttachment's.
typedef void (*PurpleAttachmentForeachFunc)(PurpleAttachment *attachment, gpointer data);
--- a/libpurple/purpleconversation.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleconversation.h Wed Aug 04 04:40:54 2021 -0500
@@ -43,6 +43,13 @@
#include <purplemessage.h>
+ * PURPLE_TYPE_CONVERSATION: + * The standard _TYPE_ macro for PurpleConversation. #define PURPLE_TYPE_CONVERSATION (purple_conversation_get_type())
G_DECLARE_DERIVABLE_TYPE(PurpleConversation, purple_conversation, PURPLE,
--- a/libpurple/purpleconversationmanager.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleconversationmanager.h Wed Aug 04 04:40:54 2021 -0500
@@ -30,7 +30,8 @@
* SECTION:purpleconversationmanager
* @section_id: libpurple-purpleconversationmanager
- * @title: Management of conversations+ * @title: Conversation Management + * @short_description: Management of conversations. * #PurpleConversationManager keeps track of all #PurpleConversation's inside of
* libpurple and allows searching of them.
@@ -39,7 +40,32 @@
+ * PURPLE_TYPE_CONVERSATION_MANAGER: + * The standard _TYPE_ macro for PurpleConversationManager. #define PURPLE_TYPE_CONVERSATION_MANAGER (purple_conversation_manager_get_type())
+ * purple_conversation_manager_get_type: + * Gets the #GType of #PurpleConversationManager. + * Returns: The #GType of #PurpleConversationManager. + * PurpleConversationManager: + * An opaque structure that represents the conversation manager. G_DECLARE_FINAL_TYPE(PurpleConversationManager, purple_conversation_manager,
PURPLE, CONVERSATION_MANAGER, GObject)
--- a/libpurple/purplecredentialmanager.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purplecredentialmanager.h Wed Aug 04 04:40:54 2021 -0500
@@ -35,6 +35,7 @@
* SECTION:purplecredentialmanager
* @section_id: libpurple-purplecredentialmanager
* @title: Purple Credential Manager
+ * @short_description: Management of credential providers. * Purple Credential Manager is the main API access to different credential
* providers. Providers register themselves with the manager and then the user
--- a/libpurple/purplecredentialprovider.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purplecredentialprovider.h Wed Aug 04 04:40:54 2021 -0500
@@ -33,6 +33,12 @@
* SECTION:purplecredentialprovider
* @section_id: libpurple-purplecredentialprovider
* @title: Credential Provider Object
+ * @short_description: Abstraction of credential providers. + * #PurpleCredentialProvider is an abstract base class for implementing support + * for a specific password or keyring manager. At the time of this writing, + * libpurple ships with plugins for libsecret, KWallet, and the Windows + * Credentials store by subclassing #PurpleCredentialProvider. @@ -56,7 +62,25 @@
+ * PURPLE_TYPE_CREDENTIAL_PROVIDER: + * The standard _TYPE_ macro for PurpleCredentialProvider. #define PURPLE_TYPE_CREDENTIAL_PROVIDER (purple_credential_provider_get_type())
+ * purple_credential_provider_get_type: + * Gets the #GType of #PurpleCredentialProvider. + * Returns: The #GType of #PurpleCredentialProvider. G_DECLARE_DERIVABLE_TYPE(PurpleCredentialProvider, purple_credential_provider,
PURPLE, CREDENTIAL_PROVIDER, GObject)
--- a/libpurple/purplemessage.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purplemessage.h Wed Aug 04 04:40:54 2021 -0500
@@ -73,6 +73,7 @@
* @PURPLE_MESSAGE_REMOTE_SEND: Message sent from another location, not an echo
+ * @PURPLE_MESSAGE_FORWARDED: The message has been forward to the recipient. * Flags applicable to a message. Most will have send, recv or system.
--- a/libpurple/purplenoopcredentialprovider.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purplenoopcredentialprovider.h Wed Aug 04 04:40:54 2021 -0500
@@ -32,6 +32,7 @@
* SECTION:purplenoopcredentialprovider
* @section_id: libpurple-purplenoopcredentialprovider
* @title: No Operation Credential Provider Object
+ * @short_description: A #PurpleCredentialProvider that does nothing. * This is the "None" credential provider that always returns failures so that
* the user is forced to enter a password.
@@ -49,7 +50,24 @@
+ * PURPLE_TYPE_NOOP_CREDENTIAL_PROVIDER: + * The standard _TYPE_ macro for #PurpleNoopCredentialProvider. #define PURPLE_TYPE_NOOP_CREDENTIAL_PROVIDER (purple_noop_credential_provider_get_type())
+ * purple_noop_credential_provider_get_type: + * Gets the #GType of #PurpleNoopCredentialProvider. + * Returns: The #GType of #PurpleNoopCredentialProvider. G_DECLARE_FINAL_TYPE(PurpleNoopCredentialProvider,
purple_noop_credential_provider,
PURPLE, NOOP_CREDENTIAL_PROVIDER, PurpleCredentialProvider)
--- a/libpurple/purpleplugininfo.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleplugininfo.h Wed Aug 04 04:40:54 2021 -0500
@@ -27,9 +27,13 @@
* SECTION:purpleplugininfo
* @section_id: libpurple-purpleplugininfo
* @title: PurplePluginInfo Object
+ * @short_description: An object representing information about purple plugins. * @see_also: <link linkend="chapter-signals-plugin">Plugin signals</link>,
* <link linkend="chapter-plugin-ids">Plugin IDs</link>,
* <link linkend="chapter-plugin-i18n">Third Party Plugin Translation</link>
+ * #PurplePluginInfo is a #GPluginPluginInfo subclass that adds additional + * libpurple specific properties. @@ -43,19 +47,32 @@
* PURPLE_TYPE_PLUGIN_INFO:
* The standard _get_type macro for #PurplePluginInfo.
#define PURPLE_TYPE_PLUGIN_INFO (purple_plugin_info_get_type())
* purple_plugin_info_get_type:
+ * The standard _get_type function for #PurplePluginInfo. * Returns: The #GType for the #PurplePluginInfo object.
-G_DECLARE_DERIVABLE_TYPE(PurplePluginInfo, purple_plugin_info, PURPLE, PLUGIN_INFO,+G_DECLARE_DERIVABLE_TYPE(PurplePluginInfo, purple_plugin_info, PURPLE, + PLUGIN_INFO, GPluginPluginInfo) + * PurplePluginInfoClass: + * An opaque type representing the class of a #PurplePluginInfo. struct _PurplePluginInfoClass {
GPluginPluginInfoClass parent;
@@ -104,17 +121,24 @@
typedef gpointer (*PurplePluginPrefRequestCb)(PurplePlugin *plugin);
+ * PURPLE_TYPE_PLUGIN_INFO_FLAGS: + * The standard type macro for #PurplePluginInfoFlags. * @PURPLE_PLUGIN_INFO_FLAGS_INTERNAL: Plugin is not shown in UI lists
* @PURPLE_PLUGIN_INFO_FLAGS_AUTO_LOAD: Auto-load the plugin
* Flags that can be used to treat plugins differently.
typedef enum /*< flags >*/
PURPLE_PLUGIN_INFO_FLAGS_INTERNAL = 1 << 1,
PURPLE_PLUGIN_INFO_FLAGS_AUTO_LOAD = 1 << 2,
@@ -127,6 +151,11 @@
* PURPLE_PLUGIN_ABI_VERSION:
+ * @major: The major version of libpurple to target. + * @minor: The minor version of libpurple to target. + * Packs @major and @minor into an integer to be used as an abi version for * Note: The lower six nibbles represent the ABI version for libpurple, the
* rest are required by GPlugin.
@@ -138,6 +167,9 @@
* PURPLE_PLUGIN_ABI_MAJOR_VERSION:
+ * @abi: The abi version. + * Extracts the purple major version from @abi. * Returns: The major version from an ABI version
@@ -146,6 +178,9 @@
* PURPLE_PLUGIN_ABI_MINOR_VERSION:
+ * @abi: The abi version. + * Extracts the purple minor version from @abi. * Returns: The minor version from an ABI version
--- a/libpurple/purpleprotocolattention.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleprotocolattention.h Wed Aug 04 04:40:54 2021 -0500
@@ -34,6 +34,10 @@
* SECTION:purpleprotocolattention
* @section_id: libpurple-purpleprotocolattention
* @title: Protocol Attention Interface
+ * @short_description: Protocol interface for attention. + * @PurpleProtocolAttention is an interface that PurpleProtocols can implement + * to support getting a contact's attention. @@ -45,13 +49,28 @@
* PURPLE_TYPE_PROTOCOL_ATTENTION:
* The standard _get_type macro for #PurpleProtocolAttention.
#define PURPLE_TYPE_PROTOCOL_ATTENTION (purple_protocol_attention_get_type())
* purple_protocol_attention_get_type:
+ * Gets the #GType for #PurpleProtocolAttentionInterface. * Returns: The #GType for the protocol attention interface.
+ * PurpleProtocolAttention: + * An opaque data structure used to represent an object that implements the + * #PurpleProtocolAttention interface. G_DECLARE_INTERFACE(PurpleProtocolAttention, purple_protocol_attention, PURPLE,
PROTOCOL_ATTENTION, GObject)
@@ -67,6 +86,8 @@
* This interface provides attention API for sending and receiving
* zaps/nudges/buzzes etc.
struct _PurpleProtocolAttentionInterface {
--- a/libpurple/purpleprotocolchat.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleprotocolchat.h Wed Aug 04 04:40:54 2021 -0500
@@ -43,21 +43,39 @@
#include <libpurple/connection.h>
#include <libpurple/purplemessage.h>
+ * PURPLE_TYPE_PROTOCOL_CHAT: + * The standard _TYPE_ macro for #PurpleProtocolChat. #define PURPLE_TYPE_PROTOCOL_CHAT (purple_protocol_chat_get_type())
+ * purple_protocol_chat_get_type: + * Gets the #GType for #PurpleProtocolChat. + * Returns: The #GType for #PurpleProtocolChat. + * An opaque representation of an object that implements + * #PurpleProtocolChatInterface. G_DECLARE_INTERFACE(PurpleProtocolChat, purple_protocol_chat, PURPLE, PROTOCOL_CHAT,
- * PURPLE_TYPE_PROTOCOL_CHAT:- * The standard _get_type method for #PurpleProtocolChat. * PurpleProtocolChatInterface:
* @info: Returns a list of #PurpleProtocolChatEntry structs, which represent
* information required by the protocol to join a chat. libpurple will
--- a/libpurple/purpleprotocolim.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleprotocolim.h Wed Aug 04 04:40:54 2021 -0500
@@ -30,8 +30,8 @@
* SECTION:purpleprotocolim
* @section_id: libpurple-purpleprotocolim
+ * @title: ProtocolIM Interface * @short_description: Protocol Instant Message Interface
- * @title: ProtocolIM Interface * #PurpleProtocolIM describes the API that protocols need to implement for
* handling one on one conversations.
@@ -42,17 +42,35 @@
#include <libpurple/connection.h>
-#define PURPLE_TYPE_PROTOCOL_IM (purple_protocol_im_get_type())-G_DECLARE_INTERFACE(PurpleProtocolIM, purple_protocol_im, PURPLE, PROTOCOL_IM, * PURPLE_TYPE_PROTOCOL_IM:
- * The standard _get_type method for #PurpleProtocolIM.+ * The standard _TYPE_ macro for #PurpleProtocolIM. +#define PURPLE_TYPE_PROTOCOL_IM (purple_protocol_im_get_type()) + * purple_protocol_im_get_type: + * Gets the #GType for #PurpleProtocolIM. + * Returns: The #GType for #PurpleProtocolIM. + * An opaque data structure that represents and object that implements + * #PurpleProtocolIMInterface. +G_DECLARE_INTERFACE(PurpleProtocolIM, purple_protocol_im, PURPLE, PROTOCOL_IM, * PurpleProtocolIMInterface:
@@ -106,7 +124,7 @@
- * purple_protocol_im_send_type:+ * purple_protocol_im_send_typing: * @im: The #PurpleProtocolIM instance.
* @connection: The #PurpleConversation to use.
* @name: The name of the user to send a typing notification to.
--- a/libpurple/purpleprotocolmanager.c Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleprotocolmanager.c Wed Aug 04 04:40:54 2021 -0500
@@ -70,7 +70,7 @@
obj_class->finalize = purple_protocol_manager_finalize;
- * PurpleProtocolManager::protocol-registered:+ * PurpleProtocolManager::registered: * @manager: The #PurpleProtocolManager instance.
* @protocol: The #PurpleProtocol that was registered.
@@ -91,7 +91,7 @@
- * PurpleProtocolManager::protocol-unregistered:+ * PurpleProtocolManager::unregistered: * @manager: The #PurpleProtocolManager instance.
* @protocol: The #PurpleProtocol that was unregistered.
--- a/libpurple/purpleprotocolmanager.h Tue Aug 03 23:51:44 2021 -0500
+++ b/libpurple/purpleprotocolmanager.h Wed Aug 04 04:40:54 2021 -0500
@@ -34,6 +34,7 @@
* SECTION:purpleprotocolmanager
* @section_id: libpurple-purpleprotocolmanager
* @title: Purple Protocol Manager
+ * @short_description: Management of protocols. * #PurpleProtocolManager keeps track of all protocols and emits signals when
* protocols are registered and unregistered.
