Convert the new .h files for this branch for gtk-doc

1 files changed, 226 insertions, 190 deletions

diff --git a/libpurple/protocols.h b/libpurple/protocols.h
index be0d8ae5e7..1e4ddfecb1 100644
--- a/libpurple/protocols.h
+++ b/libpurple/protocols.h
@@ -31,14 +31,16 @@
 
 #define PURPLE_TYPE_PROTOCOL_ACTION  (purple_protocol_action_get_type())
 
-/** @copydoc _PurpleProtocolAction */
 typedef struct _PurpleProtocolAction PurpleProtocolAction;
 typedef void (*PurpleProtocolActionCallback)(PurpleProtocolAction *);
 
 #define PURPLE_TYPE_ATTENTION_TYPE  (purple_attention_type_get_type())
 
-/** Represents "nudges" and "buzzes" that you may send to a buddy to attract
- *  their attention (or vice-versa).
+/**
+ * PurpleAttentionType:
+ *
+ * Represents "nudges" and "buzzes" that you may send to a buddy to attract
+ * their attention (or vice-versa).
  */
 typedef struct _PurpleAttentionType PurpleAttentionType;
 
@@ -46,110 +48,77 @@ typedef struct _PurpleAttentionType PurpleAttentionType;
 /** @name Basic Protocol Information                                      */
 /**************************************************************************/
 
+/**
+ * PurpleIconScaleRules:
+ * @PURPLE_ICON_SCALE_DISPLAY: We scale the icon when we display it
+ * @PURPLE_ICON_SCALE_SEND:    We scale the icon before we send it to the server
+ */
 typedef enum  /*< flags >*/
 {
-	PURPLE_ICON_SCALE_DISPLAY = 0x01,		/**< We scale the icon when we display it */
-	PURPLE_ICON_SCALE_SEND = 0x02			/**< We scale the icon before we send it to the server */
+	PURPLE_ICON_SCALE_DISPLAY = 0x01,
+	PURPLE_ICON_SCALE_SEND    = 0x02
+	
 } PurpleIconScaleRules;
 
-/**
- * Represents an entry containing information that must be supplied by the
- * user when joining a chat.
- */
 typedef struct _PurpleProtocolChatEntry PurpleProtocolChatEntry;
 
 /**
+ * PurpleProtocolOptions:
+ * @OPT_PROTO_UNIQUE_CHATNAME: User names are unique to a chat and are not
+ *           shared between rooms.<br/>
+ *           XMPP lets you choose what name you want in chats, so it shouldn't
+ *           be pulling the aliases from the buddy list for the chat list; it
+ *           gets annoying.
+ * @OPT_PROTO_CHAT_TOPIC: Chat rooms have topics.<br/>
+ *           IRC and XMPP support this.
+ * @OPT_PROTO_NO_PASSWORD: Don't require passwords for sign-in.<br/>
+ *           Zephyr doesn't require passwords, so there's no need for a
+ *           password prompt.
+ * @OPT_PROTO_MAIL_CHECK: Notify on new mail.<br/>
+ *           MSN and Yahoo notify you when you have new mail.
+ * @OPT_PROTO_IM_IMAGE: Images in IMs.<br/>
+ *           Oscar lets you send images in direct IMs.
+ * @OPT_PROTO_PASSWORD_OPTIONAL: Allow passwords to be optional.<br/>
+ *           Passwords in IRC are optional, and are needed for certain
+ *           functionality.
+ * @OPT_PROTO_USE_POINTSIZE: Allows font size to be specified in sane point
+ *           size.<br/>
+ *           Probably just XMPP and Y!M
+ * @OPT_PROTO_REGISTER_NOSCREENNAME: Set the Register button active even when
+ *           the username has not been specified.<br/>
+ *           Gadu-Gadu doesn't need a username to register new account (because
+ *           usernames are assigned by the server).
+ * @OPT_PROTO_SLASH_COMMANDS_NATIVE: Indicates that slash commands are native
+ *           to this protocol.<br/>
+ *           Used as a hint that unknown commands should not be sent as
+ *           messages.
+ * @OPT_PROTO_INVITE_MESSAGE: Indicates that this protocol supports sending a
+ *           user-supplied message along with an invitation.
+ * @OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE: Indicates that this protocol
+ *           supports sending a user-supplied message along with an
+ *           authorization acceptance.
+ * @OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE: Indicates that this protocol
+ *           supports sending a user-supplied message along with an
+ *           authorization denial.
+ *
  * Protocol options
  *
  * These should all be stuff that some protocols can do and others can't.
  */
 typedef enum  /*< flags >*/
 {
-	/**
-	 * User names are unique to a chat and are not shared between rooms.
-	 *
-	 * XMPP lets you choose what name you want in chats, so it shouldn't
-	 * be pulling the aliases from the buddy list for the chat list;
-	 * it gets annoying.
-	 */
-	OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
-
-	/**
-	 * Chat rooms have topics.
-	 *
-	 * IRC and XMPP support this.
-	 */
-	OPT_PROTO_CHAT_TOPIC = 0x00000008,
-
-	/**
-	 * Don't require passwords for sign-in.
-	 *
-	 * Zephyr doesn't require passwords, so there's no
-	 * need for a password prompt.
-	 */
-	OPT_PROTO_NO_PASSWORD = 0x00000010,
-
-	/**
-	 * Notify on new mail.
-	 *
-	 * MSN and Yahoo notify you when you have new mail.
-	 */
-	OPT_PROTO_MAIL_CHECK = 0x00000020,
-
-	/**
-	 * Images in IMs.
-	 *
-	 * Oscar lets you send images in direct IMs.
-	 */
-	OPT_PROTO_IM_IMAGE = 0x00000040,
-
-	/**
-	 * Allow passwords to be optional.
-	 *
-	 * Passwords in IRC are optional, and are needed for certain
-	 * functionality.
-	 */
-	OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
-
-	/**
-	 * Allows font size to be specified in sane point size
-	 *
-	 * Probably just XMPP and Y!M
-	 */
-	OPT_PROTO_USE_POINTSIZE = 0x00000100,
-
-	/**
-	 * Set the Register button active even when the username has not
-	 * been specified.
-	 *
-	 * Gadu-Gadu doesn't need a username to register new account (because
-	 * usernames are assigned by the server).
-	 */
-	OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
-
-	/**
-	 * Indicates that slash commands are native to this protocol.
-	 * Used as a hint that unknown commands should not be sent as messages.
-	 */
-	OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
-
-	/**
-	 * Indicates that this protocol supports sending a user-supplied message
-	 * along with an invitation.
-	 */
-	OPT_PROTO_INVITE_MESSAGE = 0x00000800,
-
-	/**
-	 * Indicates that this protocol supports sending a user-supplied message
-	 * along with an authorization acceptance.
-	 */
+	OPT_PROTO_UNIQUE_CHATNAME               = 0x00000004,
+	OPT_PROTO_CHAT_TOPIC                    = 0x00000008,
+	OPT_PROTO_NO_PASSWORD                   = 0x00000010,
+	OPT_PROTO_MAIL_CHECK                    = 0x00000020,
+	OPT_PROTO_IM_IMAGE                      = 0x00000040,
+	OPT_PROTO_PASSWORD_OPTIONAL             = 0x00000080,
+	OPT_PROTO_USE_POINTSIZE                 = 0x00000100,
+	OPT_PROTO_REGISTER_NOSCREENNAME         = 0x00000200,
+	OPT_PROTO_SLASH_COMMANDS_NATIVE         = 0x00000400,
+	OPT_PROTO_INVITE_MESSAGE                = 0x00000800,
 	OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE = 0x00001000,
-
-	/**
-	 * Indicates that this protocol supports sending a user-supplied message
-	 * along with an authorization denial.
-	 */
-	OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE = 0x00002000
+	OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE  = 0x00002000
 
 } PurpleProtocolOptions;
 
@@ -159,18 +128,32 @@ typedef enum  /*< flags >*/
 
 #define PURPLE_TYPE_PROTOCOL_CHAT_ENTRY  (purple_protocol_chat_entry_get_type())
 
-/** @copydoc PurpleProtocolChatEntry */
+/**
+ * PurpleProtocolChatEntry:
+ * @label:      User-friendly name of the entry
+ * @identifier: Used by the protocol to identify the option
+ * @required:   True if it's required
+ * @is_int:     True if the entry expects an integer
+ * @min:        Minimum value in case of integer
+ * @max:        Maximum value in case of integer
+ * @secret:     True if the entry is secret (password)
+ *
+ * Represents an entry containing information that must be supplied by the
+ * user when joining a chat.
+ */
 struct _PurpleProtocolChatEntry {
-	const char *label;       /**< User-friendly name of the entry */
-	const char *identifier;  /**< Used by the protocol to identify the option */
-	gboolean required;       /**< True if it's required */
-	gboolean is_int;         /**< True if the entry expects an integer */
-	int min;                 /**< Minimum value in case of integer */
-	int max;                 /**< Maximum value in case of integer */
-	gboolean secret;         /**< True if the entry is secret (password) */
+	const char *label;
+	const char *identifier;
+	gboolean required;
+	gboolean is_int;
+	int min;
+	int max;
+	gboolean secret;
 };
 
 /**
+ * PurpleProtocolAction:
+ *
  * Represents an action that the protocol can perform. This shows up in the
  * Accounts menu, under a submenu with the name of the account.
  */
@@ -189,111 +172,130 @@ G_BEGIN_DECLS
 /*@{*/
 
 /**
+ * purple_attention_type_get_type:
+ *
  * Returns the GType for the #PurpleAttentionType boxed structure.
  */
 GType purple_attention_type_get_type(void);
 
 /**
- * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
- *
+ * purple_attention_type_new:
  * @ulname: A non-localized string that can be used by UIs in need of such
- *               non-localized strings.  This should be the same as @a name,
+ *               non-localized strings.  This should be the same as @name,
  *               without localization.
  * @name: A localized string that the UI may display for the event. This
- *             should be the same string as @a ulname, with localization.
+ *             should be the same string as @ulname, with localization.
  * @inc_desc: A localized description shown when the event is received.
  * @out_desc: A localized description shown when the event is sent.
  *
+ * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
+ *
  * Returns: A pointer to the new object.
  */
 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
 								const char *inc_desc, const char *out_desc);
 
 /**
- * Sets the displayed name of the attention-demanding event.
- *
+ * purple_attention_type_set_name:
  * @type: The attention type.
  * @name: The localized name that will be displayed by UIs. This should be
  *             the same string given as the unlocalized name, but with
  *             localization.
+ *
+ * Sets the displayed name of the attention-demanding event.
  */
 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
 
 /**
- * Sets the description of the attention-demanding event shown in  conversations
- * when the event is received.
- *
+ * purple_attention_type_set_incoming_desc:
  * @type: The attention type.
  * @desc: The localized description for incoming events.
+ *
+ * Sets the description of the attention-demanding event shown in  conversations
+ * when the event is received.
  */
 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
 
 /**
- * Sets the description of the attention-demanding event shown in conversations
- * when the event is sent.
- *
+ * purple_attention_type_set_outgoing_desc:
  * @type: The attention type.
  * @desc: The localized description for outgoing events.
+ *
+ * Sets the description of the attention-demanding event shown in conversations
+ * when the event is sent.
  */
 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
 
 /**
- * Sets the name of the icon to display for the attention event; this is optional.
- *
+ * purple_attention_type_set_icon_name:
  * @type: The attention type.
  * @name: The icon's name.
+ *
+ * Sets the name of the icon to display for the attention event; this is optional.
+ *
  * Note: Icons are optional for attention events.
  */
 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
 
 /**
- * Sets the unlocalized name of the attention event; some UIs may need this,
- * thus it is required.
- *
+ * purple_attention_type_set_unlocalized_name:
  * @type: The attention type.
  * @ulname: The unlocalized name.  This should be the same string given as
  *               the localized name, but without localization.
+ *
+ * Sets the unlocalized name of the attention event; some UIs may need this,
+ * thus it is required.
  */
 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
 
 /**
- * Get the attention type's name as displayed by the UI.
- *
+ * purple_attention_type_get_name:
  * @type: The attention type.
  *
+ * Get the attention type's name as displayed by the UI.
+ *
  * Returns: The name.
  */
 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
 
 /**
+ * purple_attention_type_get_incoming_desc:
+ * @type: The attention type.
+ *
  * Get the attention type's description shown when the event is received.
  *
- * @type: The attention type.
  * Returns: The description.
  */
 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
 
 /**
+ * purple_attention_type_get_outgoing_desc:
+ * @type: The attention type.
+ *
  * Get the attention type's description shown when the event is sent.
  *
- * @type: The attention type.
  * Returns: The description.
  */
 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
 
 /**
+ * purple_attention_type_get_icon_name:
+ * @type: The attention type.
+ *
  * Get the attention type's icon name.
  *
- * @type: The attention type.
- * Returns: The icon name or %NULL if unset/empty.
  * Note: Icons are optional for attention events.
+ *
+ * Returns: The icon name or %NULL if unset/empty.
  */
 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
 
 /**
+ * purple_attention_type_get_unlocalized_name:
+ * @type: The attention type
+ *
  * Get the attention type's unlocalized name; this is useful for some UIs.
  *
- * @type: The attention type
  * Returns: The unlocalized name.
  */
 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
@@ -306,24 +308,28 @@ const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType
 /*@{*/
 
 /**
+ * purple_protocol_action_get_type:
+ *
  * Returns the GType for the #PurpleProtocolAction boxed structure.
  */
 GType purple_protocol_action_get_type(void);
 
 /**
- * Allocates and returns a new PurpleProtocolAction. Use this to add actions in
- * a list in the get_actions function of the protocol.
- *
+ * purple_protocol_action_new:
  * @label:    The description of the action to show to the user.
  * @callback: The callback to call when the user selects this action.
+ *
+ * Allocates and returns a new PurpleProtocolAction. Use this to add actions in
+ * a list in the get_actions function of the protocol.
  */
 PurpleProtocolAction *purple_protocol_action_new(const char* label,
 		PurpleProtocolActionCallback callback);
 
 /**
- * Frees a PurpleProtocolAction
- *
+ * purple_protocol_action_free:
  * @action: The PurpleProtocolAction to free.
+ *
+ * Frees a PurpleProtocolAction
  */
 void purple_protocol_action_free(PurpleProtocolAction *action);
 
@@ -335,6 +341,8 @@ void purple_protocol_action_free(PurpleProtocolAction *action);
 /*@{*/
 
 /**
+ * purple_protocol_chat_entry_get_type:
+ *
  * Returns the GType for the #PurpleProtocolChatEntry boxed structure.
  */
 GType purple_protocol_chat_entry_get_type(void);
@@ -347,60 +355,61 @@ GType purple_protocol_chat_entry_get_type(void);
 /*@{*/
 
 /**
- * Notifies Purple that our account's idle state and time have changed.
- *
- * This is meant to be called from protocols.
- *
+ * purple_protocol_got_account_idle:
  * @account:   The account.
  * @idle:      The user's idle state.
  * @idle_time: The user's idle time.
+ *
+ * Notifies Purple that our account's idle state and time have changed.
+ *
+ * This is meant to be called from protocols.
  */
 void purple_protocol_got_account_idle(PurpleAccount *account, gboolean idle,
                                       time_t idle_time);
 
 /**
+ * purple_protocol_got_account_login_time:
+ * @account:    The account the user is on.
+ * @login_time: The user's log-in time.
+ *
  * Notifies Purple of our account's log-in time.
  *
  * This is meant to be called from protocols.
- *
- * @account:    The account the user is on.
- * @login_time: The user's log-in time.
  */
 void purple_protocol_got_account_login_time(PurpleAccount *account,
                                             time_t login_time);
 
 /**
- * Notifies Purple that our account's status has changed.
- *
- * This is meant to be called from protocols.
- *
+ * purple_protocol_got_account_status:
  * @account:   The account the user is on.
  * @status_id: The status ID.
  * @...:       A NULL-terminated list of attribute IDs and values,
- *                  beginning with the value for @a attr_id.
+ *             beginning with the value for %attr_id.
+ *
+ * Notifies Purple that our account's status has changed.
+ *
+ * This is meant to be called from protocols.
  */
 void purple_protocol_got_account_status(PurpleAccount *account,
                                         const char *status_id, ...)
                                         G_GNUC_NULL_TERMINATED;
 
 /**
+ * purple_protocol_got_account_actions:
+ * @account:   The account.
+ *
  * Notifies Purple that our account's actions have changed. This is only
  * called after the initial connection. Emits the account-actions-changed
  * signal.
  *
  * This is meant to be called from protocols.
  *
- * @account:   The account.
- *
  * @see account-actions-changed
  */
 void purple_protocol_got_account_actions(PurpleAccount *account);
 
 /**
- * Notifies Purple that a buddy's idle state and time have changed.
- *
- * This is meant to be called from protocols.
- *
+ * purple_protocol_got_user_idle:
  * @account:   The account the user is on.
  * @name:      The name of the buddy.
  * @idle:      The user's idle state.
@@ -408,76 +417,84 @@ void purple_protocol_got_account_actions(PurpleAccount *account);
  *                  which the user became idle, in seconds since
  *                  the epoch.  If the protocol does not know this value
  *                  then it should pass 0.
+ *
+ * Notifies Purple that a buddy's idle state and time have changed.
+ *
+ * This is meant to be called from protocols.
  */
 void purple_protocol_got_user_idle(PurpleAccount *account, const char *name,
                                    gboolean idle, time_t idle_time);
 
 /**
- * Notifies Purple of a buddy's log-in time.
- *
- * This is meant to be called from protocols.
- *
+ * purple_protocol_got_user_login_time:
  * @account:    The account the user is on.
  * @name:       The name of the buddy.
  * @login_time: The user's log-in time.
+ *
+ * Notifies Purple of a buddy's log-in time.
+ *
+ * This is meant to be called from protocols.
  */
 void purple_protocol_got_user_login_time(PurpleAccount *account,
                                          const char *name, time_t login_time);
 
 /**
- * Notifies Purple that a buddy's status has been activated.
- *
- * This is meant to be called from protocols.
- *
+ * purple_protocol_got_user_status:
  * @account:   The account the user is on.
  * @name:      The name of the buddy.
  * @status_id: The status ID.
  * @...:       A NULL-terminated list of attribute IDs and values,
- *                  beginning with the value for @a attr_id.
+ *             beginning with the value for %attr_id.
+ *
+ * Notifies Purple that a buddy's status has been activated.
+ *
+ * This is meant to be called from protocols.
  */
 void purple_protocol_got_user_status(PurpleAccount *account, const char *name,
                                      const char *status_id, ...)
                                      G_GNUC_NULL_TERMINATED;
 
 /**
- * Notifies libpurple that a buddy's status has been deactivated
- *
- * This is meant to be called from protocols.
- *
+ * purple_protocol_got_user_status_deactive:
  * @account:   The account the user is on.
  * @name:      The name of the buddy.
  * @status_id: The status ID.
+ *
+ * Notifies libpurple that a buddy's status has been deactivated
+ *
+ * This is meant to be called from protocols.
  */
 void purple_protocol_got_user_status_deactive(PurpleAccount *account,
                                               const char *name,
                                               const char *status_id);
 
 /**
- * Informs the server that our account's status changed.
- *
+ * purple_protocol_change_account_status:
  * @account:    The account the user is on.
  * @old_status: The previous status.
  * @new_status: The status that was activated, or deactivated
  *                   (in the case of independent statuses).
+ *
+ * Informs the server that our account's status changed.
  */
 void purple_protocol_change_account_status(PurpleAccount *account,
                                            PurpleStatus *old_status,
                                            PurpleStatus *new_status);
 
 /**
- * Retrieves the list of stock status types from a protocol.
- *
+ * purple_protocol_get_statuses:
  * @account: The account the user is on.
  * @presence: The presence for which we're going to get statuses
  *
+ * Retrieves the list of stock status types from a protocol.
+ *
  * Returns: List of statuses
  */
 GList *purple_protocol_get_statuses(PurpleAccount *account,
                                     PurplePresence *presence);
 
 /**
- * Send an attention request message.
- *
+ * purple_protocol_send_attention:
  * @gc: The connection to send the message on.
  * @who: Whose attention to request.
  * @type_code: An index into the protocol's attention_types list
@@ -485,6 +502,8 @@ GList *purple_protocol_get_statuses(PurpleAccount *account,
  *                  send. 0 if protocol only defines one (for example, Yahoo and
  *                  MSN), but some protocols define more (MySpaceIM).
  *
+ * Send an attention request message.
+ *
  * Note that you can't send arbitrary PurpleAttentionType's, because there is
  * only a fixed set of attention commands.
  */
@@ -492,72 +511,78 @@ void purple_protocol_send_attention(PurpleConnection *gc, const char *who,
                                     guint type_code);
 
 /**
- * Process an incoming attention message.
- *
+ * purple_protocol_got_attention:
  * @gc: The connection that received the attention message.
  * @who: Who requested your attention.
  * @type_code: An index into the protocol's attention_types list
  *                  determining the type of the attention request command to
  *                  send.
+ *
+ * Process an incoming attention message.
  */
 void purple_protocol_got_attention(PurpleConnection *gc, const char *who,
                                    guint type_code);
 
 /**
- * Process an incoming attention message in a chat.
- *
+ * purple_protocol_got_attention_in_chat:
  * @gc: The connection that received the attention message.
  * @id: The chat id.
  * @who: Who requested your attention.
  * @type_code: An index into the protocol's attention_types list
  *                  determining the type of the attention request command to
  *                  send.
+ *
+ * Process an incoming attention message in a chat.
  */
 void purple_protocol_got_attention_in_chat(PurpleConnection *gc, int id,
                                            const char *who, guint type_code);
 
 /**
- * Determines if the contact supports the given media session type.
- *
+ * purple_protocol_get_media_caps:
  * @account: The account the user is on.
  * @who: The name of the contact to check capabilities for.
  *
+ * Determines if the contact supports the given media session type.
+ *
  * Returns: The media caps the contact supports.
  */
 PurpleMediaCaps purple_protocol_get_media_caps(PurpleAccount *account,
                                                const char *who);
 
 /**
- * Initiates a media session with the given contact.
- *
+ * purple_protocol_initiate_media:
  * @account: The account the user is on.
  * @who: The name of the contact to start a session with.
  * @type: The type of media session to start.
  *
+ * Initiates a media session with the given contact.
+ *
  * Returns: TRUE if the call succeeded else FALSE. (Doesn't imply the media
- *         session or stream will be successfully created)
+ *          session or stream will be successfully created)
  */
 gboolean purple_protocol_initiate_media(PurpleAccount *account,
                                         const char *who,
                                         PurpleMediaSessionType type);
 
 /**
+ * purple_protocol_got_media_caps:
+ * @account: The account the user is on.
+ * @who: The name of the contact for which capabilities have been received.
+ *
  * Signals that the protocol received capabilities for the given contact.
  *
  * This function is intended to be used only by protocols.
- *
- * @account: The account the user is on.
- * @who: The name of the contact for which capabilities have been received.
  */
 void purple_protocol_got_media_caps(PurpleAccount *account, const char *who);
 
 /**
+ * purple_protocol_get_max_message_size:
+ * @protocol: The protocol to query.
+ *
  * Gets the safe maximum message size in bytes for the protocol.
  *
  * @see PurpleProtocol#get_max_message_size
  *
- * @protocol: The protocol to query.
- *
  * Returns: Maximum message size, 0 if unspecified, -1 for infinite.
  */
 gssize
@@ -571,37 +596,42 @@ purple_protocol_get_max_message_size(PurpleProtocol *protocol);
 /*@{*/
 
 /**
- * Finds a protocol by ID.
- *
+ * purple_protocols_find:
  * @id: The protocol's ID.
+ *
+ * Finds a protocol by ID.
  */
 PurpleProtocol *purple_protocols_find(const char *id);
 
 /**
- * Adds a protocol to the list of protocols.
- *
+ * purple_protocols_add:
  * @protocol_type:  The type of the protocol to add.
  * @error:  Return location for a #GError or %NULL. If provided, this
- *               will be set to the reason if adding fails.
+ *          will be set to the reason if adding fails.
+ *
+ * Adds a protocol to the list of protocols.
  *
  * Returns: The protocol instance if the protocol was added, else %NULL.
  */
 PurpleProtocol *purple_protocols_add(GType protocol_type, GError **error);
 
 /**
+ * purple_protocols_remove:
+ * @protocol:  The protocol to remove.
+ * @error:  Return location for a #GError or %NULL. If provided, this
+ *          will be set to the reason if removing fails.
+ *
  * Removes a protocol from the list of protocols. This will disconnect all
  * connected accounts using this protocol, and free the protocol's user splits
  * and protocol options.
  *
- * @protocol:  The protocol to remove.
- * @error:  Return location for a #GError or %NULL. If provided, this
- *               will be set to the reason if removing fails.
- *
  * Returns: TRUE if the protocol was removed, else FALSE.
  */
 gboolean purple_protocols_remove(PurpleProtocol *protocol, GError **error);
 
 /**
+ * purple_protocols_get_all:
+ *
  * Returns a list of all loaded protocols.
  *
  * Returns: A list of all loaded protocols. The list is owned by the caller, and
@@ -617,11 +647,15 @@ GList *purple_protocols_get_all(void);
 /*@{*/
 
 /**
+ * purple_protocols_init:
+ *
  * Initializes the protocols subsystem.
  */
 void purple_protocols_init(void);
 
 /**
+ * purple_protocols_get_handle:
+ *
  * Returns the protocols subsystem handle.
  *
  * Returns: The protocols subsystem handle.
@@ -629,6 +663,8 @@ void purple_protocols_init(void);
 void *purple_protocols_get_handle(void);
 
 /**
+ * purple_protocols_uninit:
+ *
  * Uninitializes the protocols subsystem.
  */
 void purple_protocols_uninit(void);