/pidgin/main: 5f45ba259934: Improve GIntrospection annotations f...

[Jorge Villase?or]

Changeset: 5f45ba259934bf3f2f4f48cf257850ce2c835288
Author:	 Jorge Villase?or <salinasv at pidgin.im>
Date:	 2015-12-05 20:26 -0800
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/5f45ba259934

Description:

Improve GIntrospection annotations for Chat and IM

diffstat:

 libpurple/conversationtypes.h |  43 +++++++++++++++++++++++++++++--------------
 1 files changed, 29 insertions(+), 14 deletions(-)

diffs (138 lines):

diff --git a/libpurple/conversationtypes.h b/libpurple/conversationtypes.h
--- a/libpurple/conversationtypes.h
+++ b/libpurple/conversationtypes.h
@@ -29,7 +29,7 @@
  */
 
 /**************************************************************************/
-/** Data Structures                                                       */
+/* Data Structures                                                        */
 /**************************************************************************/
 
 #define PURPLE_TYPE_IM_CONVERSATION              (purple_im_conversation_get_type())
@@ -105,7 +105,7 @@ typedef enum /*< flags >*/
 #include "conversation.h"
 
 /**************************************************************************/
-/** PurpleIMConversation                                                  */
+/* PurpleIMConversation                                                   */
 /**************************************************************************/
 /**
  * PurpleIMConversation:
@@ -133,7 +133,7 @@ struct _PurpleIMConversationClass {
 };
 
 /**************************************************************************/
-/** PurpleChatConversation                                                */
+/* PurpleChatConversation                                                 */
 /**************************************************************************/
 /**
  * PurpleChatConversation:
@@ -161,7 +161,7 @@ struct _PurpleChatConversationClass {
 };
 
 /**************************************************************************/
-/** PurpleChatUser                                                        */
+/* PurpleChatUser                                                         */
 /**************************************************************************/
 /**
  * PurpleChatUser:
@@ -380,7 +380,8 @@ PurpleChatConversation *purple_chat_conv
  * Returns a list of users in the chat room.  The members of the list
  * are PurpleChatUser objects.
  *
- * Returns: (transfer container): The list of users. Use g_list_free() when done
+ * Returns: (element-type PurpleChatUser) (transfer container):
+ *          The list of users. Use g_list_free() when done
  *          using the list.
  */
 GList *purple_chat_conversation_get_users(const PurpleChatConversation *chat);
@@ -417,11 +418,13 @@ void purple_chat_conversation_unignore(P
 /**
  * purple_chat_conversation_set_ignored:
  * @chat:    The chat.
- * @ignored: The list of ignored users.
+ * @ignored: (element-type char*):
+ *           The list of ignored users.
  *
  * Sets the list of ignored users in the chat room.
  *
- * Returns: The list passed.
+ * Returns: (element-type char*) (transfer none):
+ *          The list passed.
  */
 GList *purple_chat_conversation_set_ignored(PurpleChatConversation *chat, GList *ignored);
 
@@ -431,7 +434,8 @@ GList *purple_chat_conversation_set_igno
  *
  * Returns the list of ignored users in the chat room.
  *
- * Returns: (transfer none): The list of ignored users.
+ * Returns: (element-type char*) (transfer none):
+ *          The list of ignored users.
  */
 GList *purple_chat_conversation_get_ignored(const PurpleChatConversation *chat);
 
@@ -532,14 +536,19 @@ void purple_chat_conversation_add_user(P
 /**
  * purple_chat_conversation_add_users:
  * @chat:         The chat.
- * @users:        The list of users to add.
- * @extra_msgs:   An extra message to display with the join message for each
+ * @users: (element-type char*):
+ *                The list of users to add.
+ * @extra_msgs: (element-type char*) (nullable):
+ *                An extra message to display with the join message for each
  *                     user.  This list may be shorter than @users, in which
  *                     case, the users after the end of extra_msgs will not have
  *                     an extra message.  By extension, this means that extra_msgs
  *                     can simply be %NULL and none of the users will have an
  *                     extra message.
- * @flags:        The list of flags for each user.
+ * @flags: (element-type PurpleChatUserFlags):
+ *                The list of flags for each user.
+ *                This list data should be an int converted to pointer using
+ *                GINT_TO_POINTER(flag)
  * @new_arrivals: Decides whether or not to show join notices.
  *
  * Adds a list of users to a chat.
@@ -577,7 +586,8 @@ void purple_chat_conversation_remove_use
 /**
  * purple_chat_conversation_remove_users:
  * @chat:   The chat.
- * @users:  The users that are being removed.
+ * @users: (element-type char*)
+ *          The users that are being removed.
  * @reason: The optional reason given for the removal. Can be %NULL.
  *
  * Removes a list of users from a chat, optionally with a single reason.
@@ -640,6 +650,9 @@ void purple_chat_conversation_leave(Purp
  * @name: The name of the chat user to find.
  *
  * Find a chat user in a chat
+ *
+ * Returns: (transfer none):
+ *         The @PurpleChatUser with the name refered by @name.
  */
 PurpleChatUser *purple_chat_conversation_find_user(PurpleChatConversation *chat,
 		const char *name);
@@ -698,7 +711,8 @@ void purple_chat_user_set_chat(PurpleCha
  *
  * Get the chat conversation associated with this chat user.
  *
- * Returns:		The chat conversation that the buddy belongs to.
+ * Returns: (transfer none):
+ *          The chat conversation that the buddy belongs to.
  */
 PurpleChatConversation *purple_chat_user_get_chat(const PurpleChatUser *cb);
 
@@ -731,7 +745,8 @@ void purple_chat_user_set_ui_data(Purple
  *
  * Get the UI data associated with this chat user.
  *
- * Returns: The UI data associated with this chat user.  This is a
+ * Returns: (transfer none):
+ *         The UI data associated with this chat user.  This is a
  *         convenience field provided to the UIs--it is not
  *         used by the libpurple core.
  */