--- a/libpurple/roomlist.h Wed Jan 29 00:28:08 2014 +0530
+++ b/libpurple/roomlist.h Wed Jan 29 05:28:33 2014 +0530
@@ -140,15 +140,15 @@
* While we're pretending, predend I didn't say anything about dialogs
* or buttons, since this is the core.
*
- * @param account The account to get the list on.
+ * @account: The account to get the list on.
*/
void purple_roomlist_show_with_account(PurpleAccount *account);
/**
* Returns a newly created room list object.
*
- * @param account The account that's listing rooms.
- * @return The new room list handle.
+ * @account: The account that's listing rooms.
+ * Returns: The new room list handle.
*/
PurpleRoomlist *purple_roomlist_new(PurpleAccount *account);
@@ -156,7 +156,7 @@
* Retrieve the PurpleAccount that was given when the room list was
* created.
*
- * @return The PurpleAccount tied to this room list.
+ * Returns: The PurpleAccount tied to this room list.
*/
PurpleAccount *purple_roomlist_get_account(PurpleRoomlist *list);
@@ -165,8 +165,8 @@
*
* This must be called before purple_roomlist_room_add().
*
- * @param list The room list.
- * @param fields A GList of PurpleRoomlistField's. UI's are encouraged
+ * @list: The room list.
+ * @fields: A GList of PurpleRoomlistField's. UI's are encouraged
* to default to displaying them in the order given.
*/
void purple_roomlist_set_fields(PurpleRoomlist *list, GList *fields);
@@ -177,8 +177,8 @@
* The UI is encouraged to somehow hint to the user
* whether or not we're busy downloading a room list or not.
*
- * @param list The room list.
- * @param in_progress We're downloading it, or we're not.
+ * @list: The room list.
+ * @in_progress: We're downloading it, or we're not.
*/
void purple_roomlist_set_in_progress(PurpleRoomlist *list, gboolean in_progress);
@@ -188,16 +188,16 @@
* The UI is encouraged to somehow hint to the user
* whether or not we're busy downloading a room list or not.
*
- * @param list The room list.
- * @return True if we're downloading it, or false if we're not.
+ * @list: The room list.
+ * Returns: True if we're downloading it, or false if we're not.
*/
gboolean purple_roomlist_get_in_progress(PurpleRoomlist *list);
/**
* Adds a room to the list of them.
*
- * @param list The room list.
- * @param room The room to add to the list. The GList of fields must be in the same
+ * @list: The room list.
+ * @room: The room to add to the list. The GList of fields must be in the same
order as was given in purple_roomlist_set_fields().
*/
void purple_roomlist_room_add(PurpleRoomlist *list, PurpleRoomlistRoom *room);
@@ -206,9 +206,9 @@
* Returns a PurpleRoomlist structure from the protocol, and
* instructs the protocol to start fetching the list.
*
- * @param gc The PurpleConnection to have get a list.
+ * @gc: The PurpleConnection to have get a list.
*
- * @return A PurpleRoomlist* or @c NULL if the protocol
+ * Returns: A PurpleRoomlist* or @c NULL if the protocol
* doesn't support that.
*/
PurpleRoomlist *purple_roomlist_get_list(PurpleConnection *gc);
@@ -219,7 +219,7 @@
* call set_in_progress with @c FALSE and possibly
* unref the list if it took a reference.
*
- * @param list The room list to cancel a get_list on.
+ * @list: The room list to cancel a get_list on.
*/
void purple_roomlist_cancel_get_list(PurpleRoomlist *list);
@@ -229,8 +229,8 @@
* On some protocols, the rooms in the category
* won't be fetched until this is called.
*
- * @param list The room list.
- * @param category The category that was expanded. The expression
+ * @list: The room list.
+ * @category: The category that was expanded. The expression
* (category->type & PURPLE_ROOMLIST_ROOMTYPE_CATEGORY)
* must be true.
*/
@@ -239,17 +239,17 @@
/**
* Get the list of fields for a roomlist.
*
- * @param roomlist The roomlist, which must not be @c NULL.
- * @constreturn A list of fields
+ * @roomlist: The roomlist, which must not be @c NULL.
+ * Returns: (TODO const): A list of fields
*/
GList *purple_roomlist_get_fields(PurpleRoomlist *roomlist);
/**
* Get the protocol data associated with this room list.
*
- * @param list The roomlist, which must not be @c NULL.
+ * @list: The roomlist, which must not be @c NULL.
*
- * @return The protocol data associated with this room list. This is a
+ * Returns: The protocol data associated with this room list. This is a
* convenience field provided to the protocol -- it is not
* used the libpurple core.
*/
@@ -258,17 +258,17 @@
/**
* Set the protocol data associated with this room list.
*
- * @param list The roomlist, which must not be @c NULL.
- * @param proto_data A pointer to associate with this room list.
+ * @list: The roomlist, which must not be @c NULL.
+ * @proto_data: A pointer to associate with this room list.
*/
void purple_roomlist_set_protocol_data(PurpleRoomlist *list, gpointer proto_data);
/**
* Get the UI data associated with this room list.
*
- * @param list The roomlist, which must not be @c NULL.
+ * @list: The roomlist, which must not be @c NULL.
*
- * @return The UI data associated with this room list. This is a
+ * Returns: The UI data associated with this room list. This is a
* convenience field provided to the UIs--it is not
* used by the libpurple core.
*/
@@ -277,8 +277,8 @@
/**
* Set the UI data associated with this room list.
*
- * @param list The roomlist, which must not be @c NULL.
- * @param ui_data A pointer to associate with this room list.
+ * @list: The roomlist, which must not be @c NULL.
+ * @ui_data: A pointer to associate with this room list.
*/
void purple_roomlist_set_ui_data(PurpleRoomlist *list, gpointer ui_data);
@@ -297,11 +297,11 @@
/**
* Creates a new room, to be added to the list.
*
- * @param type The type of room.
- * @param name The name of the room.
- * @param parent The room's parent, if any.
+ * @type: The type of room.
+ * @name: The name of the room.
+ * @parent: The room's parent, if any.
*
- * @return A new room.
+ * Returns: A new room.
*/
PurpleRoomlistRoom *purple_roomlist_room_new(PurpleRoomlistRoomType type, const gchar *name,
PurpleRoomlistRoom *parent);
@@ -309,63 +309,63 @@
/**
* Adds a field to a room.
*
- * @param list The room list the room belongs to.
- * @param room The room.
- * @param field The field to append. Strings get g_strdup'd internally.
+ * @list: The room list the room belongs to.
+ * @room: The room.
+ * @field: The field to append. Strings get g_strdup'd internally.
*/
void purple_roomlist_room_add_field(PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field);
/**
* Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist.
*
- * @param list The room list the room belongs to.
- * @param room The room to join.
+ * @list: The room list the room belongs to.
+ * @room: The room to join.
*/
void purple_roomlist_room_join(PurpleRoomlist *list, PurpleRoomlistRoom *room);
/**
* Get the type of a room.
- * @param room The room, which must not be @c NULL.
- * @return The type of the room.
+ * @room: The room, which must not be @c NULL.
+ * Returns: The type of the room.
*/
PurpleRoomlistRoomType purple_roomlist_room_get_room_type(PurpleRoomlistRoom *room);
/**
* Get the name of a room.
- * @param room The room, which must not be @c NULL.
- * @return The name of the room.
+ * @room: The room, which must not be @c NULL.
+ * Returns: The name of the room.
*/
const char * purple_roomlist_room_get_name(PurpleRoomlistRoom *room);
/**
* Get the parent of a room.
- * @param room The room, which must not be @c NULL.
- * @return The parent of the room, which can be @c NULL.
+ * @room: The room, which must not be @c NULL.
+ * Returns: The parent of the room, which can be @c NULL.
*/
PurpleRoomlistRoom * purple_roomlist_room_get_parent(PurpleRoomlistRoom *room);
/**
* Get the value of the expanded_once flag.
*
- * @param room The room, which must not be @c NULL.
+ * @room: The room, which must not be @c NULL.
*
- * @return The value of the expanded_once flag.
+ * Returns: The value of the expanded_once flag.
*/
gboolean purple_roomlist_room_get_expanded_once(PurpleRoomlistRoom *room);
/**
* Set the expanded_once flag.
*
- * @param room The room, which must not be @c NULL.
- * @param expanded_once The new value of the expanded_once flag.
+ * @room: The room, which must not be @c NULL.
+ * @expanded_once: The new value of the expanded_once flag.
*/
void purple_roomlist_room_set_expanded_once(PurpleRoomlistRoom *room, gboolean expanded_once);
/**
* Get the list of fields for a room.
*
- * @param room The room, which must not be @c NULL.
- * @constreturn A list of fields
+ * @room: The room, which must not be @c NULL.
+ * Returns: (TODO const): A list of fields
*/
GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room);
@@ -384,12 +384,12 @@
/**
* Creates a new field.
*
- * @param type The type of the field.
- * @param label The i18n'ed, user displayable name.
- * @param name The internal name of the field.
- * @param hidden Hide the field.
+ * @type: The type of the field.
+ * @label: The i18n'ed, user displayable name.
+ * @name: The internal name of the field.
+ * @hidden: Hide the field.
*
- * @return A new PurpleRoomlistField, ready to be added to a GList and passed to
+ * Returns: A new PurpleRoomlistField, ready to be added to a GList and passed to
* purple_roomlist_set_fields().
*/
PurpleRoomlistField *purple_roomlist_field_new(PurpleRoomlistFieldType type,
@@ -399,26 +399,26 @@
/**
* Get the type of a field.
*
- * @param field A PurpleRoomlistField, which must not be @c NULL.
+ * @field: A PurpleRoomlistField, which must not be @c NULL.
*
- * @return The type of the field.
+ * Returns: The type of the field.
*/
PurpleRoomlistFieldType purple_roomlist_field_get_field_type(PurpleRoomlistField *field);
/**
* Get the label of a field.
*
- * @param field A PurpleRoomlistField, which must not be @c NULL.
+ * @field: A PurpleRoomlistField, which must not be @c NULL.
*
- * @return The label of the field.
+ * Returns: The label of the field.
*/
const char * purple_roomlist_field_get_label(PurpleRoomlistField *field);
/**
* Check whether a roomlist-field is hidden.
- * @param field A PurpleRoomlistField, which must not be @c NULL.
+ * @field: A PurpleRoomlistField, which must not be @c NULL.
*
- * @return @c TRUE if the field is hidden, @c FALSE otherwise.
+ * Returns: @c TRUE if the field is hidden, @c FALSE otherwise.
*/
gboolean purple_roomlist_field_get_hidden(PurpleRoomlistField *field);
@@ -432,7 +432,7 @@
/**
* Sets the UI operations structure to be used in all purple room lists.
*
- * @param ops The UI operations structure.
+ * @ops: The UI operations structure.
*/
void purple_roomlist_set_ui_ops(PurpleRoomlistUiOps *ops);
@@ -440,7 +440,7 @@
* Returns the purple window UI operations structure to be used in
* new windows.
*
- * @return A filled-out PurpleRoomlistUiOps structure.
+ * Returns: A filled-out PurpleRoomlistUiOps structure.
*/
PurpleRoomlistUiOps *purple_roomlist_get_ui_ops(void);
