Merged in default (pull request #494)

A few more doc/gir fixups

Approved-by: Elliott Sales de Andrade

4 files changed, 345 insertions, 37 deletions

diff --git a/ChangeLog.API b/ChangeLog.API
index 297ad6d519..80b7f9a3ac 100644
--- a/ChangeLog.API
+++ b/ChangeLog.API
@@ -113,15 +113,11 @@ version 3.0.0 (??/??/????):
 		* PurpleProtocolFactoryIface
 		* purple_protocol_get_* for PurpleProtocol members
 		* purple_protocol_class_* for class methods
-		* purple_protocol_client_iface_* for client interface methods
 		* purple_protocol_server_iface_* for server interface methods
 		* purple_protocol_im_iface_* for IM interface methods
-		* purple_protocol_chat_iface_* for chat interface methods
 		* purple_protocol_privacy_iface_* for privacy interface methods
 		* purple_protocol_xfer_iface_* for xfer interface methods
-		* purple_protocol_roomlist_iface_* for roomlist interface methods
 		* purple_protocol_attention_iface_* for attention interface methods
-		* purple_protocol_media_iface_* for media interface methods
 		* purple_protocol_factory_iface_* for factory interface methods
 		* purple_protocol_action_new
 		* purple_protocol_action_free
diff --git a/libpurple/protocol.h b/libpurple/protocol.h
index 7455001d65..94c5d14aec 100644
--- a/libpurple/protocol.h
+++ b/libpurple/protocol.h
@@ -814,18 +814,65 @@ const char *purple_protocol_class_list_icon(PurpleProtocol *protocol,
  * purple_protocol_client_iface_get_type:
  *
  * Returns: The #GType for the protocol client interface.
+ *
+ * Since: 3.0.0
  */
 GType purple_protocol_client_iface_get_type(void);
 
+/**
+ * purple_protocol_client_iface_get_actions:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ *
+ * Gets a list of actions for @connection.
+ *
+ * Returns: (transfer full) (element-type PurpleProtocolAction): The list of actions for @connection.
+ *
+ * Since: 3.0.0
+ */
 GList *purple_protocol_client_iface_get_actions(PurpleProtocol *protocol,
 		PurpleConnection *connection);
 
+/**
+ * purple_protocol_client_iface_list_emblem:
+ * @protocol: The #PurpleProtocol instance.
+ * @buddy: The #PurpleBuddy instance.
+ *
+ * Gets the icon name of the emblem that should be used for @buddy.
+ *
+ * Returns: The icon name of the emblem or NULL.
+ *
+ * Since: 3.0.0
+ */
 const char *purple_protocol_client_iface_list_emblem(PurpleProtocol *protocol,
 		PurpleBuddy *buddy);
 
+/**
+ * purple_protocol_client_iface_status_text:
+ * @protocol: The #PurpleProtocol instance.
+ * @buddy: The #ProtocolBuddy instance.
+ *
+ * Gets the status text for @buddy.
+ *
+ * Returns: (transfer full): The status text for @buddy or NULL.
+ *
+ * Since: 3.0.0
+ */
 char *purple_protocol_client_iface_status_text(PurpleProtocol *protocol,
 		PurpleBuddy *buddy);
 
+/**
+ * purple_protocol_client_iface_tooltip_text:
+ * @protocol: The #PurpleProtocol instance.
+ * @buddy: The #PurpleBuddy instance.
+ * @user_info: The #PurpleNotifyUserInfo instance.
+ * @full: Whether or not additional info should be added.
+ *
+ * Asks @protocol to update @user_info for @buddy.  If @full is %TRUE then
+ * more detailed information will added.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_client_iface_tooltip_text(PurpleProtocol *protocol,
 		PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
 
@@ -974,36 +1021,159 @@ unsigned int purple_protocol_im_iface_send_typing(PurpleProtocol *protocol,
  * purple_protocol_chat_iface_get_type:
  *
  * Returns: The #GType for the protocol chat interface.
+ *
+ * Since: 3.0.0
  */
 GType purple_protocol_chat_iface_get_type(void);
 
+/**
+ * purple_protocol_chat_iface_info:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ *
+ * Gets the list of #PurpleProtocolChatEntry's that are required to join a
+ * multi user chat.
+ *
+ * Returns: (transfer full) (element-type PurpleProtocolChatEntry): The list
+ *          of #PurpleProtocolChatEntry's that are used to join a chat.
+ *
+ * Since: 3.0.0
+ */
 GList *purple_protocol_chat_iface_info(PurpleProtocol *protocol,
 		PurpleConnection *connection);
 
+/**
+ * purple_protocol_chat_iface_info_defaults:
+ * @protocol: The #PurpleProtocol instance
+ * @connection: The #PurpleConnection instance
+ * @chat_name: The name of the chat
+ *
+ * Returns a #GHashTable of the default protocol dependent components that will
+ * be passed to #purple_protocol_chat_iface_join.
+ *
+ * Returns: (transfer full) (element-type utf8 utf8): The values that will be
+ *          used to join the chat.
+ *
+ * Since: 3.0.0
+ */
 GHashTable *purple_protocol_chat_iface_info_defaults(PurpleProtocol *protocol,
 		PurpleConnection *connection, const char *chat_name);
 
+/**
+ * purple_protocol_chat_iface_join:
+ * @protocol: The #PurpleProtocol instance
+ * @connection: The #PurpleConnection instance
+ * @components: (element-type utf8 utf8): The protocol dependent join
+ *              components
+ *
+ * Joins the chat described in @components.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_chat_iface_join(PurpleProtocol *protocol, PurpleConnection *connection,
 		GHashTable *components);
 
+/**
+ * purple_protocol_chat_iface_reject:
+ * @protocol: The #PurpleProtocol instance
+ * @connection: The #PurpleConnection instance
+ * @components: (element-type utf8 utf8): The protocol dependent join
+ *              components
+ *
+ * Not quite sure exactly what this does or where it's used.  Please fill in
+ * the details if you know.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_chat_iface_reject(PurpleProtocol *protocol,
 		PurpleConnection *connection, GHashTable *components);
 
+/**
+ * purple_protocol_chat_iface_get_name:
+ * @protocol: The #PurpleProtocol instance
+ * @components: (element-type utf8 utf8): The protocol dependent join
+ *              components
+ *
+ * Gets the name from @components.
+ *
+ * Returns: (transfer full): The chat name from @components.
+ *
+ * Since: 3.0.0
+ */
 char *purple_protocol_chat_iface_get_name(PurpleProtocol *protocol,
 		GHashTable *components);
 
+/**
+ * purple_protocol_chat_iface_invite:
+ * @protocol: The #PurpleProtocol instance
+ * @connection: The #PurpleConnection instance
+ * @id: The id of the chat
+ * @message: The invite message
+ * @who: The target of the invite
+ *
+ * Sends an invite to @who with @message.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_chat_iface_invite(PurpleProtocol *protocol,
 		PurpleConnection *connection, int id, const char *message, const char *who);
 
+/**
+ * purple_protocol_chat_iface_leave:
+ * @protocol: The #PurpleProtocol instance
+ * @connection: The #PurpleConnection instance
+ * @id: The id of the chat
+ *
+ * Leaves the chat identified by @id.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_chat_iface_leave(PurpleProtocol *protocol, PurpleConnection *connection,
 		int id);
 
+/**
+ * purple_protocol_chat_iface_send:
+ * @protocol: The #PurpleProtocol instance
+ * @connection: The #PurpleConnection instance
+ * @id: The id of the chat
+ * @msg: The message to send
+ *
+ * Sends @msg to the chat identified by @id.
+ *
+ * Returns: 0 on success, non-zero on failure.
+ *
+ * Since: 3.0.0
+ */
 int  purple_protocol_chat_iface_send(PurpleProtocol *protocol, PurpleConnection *connection,
 		int id, PurpleMessage *msg);
 
+/**
+ * purple_protocol_chat_iface_get_user_real_name:
+ * @protocol: The #PurpleProtocol instance
+ * @gc: The #PurpleConnection instance
+ * @id: The id of the chat
+ * @who: The username
+ *
+ * Gets the real name of @who.
+ *
+ * Returns: (transfer full): The realname of @who.
+ *
+ * Since: 3.0.0
+ */
 char *purple_protocol_chat_iface_get_user_real_name(PurpleProtocol *protocol,
 		PurpleConnection *gc, int id, const char *who);
 
+/**
+ * purple_protocol_chat_iface_set_topic:
+ * @protocol: The #PurpleProtocol instance
+ * @gc: The #PurpleConnection instance
+ * @id: The id of the chat
+ * @topic: The new topic
+ *
+ * Sets the topic for the chat with id @id to @topic.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_chat_iface_set_topic(PurpleProtocol *protocol,
 		PurpleConnection *gc, int id, const char *topic);
 
@@ -1015,21 +1185,74 @@ void purple_protocol_chat_iface_set_topic(PurpleProtocol *protocol,
  * purple_protocol_privacy_iface_get_type:
  *
  * Returns: The #GType for the protocol privacy interface.
+ *
+ * Since: 3.0.0
  */
 GType purple_protocol_privacy_iface_get_type(void);
 
+/**
+ * purple_protocol_privacy_iface_add_permit:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ * @name: The username to permit.
+ *
+ * Adds a permit to the privacy settings for @connection to allow @name to
+ * contact the user.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_privacy_iface_add_permit(PurpleProtocol *protocol,
 		PurpleConnection *connection, const char *name);
 
+/**
+ * purple_protocol_privacy_iface_add_deny:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ * @name: The username to deny.
+ *
+ * Adds a deny to the privacy settings for @connection to deny @name from
+ * contacting the user.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_privacy_iface_add_deny(PurpleProtocol *protocol,
 		PurpleConnection *connection, const char *name);
 
+/**
+ * purple_protocol_privacy_iface_rem_permit:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ * @name: The username to remove from the permit privacy settings.
+ *
+ * Removes an existing permit for @name.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_privacy_iface_rem_permit(PurpleProtocol *protocol,
 		PurpleConnection *connection, const char *name);
 
+/**
+ * purple_protocol_privacy_iface_rem_deny:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ * @name: The username to remove from the deny privacy settings.
+ *
+ * Removes an existing deny for @name.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_privacy_iface_rem_deny(PurpleProtocol *protocol,
 		PurpleConnection *connection, const char *name);
 
+/**
+ * purple_protocol_privacy_iface_set_permit_deny:
+ * @protocol: The #PurpleProtocol instance.
+ * @connection: The #PurpleConnection instance.
+ *
+ * Forces a sync of the privacy settings with server.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_privacy_iface_set_permit_deny(PurpleProtocol *protocol,
 		PurpleConnection *connection);
 
@@ -1041,18 +1264,62 @@ void purple_protocol_privacy_iface_set_permit_deny(PurpleProtocol *protocol,
  * purple_protocol_roomlist_iface_get_type:
  *
  * Returns: The #GType for the protocol roomlist interface.
+ *
+ * Since: 3.0.0
  */
 GType purple_protocol_roomlist_iface_get_type(void);
 
+/**
+ * purple_protocol_roomlist_iface_get_list:
+ * @protocol: The #PurpleProtocol instance.
+ * @gc: The #PurpleAccount to get the roomlist for.
+ *
+ * Gets the list of rooms for @gc.
+ *
+ * Returns: (transfer full): The roomlist for @gc.
+ *
+ * Since: 3.0.0
+ */
 PurpleRoomlist *purple_protocol_roomlist_iface_get_list(PurpleProtocol *protocol,
 		PurpleConnection *gc);
 
+/**
+ * purple_protocol_roomlist_iface_cancel:
+ * @protocol: The #PurpleProtocol instance.
+ * @list: The #PurpleRoomlist instance.
+ *
+ * Requesting a roomlist can take a long time.  This function cancels a request
+ * that's already in progress.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_roomlist_iface_cancel(PurpleProtocol *protocol,
 		PurpleRoomlist *list);
 
+/**
+ * purple_protocol_roomlist_iface_expand_category:
+ * @protocol: The #PurpleProtocol instance.
+ * @list: The #PurpleRoomlist instance.
+ * @category: The category to expand.
+ *
+ * Expands the given @category for @list.
+ *
+ * Since: 3.0.0
+ */
 void purple_protocol_roomlist_iface_expand_category(PurpleProtocol *protocol,
 		PurpleRoomlist *list, PurpleRoomlistRoom *category);
 
+/**
+ * purple_protocol_roomlist_iface_room_serialize:
+ * @protocol: The #PurpleProtocol instance.
+ * @room: The #PurpleRoomlistRoom instance.
+ *
+ * Serializes @room into a string that will be displayed in a user interface.
+ *
+ * Returns: (transfer full): The serialized form of @room.
+ *
+ * Since: 3.0.0
+ */
 char *purple_protocol_roomlist_iface_room_serialize(PurpleProtocol *protocol,
 		PurpleRoomlistRoom *room);
 
@@ -1064,15 +1331,60 @@ char *purple_protocol_roomlist_iface_room_serialize(PurpleProtocol *protocol,
  * purple_protocol_media_iface_get_type:
  *
  * Returns: The #GType for the protocol media interface.
+ *
+ * Since: 3.0.0
  */
 GType purple_protocol_media_iface_get_type(void);
 
+/**
+ * purple_protocol_media_iface_initiate_session:
+ * @protocol: The #PurpleProtocol instance.
+ * @account: The #PurpleAccount instance.
+ * @who: The user to initiate a media session with.
+ * @type: The type of media session to create.
+ *
+ * Initiates a media connection of @type to @who.
+ *
+ * Returns: TRUE if successful, FALSE otherwise.
+ *
+ * Since: 3.0.0
+ */
 gboolean purple_protocol_media_iface_initiate_session(PurpleProtocol *protocol,
 		PurpleAccount *account, const char *who, PurpleMediaSessionType type);
 
+/**
+ * purple_protocol_media_iface_get_caps:
+ * @protocol: The #PurpleProtocol instance.
+ * @account: The #PurpleAccount instance.
+ * @who: The user to get the media capabilites for.
+ *
+ * Gets the #PurpleMediaCaps for @who which determine what types of media are
+ * available.
+ *
+ * Returns: the media capabilities of @who.
+ *
+ * Since: 3.0.0
+ */
 PurpleMediaCaps purple_protocol_media_iface_get_caps(PurpleProtocol *protocol,
 		PurpleAccount *account, const char *who);
 
+/**
+ * purple_protocol_media_iface_send_dtmf:
+ * @protocol: The #PurpleProtocol instance.
+ * @media: The #PurpleMedia instance.
+ * @dtmf: A DTMF to send.
+ * @volume: The volume to send @dtmf at.
+ * @duration: The duration to send @dtmf (in ms?)
+ *
+ * Sends a DTMF (dual-tone multi-frequency) signal via the established @media
+ * for the given @duration at the given @volume.
+ *
+ * It is up to the specific implementation if DTMF is send in or out of band.
+ *
+ * Returns: TRUE if successful, FALSE otherwise.
+ *
+ * Since: 3.0.0
+ */
 gboolean purple_protocol_media_iface_send_dtmf(PurpleProtocol *protocol,
 		PurpleMedia *media, gchar dtmf, guint8 volume, guint8 duration);
 
diff --git a/libpurple/whiteboard.c b/libpurple/whiteboard.c
index 64ac003d6a..2d71b05ed0 100644
--- a/libpurple/whiteboard.c
+++ b/libpurple/whiteboard.c
@@ -132,7 +132,7 @@ const char *purple_whiteboard_get_who(PurpleWhiteboard *wb)
 
 	g_return_val_if_fail(priv != NULL, NULL);
 
-	return priv->who;	
+	return priv->who;
 }
 
 void purple_whiteboard_set_state(PurpleWhiteboard *wb, int state)
diff --git a/libpurple/whiteboard.h b/libpurple/whiteboard.h
index bb3a6dc0db..e3fb2412e7 100644
--- a/libpurple/whiteboard.h
+++ b/libpurple/whiteboard.h
@@ -189,17 +189,17 @@ PurpleWhiteboard *purple_whiteboard_new(PurpleAccount *account, const char *who,
 
 /**
  * purple_whiteboard_get_account:
- * @wb:		The whiteboard.
+ * @wb: The whiteboard.
  *
  * Returns the whiteboard's account.
  *
- * Returns: The whiteboard's account.
+ * Returns: (transfer none): The whiteboard's account.
  */
 PurpleAccount *purple_whiteboard_get_account(PurpleWhiteboard *wb);
 
 /**
  * purple_whiteboard_get_who:
- * @wb:		The whiteboard
+ * @wb: The whiteboard
  *
  * Return who you're drawing with.
  *
@@ -209,8 +209,8 @@ const char *purple_whiteboard_get_who(PurpleWhiteboard *wb);
 
 /**
  * purple_whiteboard_set_state:
- * @wb:		The whiteboard.
- * @state:		The state
+ * @wb:    The whiteboard.
+ * @state: The state
  *
  * Set the state of the whiteboard.
  */
@@ -218,7 +218,7 @@ void purple_whiteboard_set_state(PurpleWhiteboard *wb, int state);
 
 /**
  * purple_whiteboard_get_state:
- * @wb:		The whiteboard.
+ * @wb: The whiteboard.
  *
  * Return the state of the whiteboard.
  *
@@ -241,13 +241,13 @@ void purple_whiteboard_start(PurpleWhiteboard *wb);
  *
  * Finds a whiteboard from an account and user.
  *
- * Returns: The whiteboard if found, otherwise %NULL.
+ * Returns: (transfer none): The whiteboard if found, otherwise %NULL.
  */
 PurpleWhiteboard *purple_whiteboard_get_session(const PurpleAccount *account, const char *who);
 
 /**
  * purple_whiteboard_draw_list_destroy:
- * @draw_list: The drawing list.
+ * @draw_list: (element-type gint): The drawing list.
  *
  * Destorys a drawing list for a whiteboard
  */
@@ -255,9 +255,9 @@ void purple_whiteboard_draw_list_destroy(GList *draw_list);
 
 /**
  * purple_whiteboard_get_dimensions:
- * @wb:		The whiteboard.
- * @width:		The width to be set.
- * @height:	The height to be set.
+ * @wb:     The whiteboard.
+ * @width:  The width to be set.
+ * @height: The height to be set.
  *
  * Gets the dimension of a whiteboard.
  *
@@ -289,8 +289,8 @@ void purple_whiteboard_draw_point(PurpleWhiteboard *wb, int x, int y, int color,
 
 /**
  * purple_whiteboard_send_draw_list:
- * @wb:	The whiteboard
- * @list:	A GList of points
+ * @wb:                        The whiteboard
+ * @list: (element-type gint): A GList of points
  *
  * Send a list of points to draw to the buddy.
  */
@@ -328,9 +328,9 @@ void purple_whiteboard_send_clear(PurpleWhiteboard *wb);
 
 /**
  * purple_whiteboard_send_brush:
- * @wb:	The whiteboard
- * @size:	The size of the brush
- * @color:	The color of the brush
+ * @wb:    The whiteboard
+ * @size:  The size of the brush
+ * @color: The color of the brush
  *
  * Sends a request to change the size and color of the brush.
  */
@@ -338,9 +338,9 @@ void purple_whiteboard_send_brush(PurpleWhiteboard *wb, int size, int color);
 
 /**
  * purple_whiteboard_get_brush:
- * @wb:	The whiteboard
- * @size:	The size of the brush
- * @color:	The color of the brush
+ * @wb:    The whiteboard
+ * @size:  The size of the brush
+ * @color: The color of the brush
  *
  * Gets the size and color of the brush.
  *
@@ -350,9 +350,9 @@ gboolean purple_whiteboard_get_brush(PurpleWhiteboard *wb, int *size, int *color
 
 /**
  * purple_whiteboard_set_brush:
- * @wb:	The whiteboard
- * @size:	The size of the brush
- * @color:	The color of the brush
+ * @wb:    The whiteboard
+ * @size:  The size of the brush
+ * @color: The color of the brush
  *
  * Sets the size and color of the brush.
  */
@@ -360,18 +360,18 @@ void purple_whiteboard_set_brush(PurpleWhiteboard *wb, int size, int color);
 
 /**
  * purple_whiteboard_get_draw_list:
- * @wb:			The whiteboard.
+ * @wb: The whiteboard.
  *
  * Return the drawing list.
  *
- * Returns: The drawing list
+ * Returns: (transfer none) (element-type gint): The drawing list
  */
 GList *purple_whiteboard_get_draw_list(PurpleWhiteboard *wb);
 
 /**
  * purple_whiteboard_set_draw_list:
- * @wb:			The whiteboard
- * @draw_list:		The drawing list.
+ * @wb:                             The whiteboard
+ * @draw_list: (element-type gint): The drawing list.
  *
  * Set the drawing list.
  */
@@ -379,8 +379,8 @@ void purple_whiteboard_set_draw_list(PurpleWhiteboard *wb, GList* draw_list);
 
 /**
  * purple_whiteboard_set_protocol_data:
- * @wb:			The whiteboard.
- * @proto_data:	The protocol data to set for the whiteboard.
+ * @wb:         The whiteboard.
+ * @proto_data: The protocol data to set for the whiteboard.
  *
  * Sets the protocol data for a whiteboard.
  */
@@ -388,7 +388,7 @@ void purple_whiteboard_set_protocol_data(PurpleWhiteboard *wb, gpointer proto_da
 
 /**
  * purple_whiteboard_get_protocol_data:
- * @wb:			The whiteboard.
+ * @wb: The whiteboard.
  *
  * Gets the protocol data for a whiteboard.
  *
@@ -398,8 +398,8 @@ gpointer purple_whiteboard_get_protocol_data(PurpleWhiteboard *wb);
 
 /**
  * purple_whiteboard_set_ui_data:
- * @wb:			The whiteboard.
- * @ui_data:		A pointer to associate with this whiteboard.
+ * @wb:      The whiteboard.
+ * @ui_data: A pointer to associate with this whiteboard.
  *
  * Set the UI data associated with this whiteboard.
  */
@@ -407,7 +407,7 @@ void purple_whiteboard_set_ui_data(PurpleWhiteboard *wb, gpointer ui_data);
 
 /**
  * purple_whiteboard_get_ui_data:
- * @wb:			The whiteboard..
+ * @wb: The whiteboard..
  *
  * Get the UI data associated with this whiteboard.
  *