--- a/libpurple/conversation.h Wed Jan 29 00:28:08 2014 +0530
+++ b/libpurple/conversation.h Wed Jan 29 05:28:33 2014 +0530
@@ -208,8 +208,8 @@
time_t mtime);
/** Add @a cbuddies to a chat.
- * @param cbuddies A @c GList of #PurpleChatUser structs.
- * @param new_arrivals Whether join notices should be shown.
+ * @cbuddies: A @c GList of #PurpleChatUser structs.
+ * @new_arrivals: Whether join notices should be shown.
* (Join notices are actually written to the
* conversation by
* #purple_chat_conversation_add_users().)
@@ -219,13 +219,13 @@
gboolean new_arrivals);
/** Rename the user in this chat named @a old_name to @a new_name. (The
* rename message is written to the conversation by libpurple.)
- * @param new_alias @a new_name's new alias, if they have one.
+ * @new_alias: @a new_name's new alias, if they have one.
* @see purple_chat_conversation_add_users()
*/
void (*chat_rename_user)(PurpleChatConversation *chat, const char *old_name,
const char *new_name, const char *new_alias);
/** Remove @a users from a chat.
- * @param users A @c GList of <tt>const char *</tt>s.
+ * @users: A @c GList of <tt>const char *</tt>s.
* @see purple_chat_conversation_rename_user()
*/
void (*chat_remove_users)(PurpleChatConversation *chat, GList *users);
@@ -281,15 +281,15 @@
/**
* Present a conversation to the user. This allows core code to initiate a
* conversation by displaying the IM dialog.
- * @param conv The conversation to present
+ * @conv: The conversation to present
*/
void purple_conversation_present(PurpleConversation *conv);
/**
* Sets the specified conversation's UI operations structure.
*
- * @param conv The conversation.
- * @param ops The UI conversation operations structure.
+ * @conv: The conversation.
+ * @ops: The UI conversation operations structure.
*/
void purple_conversation_set_ui_ops(PurpleConversation *conv,
PurpleConversationUiOps *ops);
@@ -297,9 +297,9 @@
/**
* Returns the specified conversation's UI operations structure.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return The operations structure.
+ * Returns: The operations structure.
*/
PurpleConversationUiOps *purple_conversation_get_ui_ops(const PurpleConversation *conv);
@@ -309,8 +309,8 @@
* This purple_account represents the user using purple, not the person the user
* is having a conversation/chat/flame with.
*
- * @param conv The conversation.
- * @param account The purple_account.
+ * @conv: The conversation.
+ * @account: The purple_account.
*/
void purple_conversation_set_account(PurpleConversation *conv,
PurpleAccount *account);
@@ -321,35 +321,35 @@
* This purple_account represents the user using purple, not the person the user
* is having a conversation/chat/flame with.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return The conversation's purple_account.
+ * Returns: The conversation's purple_account.
*/
PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv);
/**
* Returns the specified conversation's purple_connection.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return The conversation's purple_connection.
+ * Returns: The conversation's purple_connection.
*/
PurpleConnection *purple_conversation_get_connection(const PurpleConversation *conv);
/**
* Sets the specified conversation's title.
*
- * @param conv The conversation.
- * @param title The title.
+ * @conv: The conversation.
+ * @title: The title.
*/
void purple_conversation_set_title(PurpleConversation *conv, const char *title);
/**
* Returns the specified conversation's title.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return The title.
+ * Returns: The title.
*/
const char *purple_conversation_get_title(const PurpleConversation *conv);
@@ -359,24 +359,24 @@
* This function takes OPT_IM_ALIAS_TAB into account, as well as the
* user's alias.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*/
void purple_conversation_autoset_title(PurpleConversation *conv);
/**
* Sets the specified conversation's name.
*
- * @param conv The conversation.
- * @param name The conversation's name.
+ * @conv: The conversation.
+ * @name: The conversation's name.
*/
void purple_conversation_set_name(PurpleConversation *conv, const char *name);
/**
* Returns the specified conversation's name.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return The conversation's name. If the conversation is an IM with a PurpleBuddy,
+ * Returns: The conversation's name. If the conversation is an IM with a PurpleBuddy,
* then it's the name of the PurpleBuddy.
*/
const char *purple_conversation_get_name(const PurpleConversation *conv);
@@ -384,8 +384,8 @@
/**
* Sets current E2EE state for the conversation.
*
- * @param conv The conversation.
- * @param state The E2EE state.
+ * @conv: The conversation.
+ * @state: The E2EE state.
*/
void
purple_conversation_set_e2ee_state(PurpleConversation *conv,
@@ -394,9 +394,9 @@
/**
* Gets current conversation's E2EE state.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return Current E2EE state for conversation.
+ * Returns: Current E2EE state for conversation.
*/
PurpleE2eeState *
purple_conversation_get_e2ee_state(PurpleConversation *conv);
@@ -404,17 +404,17 @@
/**
* Enables or disables logging for this conversation.
*
- * @param conv The conversation.
- * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
+ * @conv: The conversation.
+ * @log: @c TRUE if logging should be enabled, or @c FALSE otherwise.
*/
void purple_conversation_set_logging(PurpleConversation *conv, gboolean log);
/**
* Returns whether or not logging is enabled for this conversation.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
+ * Returns: @c TRUE if logging is enabled, or @c FALSE otherwise.
*/
gboolean purple_conversation_is_logging(const PurpleConversation *conv);
@@ -425,7 +425,7 @@
* message, if the conversation has logging enabled. To disable logging for
* the remainder of the conversation, use purple_conversation_set_logging().
*
- * @param conv The conversation.
+ * @conv: The conversation.
*/
void purple_conversation_close_logs(PurpleConversation *conv);
@@ -441,11 +441,11 @@
* This can be used to write generic messages, such as "so and so closed
* the conversation window."
*
- * @param conv The conversation.
- * @param who The user who sent the message.
- * @param message The message.
- * @param flags The message flags.
- * @param mtime The time the message was sent.
+ * @conv: The conversation.
+ * @who: The user who sent the message.
+ * @message: The message.
+ * @flags: The message flags.
+ * @mtime: The time the message was sent.
*
* @see purple_conversation_write_message()
*/
@@ -456,11 +456,11 @@
/**
* Writes to a chat or an IM.
*
- * @param conv The conversation.
- * @param who The user who sent the message.
- * @param message The message to write.
- * @param flags The message flags.
- * @param mtime The time the message was sent.
+ * @conv: The conversation.
+ * @who: The user who sent the message.
+ * @message: The message to write.
+ * @flags: The message flags.
+ * @mtime: The time the message was sent.
*/
void purple_conversation_write_message(PurpleConversation *conv,
const char *who, const char *message,
@@ -470,17 +470,17 @@
* Sends a message to this conversation. This function calls
* purple_conversation_send_with_flags() with no additional flags.
*
- * @param conv The conversation.
- * @param message The message to send.
+ * @conv: The conversation.
+ * @message: The message to send.
*/
void purple_conversation_send(PurpleConversation *conv, const char *message);
/**
* Sends a message to this conversation with specified flags.
*
- * @param conv The conversation.
- * @param message The message to send.
- * @param flags The PurpleMessageFlags flags to use in addition to
+ * @conv: The conversation.
+ * @message: The message to send.
+ * @flags: The PurpleMessageFlags flags to use in addition to
* PURPLE_MESSAGE_SEND.
*/
void purple_conversation_send_with_flags(PurpleConversation *conv, const char *message,
@@ -488,8 +488,8 @@
/**
Set the features as supported for the given conversation.
- @param conv The conversation
- @param features Bitset defining supported features
+ @conv: The conversation
+ @features: Bitset defining supported features
*/
void purple_conversation_set_features(PurpleConversation *conv,
PurpleConnectionFlags features);
@@ -497,16 +497,16 @@
/**
Get the features supported by the given conversation.
- @param conv The conversation
+ @conv: The conversation
*/
PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv);
/**
* Determines if a conversation has focus
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return @c TRUE if the conversation has focus, @c FALSE if
+ * Returns: @c TRUE if the conversation has focus, @c FALSE if
* it does not or the UI does not have a concept of conversation focus
*/
gboolean purple_conversation_has_focus(PurpleConversation *conv);
@@ -514,17 +514,17 @@
/**
* Updates the visual status and UI of a conversation.
*
- * @param conv The conversation.
- * @param type The update type.
+ * @conv: The conversation.
+ * @type: The update type.
*/
void purple_conversation_update(PurpleConversation *conv, PurpleConversationUpdateType type);
/**
* Retrieve the message history of a conversation.
*
- * @param conv The conversation
+ * @conv: The conversation
*
- * @return A GList of PurpleConversationMessage's. The must not modify the list or the data within.
+ * Returns: A GList of PurpleConversationMessage's. The must not modify the list or the data within.
* The list contains the newest message at the beginning, and the oldest message at
* the end.
*/
@@ -533,24 +533,24 @@
/**
* Clear the message history of a conversation.
*
- * @param conv The conversation
+ * @conv: The conversation
*/
void purple_conversation_clear_message_history(PurpleConversation *conv);
/**
* Set the UI data associated with this conversation.
*
- * @param conv The conversation.
- * @param ui_data A pointer to associate with this conversation.
+ * @conv: The conversation.
+ * @ui_data: A pointer to associate with this conversation.
*/
void purple_conversation_set_ui_data(PurpleConversation *conv, gpointer ui_data);
/**
* Get the UI data associated with this conversation.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return The UI data associated with this conversation. This is a
+ * Returns: The UI data associated with this conversation. This is a
* convenience field provided to the UIs--it is not
* used by the libpurple core.
*/
@@ -565,8 +565,8 @@
* The confirmation ensures that the user isn't sending a
* message by mistake.
*
- * @param conv The conversation.
- * @param message The message to send.
+ * @conv: The conversation.
+ * @message: The message to send.
*/
void purple_conversation_send_confirm(PurpleConversation *conv, const char *message);
@@ -578,12 +578,12 @@
* found in the cache. In either case, calling write or close would
* be an error.
*
- * @param conv The conversation to associate the smiley with.
- * @param smile The text associated with the smiley
- * @param cksum_type The type of checksum.
- * @param chksum The checksum, as a NUL terminated base64 string.
- * @param remote @c TRUE if the custom smiley is set by the remote user (buddy).
- * @return @c TRUE if an icon is expected, else FALSE. Note that
+ * @conv: The conversation to associate the smiley with.
+ * @smile: The text associated with the smiley
+ * @cksum_type: The type of checksum.
+ * @chksum: The checksum, as a NUL terminated base64 string.
+ * @remote: @c TRUE if the custom smiley is set by the remote user (buddy).
+ * Returns: @c TRUE if an icon is expected, else FALSE. Note that
* it is an error to never call purple_conversation_custom_smiley_close if
* this function returns @c TRUE, but an error to call it if
* @c FALSE is returned.
@@ -596,10 +596,10 @@
/**
* Updates the image associated with the current smiley.
*
- * @param conv The conversation associated with the smiley.
- * @param smile The text associated with the smiley.
- * @param data The actual image data.
- * @param size The length of the data.
+ * @conv: The conversation associated with the smiley.
+ * @smile: The text associated with the smiley.
+ * @data: The actual image data.
+ * @size: The length of the data.
*/
void purple_conversation_custom_smiley_write(PurpleConversation *conv,
@@ -612,8 +612,8 @@
* purple_conversation_custom_smiley_write, and it is no longer valid
* to call that function on that smiley.
*
- * @param conv The purple conversation associated with the smiley.
- * @param smile The text associated with the smiley
+ * @conv: The purple conversation associated with the smiley.
+ * @smile: The text associated with the smiley
*/
void purple_conversation_custom_smiley_close(PurpleConversation *conv, const char *smile);
@@ -621,9 +621,9 @@
/**
* Retrieves the extended menu items for the conversation.
*
- * @param conv The conversation.
+ * @conv: The conversation.
*
- * @return A list of PurpleMenuAction items, harvested by the
+ * Returns: A list of PurpleMenuAction items, harvested by the
* chat-extended-menu signal. The list and the menuaction
* items should be freed by the caller.
*/
@@ -632,13 +632,13 @@
/**
* Perform a command in a conversation. Similar to @see purple_cmd_do_command
*
- * @param conv The conversation.
- * @param cmdline The entire command including the arguments.
- * @param markup @c NULL, or the formatted command line.
- * @param error If the command failed errormsg is filled in with the appropriate error
+ * @conv: The conversation.
+ * @cmdline: The entire command including the arguments.
+ * @markup: @c NULL, or the formatted command line.
+ * @error: If the command failed errormsg is filled in with the appropriate error
* message, if not @c NULL. It must be freed by the caller with g_free().
*
- * @return @c TRUE if the command was executed successfully, @c FALSE otherwise.
+ * Returns: @c TRUE if the command was executed successfully, @c FALSE otherwise.
*/
gboolean purple_conversation_do_command(PurpleConversation *conv,
const gchar *cmdline, const gchar *markup, gchar **error);
@@ -648,9 +648,9 @@
*
* @see PurplePluginProtocolInfo#get_max_message_size
*
- * @param conv The conversation to query.
+ * @conv: The conversation to query.
*
- * @return Maximum message size, 0 if unspecified, -1 for infinite.
+ * Returns: Maximum message size, 0 if unspecified, -1 for infinite.
*/
gssize
purple_conversation_get_max_message_size(PurpleConversation *conv);
@@ -670,10 +670,10 @@
* the function will return FALSE and the calling function can attempt to present
* the error another way (purple_notify_error, most likely)
*
- * @param who The user this error is about
- * @param account The account this error is on
- * @param what The error
- * @return TRUE if the error was presented, else FALSE
+ * @who: The user this error is about
+ * @account: The account this error is on
+ * @what: The error
+ * Returns: TRUE if the error was presented, else FALSE
*/
gboolean purple_conversation_present_error(const char *who, PurpleAccount *account, const char *what);
@@ -692,54 +692,54 @@
/**
* Get the sender from a PurpleConversationMessage
*
- * @param msg A PurpleConversationMessage
+ * @msg: A PurpleConversationMessage
*
- * @return The name of the sender of the message
+ * Returns: The name of the sender of the message
*/
const char *purple_conversation_message_get_sender(const PurpleConversationMessage *msg);
/**
* Get the message from a PurpleConversationMessage
*
- * @param msg A PurpleConversationMessage
+ * @msg: A PurpleConversationMessage
*
- * @return The name of the sender of the message
+ * Returns: The name of the sender of the message
*/
const char *purple_conversation_message_get_message(const PurpleConversationMessage *msg);
/**
* Get the message-flags of a PurpleConversationMessage
*
- * @param msg A PurpleConversationMessage
+ * @msg: A PurpleConversationMessage
*
- * @return The message flags
+ * Returns: The message flags
*/
PurpleMessageFlags purple_conversation_message_get_flags(const PurpleConversationMessage *msg);
/**
* Get the timestamp of a PurpleConversationMessage
*
- * @param msg A PurpleConversationMessage
+ * @msg: A PurpleConversationMessage
*
- * @return The timestamp of the message
+ * Returns: The timestamp of the message
*/
time_t purple_conversation_message_get_timestamp(const PurpleConversationMessage *msg);
/**
* Get the alias from a PurpleConversationMessage
*
- * @param msg A PurpleConversationMessage
+ * @msg: A PurpleConversationMessage
*
- * @return The alias of the sender of the message
+ * Returns: The alias of the sender of the message
*/
const char *purple_conversation_message_get_alias(const PurpleConversationMessage *msg);
/**
* Get the conversation associated with the PurpleConversationMessage
*
- * @param msg A PurpleConversationMessage
+ * @msg: A PurpleConversationMessage
*
- * @return The conversation
+ * Returns: The conversation
*/
PurpleConversation *purple_conversation_message_get_conversation(const PurpleConversationMessage *msg);
