changeset
Convert doxygen's @return and @param commands for gtk-doc
Wed, 29 Jan 2014 05:28:33 +0530
- author
- Ankit Vani <a@nevitus.org>
- date
- Wed, 29 Jan 2014 05:28:33 +0530
- branch
- soc.2013.gobjectification.plugins
- changeset 37017
- 8e2b68c79fa1
- parent 37016
- 48f85579cc4c
- child 37018
- 9b6661893d92
Convert doxygen's @return and @param commands for gtk-doc
--- a/finch/gntaccount.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntaccount.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,7 +36,7 @@ /** * Get the ui-functions. * - * @return The PurpleAccountUiOps structure populated with the appropriate functions. + * Returns: The PurpleAccountUiOps structure populated with the appropriate functions. */ PurpleAccountUiOps *finch_accounts_get_ui_ops(void); @@ -58,7 +58,7 @@ /** * Show the edit dialog for an account. * - * @param account The account to edit, or @c NULL to create a new account. + * @account: The account to edit, or @c NULL to create a new account. */ void finch_account_dialog_show(PurpleAccount *account);
--- a/finch/gntblist.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntblist.h Wed Jan 29 05:28:33 2014 +0530 @@ -55,7 +55,7 @@ /** * Get the ui-functions. * - * @return The PurpleBlistUiOps structure populated with the appropriate functions. + * Returns: The PurpleBlistUiOps structure populated with the appropriate functions. */ PurpleBlistUiOps * finch_blist_get_ui_ops(void); @@ -80,7 +80,7 @@ * @param x The x-coordinate is set here if not @ NULL. * @param y The y-coordinate is set here if not @c NULL. * - * @return Returns @c TRUE if the values were set, @c FALSE otherwise. + * Returns: Returns @c TRUE if the values were set, @c FALSE otherwise. */ gboolean finch_blist_get_position(int *x, int *y); @@ -95,64 +95,64 @@ /** * Get the size of the buddy list. * - * @param width The width is set here if not @ NULL. - * @param height The height is set here if not @c NULL. + * @width: The width is set here if not @ NULL. + * @height: The height is set here if not @c NULL. * - * @return Returns @c TRUE if the values were set, @c FALSE otherwise. + * Returns: Returns @c TRUE if the values were set, @c FALSE otherwise. */ gboolean finch_blist_get_size(int *width, int *height); /** * Set the size of the buddy list. * - * @param width The width of the buddy list. - * @param height The height of the buddy list. + * @width: The width of the buddy list. + * @height: The height of the buddy list. */ void finch_blist_set_size(int width, int height); /** * Get information about a user. Show immediate feedback. * - * @param conn The connection to get information fro - * @param name The user to get information about. + * @conn: The connection to get information fro + * @name: The user to get information about. * - * @return Returns the ui-handle for the userinfo notification. + * Returns: Returns the ui-handle for the userinfo notification. */ gpointer finch_retrieve_user_info(PurpleConnection *conn, const char *name); /** * Get the tree list of the buddy list. - * @return The GntTree widget. + * Returns: The GntTree widget. */ GntTree * finch_blist_get_tree(void); /** * Add an alternate buddy list manager. * - * @param manager The alternate buddylist manager. + * @manager: The alternate buddylist manager. */ void finch_blist_install_manager(const FinchBlistManager *manager); /** * Remove an alternate buddy list manager. * - * @param manager The buddy list manager to remove. + * @manager: The buddy list manager to remove. */ void finch_blist_uninstall_manager(const FinchBlistManager *manager); /** * Find a buddy list manager. * - * @param id The identifier for the desired buddy list manager. + * @id: The identifier for the desired buddy list manager. * - * @return The manager with the requested identifier, if available. @c NULL otherwise. + * Returns: The manager with the requested identifier, if available. @c NULL otherwise. */ FinchBlistManager * finch_blist_manager_find(const char *id); /** * Request the active buddy list manager to add a node. * - * @param node The node to add + * @node: The node to add */ void finch_blist_manager_add_node(PurpleBlistNode *node);
--- a/finch/gntconn.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntconn.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,7 +36,7 @@ /** * Get the ui-functions. * - * @return The PurpleConnectionUiOps structure populated with the appropriate functions. + * Returns: The PurpleConnectionUiOps structure populated with the appropriate functions. */ PurpleConnectionUiOps *finch_connections_get_ui_ops(void);
--- a/finch/gntconv.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntconv.h Wed Jan 29 05:28:33 2014 +0530 @@ -85,7 +85,7 @@ /** * Get the ui-functions. * - * @return The PurpleConversationUiOps populated with the appropriate functions. + * Returns: The PurpleConversationUiOps populated with the appropriate functions. */ PurpleConversationUiOps *finch_conv_get_ui_ops(void); @@ -102,15 +102,15 @@ /** * Set a conversation as active in a contactized conversation * - * @param conv The conversation to make active. + * @conv: The conversation to make active. */ void finch_conversation_set_active(PurpleConversation *conv); /** * Sets the information widget for the conversation window. * - * @param conv The conversation. - * @param widget The widget containing the information. If @c NULL, + * @conv: The conversation. + * @widget: The widget containing the information. If @c NULL, * the current information widget is removed. */ void finch_conversation_set_info_widget(PurpleConversation *conv, GntWidget *widget);
--- a/finch/gntdebug.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntdebug.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,7 +36,7 @@ /** * Get the ui-functions. * - * @return The PurpleDebugUiOps structure populated with the appropriate functions. + * Returns: The PurpleDebugUiOps structure populated with the appropriate functions. */ PurpleDebugUiOps *finch_debug_get_ui_ops(void);
--- a/finch/gntidle.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntidle.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,7 +36,7 @@ /** * Returns the GNT idle UI ops. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleIdleUiOps *finch_idle_get_ui_ops(void);
--- a/finch/gntlog.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntlog.h Wed Jan 29 05:28:33 2014 +0530 @@ -68,7 +68,7 @@ /** * Returns the GNT log subsystem handle. * - * @return The GNT log subsystem handle. + * Returns: The GNT log subsystem handle. */ void *finch_log_get_handle(void);
--- a/finch/gntmenuutil.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntmenuutil.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,9 +37,9 @@ /** * Add a PurpleMenuAction to a GntMenu. * - * @param menu the GntMenu to add to - * @param action the PurpleMenuAction to add - * @param ctx the callback context, passed as the first argument to + * @menu: the GntMenu to add to + * @action: the PurpleMenuAction to add + * @ctx: the callback context, passed as the first argument to * the PurpleMenuAction's PurpleCallback function. */ void gnt_append_menu_action(GntMenu *menu, PurpleMenuAction *action, gpointer ctx);
--- a/finch/gntnotify.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntnotify.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,7 +36,7 @@ /** * Get the ui-functions. * - * @return The PurpleNotifyUiOps structure populated with the appropriate functions. + * Returns: The PurpleNotifyUiOps structure populated with the appropriate functions. */ PurpleNotifyUiOps *finch_notify_get_ui_ops(void);
--- a/finch/gntplugin.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntplugin.h Wed Jan 29 05:28:33 2014 +0530 @@ -91,11 +91,11 @@ * which should be a callback that returns a GntWidget for the plugin's * preferences (see FinchPluginPrefFrameCb). * - * @param first_property The first property name - * @param ... The value of the first property, followed optionally by more + * @first_property: The first property name + * @...: The value of the first property, followed optionally by more * name/value pairs, followed by @c NULL * - * @return A new #FinchPluginInfo instance. + * Returns: A new #FinchPluginInfo instance. * * @see purple_plugin_info_new() */
--- a/finch/gntpounce.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntpounce.h Wed Jan 29 05:28:33 2014 +0530 @@ -31,9 +31,9 @@ /** * Displays a New Buddy Pounce or Edit Buddy Pounce dialog. * - * @param account The optional account to use. - * @param name The optional name to pounce on. - * @param cur_pounce The current buddy pounce, if editing an existing one. + * @account: The optional account to use. + * @name: The optional name to pounce on. + * @cur_pounce: The current buddy pounce, if editing an existing one. */ void finch_pounce_editor_show(PurpleAccount *account, const char *name, PurplePounce *cur_pounce); @@ -51,7 +51,7 @@ /** * Returns the gtkpounces handle * - * @return The handle to the GTK+ pounces system + * Returns: The handle to the GTK+ pounces system */ void *finch_pounces_get_handle(void);
--- a/finch/gntrequest.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntrequest.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,7 +37,7 @@ /** * Get the ui-functions. * - * @return The PurpleRequestUiOps structure populated with the appropriate functions. + * Returns: The PurpleRequestUiOps structure populated with the appropriate functions. */ PurpleRequestUiOps *finch_request_get_ui_ops(void); @@ -60,9 +60,9 @@ /** * Create a widget field for a request-field. * - * @param field The request field. + * @field: The request field. * - * @return A GntWidget for the request field. + * Returns: A GntWidget for the request field. */ GntWidget *finch_request_field_get_widget(PurpleRequestField *field); /*@}*/
--- a/finch/gntroomlist.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntroomlist.h Wed Jan 29 05:28:33 2014 +0530 @@ -41,7 +41,7 @@ /** * Get the ui-functions. * - * @return The PurpleRoomlistUiOps structure populated with the appropriate functions. + * Returns: The PurpleRoomlistUiOps structure populated with the appropriate functions. */ PurpleRoomlistUiOps *finch_roomlist_get_ui_ops(void);
--- a/finch/gntsound.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntsound.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,21 +36,21 @@ /** * Get the name of the active sound profile. * - * @return The name of the profile + * Returns: The name of the profile */ const char *finch_sound_get_active_profile(void); /** * Set the active profile. If the profile doesn't exist, nothing is changed. * - * @param name The name of the profile + * @name: The name of the profile */ void finch_sound_set_active_profile(const char *name); /** * Get a list of available sound profiles. * - * @return A list of strings denoting sound profile names. + * Returns: A list of strings denoting sound profile names. * Caller must free the list (but not the data). */ GList *finch_sound_get_profiles(void); @@ -58,7 +58,7 @@ /** * Determine whether any sound will be played or not. * - * @return Returns FALSE if preference is set to 'No sound', or if volume is + * Returns: Returns FALSE if preference is set to 'No sound', or if volume is * set to zero. */ gboolean finch_sound_is_enabled(void); @@ -66,7 +66,7 @@ /** * Gets GNT sound UI ops. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleSoundUiOps *finch_sound_get_ui_ops(void);
--- a/finch/gntstatus.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntstatus.h Wed Jan 29 05:28:33 2014 +0530 @@ -42,7 +42,7 @@ /** * Show a dialog to edit a status. * - * @param saved The saved status to edit. Set it to @c NULL to create a new status. + * @saved: The saved status to edit. Set it to @c NULL to create a new status. */ void finch_savedstatus_edit(PurpleSavedStatus *saved);
--- a/finch/gntxfer.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/gntxfer.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,7 +37,7 @@ /** * Creates a new file transfer dialog. * - * @return The new dialog. + * Returns: The new dialog. */ void finch_xfer_dialog_new(void); @@ -60,28 +60,28 @@ /** * Adds a file transfer to the dialog. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void finch_xfer_dialog_add_xfer(PurpleXfer *xfer); /** * Removes a file transfer from the dialog. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void finch_xfer_dialog_remove_xfer(PurpleXfer *xfer); /** * Indicate in a file transfer dialog that a transfer was cancelled. * - * @param xfer The file transfer that was cancelled. + * @xfer: The file transfer that was cancelled. */ void finch_xfer_dialog_cancel_xfer(PurpleXfer *xfer); /** * Updates the information for a transfer in the dialog. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void finch_xfer_dialog_update_xfer(PurpleXfer *xfer); @@ -105,7 +105,7 @@ /** * Returns the UI operations structure for the GNT file transfer UI. * - * @return The GNT file transfer UI operations structure. + * Returns: The GNT file transfer UI operations structure. */ PurpleXferUiOps *finch_xfers_get_ui_ops(void);
--- a/finch/libgnt/gnt-skel.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gnt-skel.h Wed Jan 29 05:28:33 2014 +0530 @@ -63,14 +63,14 @@ /** * * - * @return + * Returns: */ GType gnt_skel_get_gtype(void); /** * * - * @return + * Returns: */ GntWidget * gnt_skel_new();
--- a/finch/libgnt/gnt.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gnt.h Wed Jan 29 05:28:33 2014 +0530 @@ -52,7 +52,7 @@ /** * Check whether the terminal is capable of UTF8 display. * - * @return @c FALSE if the terminal is capable of drawing UTF-8, @c TRUE otherwise. + * Returns: @c FALSE if the terminal is capable of drawing UTF-8, @c TRUE otherwise. */ gboolean gnt_ascii_only(void); @@ -60,7 +60,7 @@ * Present a window. If the event was triggered because of user interaction, * the window is moved to the foreground. Otherwise, the Urgent hint is set. * - * @param window The window the present. + * @window: The window the present. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -87,16 +87,16 @@ /** * Resize a widget. * - * @param widget The widget to resize. - * @param width The desired width. - * @param height The desired height. + * @widget: The widget to resize. + * @width: The desired width. + * @height: The desired height. */ void gnt_screen_resize_widget(GntWidget *widget, int width, int height); /** * Move a widget. * - * @param widget The widget to move. + * @widget: The widget to move. * @param x The desired x-coordinate. * @param y The desired y-coordinate. */ @@ -105,41 +105,41 @@ /** * Rename a widget. * - * @param widget The widget to rename. - * @param text The new name for the widget. + * @widget: The widget to rename. + * @text: The new name for the widget. */ void gnt_screen_rename_widget(GntWidget *widget, const char *text); /** * Check whether a widget has focus. * - * @param widget The widget. + * @widget: The widget. * - * @return @c TRUE if the widget has the current focus, @c FALSE otherwise. + * Returns: @c TRUE if the widget has the current focus, @c FALSE otherwise. */ gboolean gnt_widget_has_focus(GntWidget *widget); /** * Set the URGENT hint for a widget. * - * @param widget The widget to set the URGENT hint for. + * @widget: The widget to set the URGENT hint for. */ void gnt_widget_set_urgent(GntWidget *widget); /** * Register a global action. * - * @param label The user-visible label for the action. - * @param callback The callback function for the action. + * @label: The user-visible label for the action. + * @callback: The callback function for the action. */ void gnt_register_action(const char *label, void (*callback)(void)); /** * Show a menu. * - * @param menu The menu to display. + * @menu: The menu to display. * - * @return @c TRUE if the menu is displayed, @c FALSE otherwise (e.g., if another menu is currently displayed). + * Returns: @c TRUE if the menu is displayed, @c FALSE otherwise (e.g., if another menu is currently displayed). */ gboolean gnt_screen_menu_show(gpointer menu); @@ -151,37 +151,37 @@ /** * Get the global clipboard. * - * @return The clipboard. + * Returns: The clipboard. */ GntClipboard * gnt_get_clipboard(void); /** * Get the string in the clipboard. * - * @return A copy of the string in the clipboard. The caller must @c g_free the string. + * Returns: A copy of the string in the clipboard. The caller must @c g_free the string. */ gchar * gnt_get_clipboard_string(void); /** * Set the contents of the global clipboard. * - * @param string The new content of the new clipboard. + * @string: The new content of the new clipboard. */ void gnt_set_clipboard_string(const gchar *string); /** * Spawn a different application that will consume the console. * - * @param wd The working directory for the new application. - * @param argv The argument vector. - * @param envp The environment, or @c NULL. - * @param stin Location to store the child's stdin, or @c NULL. - * @param stout Location to store the child's stdout, or @c NULL. - * @param sterr Location to store the child's stderr, or @c NULL. - * @param callback The callback to call after the child exits. - * @param data The data to pass to the callback. + * @wd: The working directory for the new application. + * @argv: The argument vector. + * @envp: The environment, or @c NULL. + * @stin: Location to store the child's stdin, or @c NULL. + * @stout: Location to store the child's stdout, or @c NULL. + * @sterr: Location to store the child's stderr, or @c NULL. + * @callback: The callback to call after the child exits. + * @data: The data to pass to the callback. * - * @return @c TRUE if the child was successfully spawned, @c FALSE otherwise. + * Returns: @c TRUE if the child was successfully spawned, @c FALSE otherwise. */ gboolean gnt_giveup_console(const char *wd, char **argv, char **envp, gint *stin, gint *stout, gint *sterr, @@ -190,7 +190,7 @@ /** * Check whether a child process is in control of the current terminal. * - * @return @c TRUE if a child process (eg., PAGER) is occupying the current + * Returns: @c TRUE if a child process (eg., PAGER) is occupying the current * terminal, @c FALSE otherwise. */ gboolean gnt_is_refugee(void);
--- a/finch/libgnt/gntbindable.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntbindable.h Wed Jan 29 05:28:33 2014 +0530 @@ -69,7 +69,7 @@ /** * * - * @return + * Returns: */ GType gnt_bindable_get_gtype(void); @@ -107,24 +107,24 @@ /** * Free a bindable action. * - * @param action The bindable action. + * @action: The bindable action. */ void gnt_bindable_action_free(GntBindableAction *action); /** * Free a GntBindableActionParam. * - * @param param The GntBindableActionParam to free. + * @param: The GntBindableActionParam to free. */ void gnt_bindable_action_param_free(GntBindableActionParam *param); /** * Register a bindable action for a class. * - * @param klass The class the binding is for. - * @param name The name of the binding. - * @param callback The callback for the binding. - * @param trigger The default trigger for the binding, or @c NULL, followed by a NULL-terminated + * @klass: The class the binding is for. + * @name: The name of the binding. + * @callback: The callback for the binding. + * @trigger: The default trigger for the binding, or @c NULL, followed by a NULL-terminated * list of default parameters. */ void gnt_bindable_class_register_action(GntBindableClass *klass, const char *name, GntBindableActionCallback callback, const char *trigger, ...); @@ -132,48 +132,48 @@ /** * Register a key-binding to an existing action. * - * @param klass The class the binding is for. - * @param name The name of the binding. - * @param trigger A new trigger for the binding, followed by a @c NULL-terminated list of parameters for the callback. + * @klass: The class the binding is for. + * @name: The name of the binding. + * @trigger: A new trigger for the binding, followed by a @c NULL-terminated list of parameters for the callback. */ void gnt_bindable_register_binding(GntBindableClass *klass, const char *name, const char *trigger, ...); /** * Perform an action from a keybinding. * - * @param bindable The bindable object. - * @param keys The key to trigger the action. + * @bindable: The bindable object. + * @keys: The key to trigger the action. * - * @return @c TRUE if the action was performed successfully, @c FALSE otherwise. + * Returns: @c TRUE if the action was performed successfully, @c FALSE otherwise. */ gboolean gnt_bindable_perform_action_key(GntBindable *bindable, const char *keys); /** * Discover if a key is bound. * - * @param bindable The bindable object. - * @param keys The key to check for. + * @bindable: The bindable object. + * @keys: The key to check for. * - * @return @c TRUE if the the key has an action associated with it. + * Returns: @c TRUE if the the key has an action associated with it. */ gboolean gnt_bindable_check_key(GntBindable *bindable, const char *keys); /** * Perform an action on a bindable object. * - * @param bindable The bindable object. - * @param name The action to perform, followed by a @c NULL-terminated list of parameters. + * @bindable: The bindable object. + * @name: The action to perform, followed by a @c NULL-terminated list of parameters. * - * @return @c TRUE if the action was performed successfully, @c FALSE otherwise. + * Returns: @c TRUE if the action was performed successfully, @c FALSE otherwise. */ gboolean gnt_bindable_perform_action_named(GntBindable *bindable, const char *name, ...) G_GNUC_NULL_TERMINATED; /** * Returns a GntTree populated with "key" -> "binding" for the widget. * - * @param bind The object to list the bindings for. + * @bind: The object to list the bindings for. * - * @return The GntTree. + * Returns: The GntTree. */ GntBindable * gnt_bindable_bindings_view(GntBindable *bind); @@ -181,9 +181,9 @@ * Builds a window that list the key bindings for a GntBindable object. * From this window a user can select a listing to rebind a new key for the given action. * - * @param bindable The object to list the bindings for. + * @bindable: The object to list the bindings for. * - * @return @c TRUE + * Returns: @c TRUE */ gboolean gnt_bindable_build_help_window(GntBindable *bindable);
--- a/finch/libgnt/gntbox.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntbox.h Wed Jan 29 05:28:33 2014 +0530 @@ -89,7 +89,7 @@ /** * The GType for GntBox. - * @return The GType. + * Returns: The GType. */ GType gnt_box_get_gtype(void); @@ -99,35 +99,35 @@ /** * Create a new GntBox. * - * @param homo If @c TRUE, all the widgets in it will have the same width (or height) - * @param vert Whether the widgets in it should be stacked vertically (if @c TRUE) + * @homo: If @c TRUE, all the widgets in it will have the same width (or height) + * @vert: Whether the widgets in it should be stacked vertically (if @c TRUE) * or horizontally (if @c FALSE). * - * @return The new GntBox. + * Returns: The new GntBox. */ GntWidget * gnt_box_new(gboolean homo, gboolean vert); /** * Add a widget in the box. * - * @param box The box - * @param widget The widget to add + * @box: The box + * @widget: The widget to add */ void gnt_box_add_widget(GntBox *box, GntWidget *widget); /** * Set a title for the box. * - * @param box The box - * @param title The title to set + * @box: The box + * @title: The title to set */ void gnt_box_set_title(GntBox *box, const char *title); /** * Set the padding to use between the widgets in the box. * - * @param box The box - * @param pad The padding to use + * @box: The box + * @pad: The padding to use */ void gnt_box_set_pad(GntBox *box, int pad); @@ -136,38 +136,38 @@ * then it will show borders, the title (if set) and shadow (if enabled in * @e .gntrc) * - * @param box The box - * @param set @c TRUE if it's a toplevel box, @c FALSE otherwise. + * @box: The box + * @set: @c TRUE if it's a toplevel box, @c FALSE otherwise. */ void gnt_box_set_toplevel(GntBox *box, gboolean set); /** * Reposition and refresh the widgets in the box. * - * @param box The box + * @box: The box */ void gnt_box_sync_children(GntBox *box); /** * Set the alignment for the widgets in the box. * - * @param box The box - * @param alignment The alignment to use + * @box: The box + * @alignment: The alignment to use */ void gnt_box_set_alignment(GntBox *box, GntAlignment alignment); /** * Remove a widget from the box. Calling this does NOT destroy the removed widget. * - * @param box The box - * @param widget The widget to remove + * @box: The box + * @widget: The widget to remove */ void gnt_box_remove(GntBox *box, GntWidget *widget); /** * Remove all widgets from the box. This DOES destroy all widgets in the box. * - * @param box The box + * @box: The box */ void gnt_box_remove_all(GntBox *box); @@ -175,23 +175,23 @@ * Readjust the size of each child widget, reposition the child widgets and * recalculate the size of the box. * - * @param box The box + * @box: The box */ void gnt_box_readjust(GntBox *box); /** * Set whether the widgets in the box should fill the empty spaces. * - * @param box The box - * @param fill Whether the child widgets should fill the empty space + * @box: The box + * @fill: Whether the child widgets should fill the empty space */ void gnt_box_set_fill(GntBox *box, gboolean fill); /** * Move the focus from one widget to the other. * - * @param box The box - * @param dir The direction. If it's 1, then the focus is moved forwards, if it's + * @box: The box + * @dir: The direction. If it's 1, then the focus is moved forwards, if it's * -1, the focus is moved backwards. */ void gnt_box_move_focus(GntBox *box, int dir); @@ -199,8 +199,8 @@ /** * Give focus to a specific child widget. * - * @param box The box - * @param widget The child widget to give focus + * @box: The box + * @widget: The child widget to give focus */ void gnt_box_give_focus_to_child(GntBox *box, GntWidget *widget);
--- a/finch/libgnt/gntbutton.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntbutton.h Wed Jan 29 05:28:33 2014 +0530 @@ -73,16 +73,16 @@ G_BEGIN_DECLS /** - * @return GType for Gntbutton + * Returns: GType for Gntbutton */ GType gnt_button_get_gtype(void); /** * Create a new button. * - * @param text The text for the button. + * @text: The text for the button. * - * @return The newly created button. + * Returns: The newly created button. */ GntWidget * gnt_button_new(const char *text);
--- a/finch/libgnt/gntcheckbox.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntcheckbox.h Wed Jan 29 05:28:33 2014 +0530 @@ -68,33 +68,33 @@ G_BEGIN_DECLS /** - * @return GType for GntCheckBox + * Returns: GType for GntCheckBox */ GType gnt_check_box_get_gtype(void); /** * Create a new checkbox. * - * @param text The text for the checkbox. + * @text: The text for the checkbox. * - * @return The newly created checkbox. + * Returns: The newly created checkbox. */ GntWidget * gnt_check_box_new(const char *text); /** * Set whether the checkbox should be checked or not. * - * @param box The checkbox. - * @param set @c TRUE if the checkbox should be selected, @c FALSE otherwise. + * @box: The checkbox. + * @set: @c TRUE if the checkbox should be selected, @c FALSE otherwise. */ void gnt_check_box_set_checked(GntCheckBox *box, gboolean set); /** * Return the checked state of the checkbox. * - * @param box The checkbox. + * @box: The checkbox. * - * @return @c TRUE if the checkbox is selected, @c FALSE otherwise. + * Returns: @c TRUE if the checkbox is selected, @c FALSE otherwise. */ gboolean gnt_check_box_get_checked(GntCheckBox *box);
--- a/finch/libgnt/gntclipboard.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntclipboard.h Wed Jan 29 05:28:33 2014 +0530 @@ -60,16 +60,16 @@ G_BEGIN_DECLS /** - * @return GType for GntClipboard. + * Returns: GType for GntClipboard. */ GType gnt_clipboard_get_gtype(void); /** * Get the current text from the clipboard. * - * @param clip The clipboard. + * @clip: The clipboard. * - * @return A copy of the string in the clipboard. The caller should free the + * Returns: A copy of the string in the clipboard. The caller should free the * returned value. */ gchar * gnt_clipboard_get_string(GntClipboard *clip); @@ -77,8 +77,8 @@ /** * Set the text in the clipboard. * - * @param clip The clipboard. - * @param string New string for the clipboard. + * @clip: The clipboard. + * @string: New string for the clipboard. */ void gnt_clipboard_set_string(GntClipboard *clip, const gchar *string);
--- a/finch/libgnt/gntcolors.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntcolors.h Wed Jan 29 05:28:33 2014 +0530 @@ -74,23 +74,23 @@ /** * Parse color information from a file. * - * @param kfile The file containing color information. + * @kfile: The file containing color information. */ void gnt_colors_parse(GKeyFile *kfile); /** * Parse color-pair information from a file. * - * @param kfile The file containing the color-pair information. + * @kfile: The file containing the color-pair information. */ void gnt_color_pairs_parse(GKeyFile *kfile); /** * Parse a string color * - * @param kfile The string value + * @kfile: The string value * - * @return A color. For an unknown color name, returns -EINVAL. + * Returns: A color. For an unknown color name, returns -EINVAL. * * @since 2.4.0 */ @@ -101,9 +101,9 @@ * If the terminal doesn't have color support, this returns A_STANDOUT * when deemed appropriate. * - * @param color The color code. + * @color: The color code. * - * @return A character attribute. + * Returns: A character attribute. * * @since 2.3.0 */ @@ -112,10 +112,10 @@ /** * Adds a color definition * - * @param fg Foreground - * @param bg Background + * @fg: Foreground + * @bg: Background * - * @return A color pair + * Returns: A color pair * * @since 2.4.0 */
--- a/finch/libgnt/gntcombobox.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntcombobox.h Wed Jan 29 05:28:33 2014 +0530 @@ -69,55 +69,55 @@ G_BEGIN_DECLS /** - * @return Get the GType for GntComboBox + * Returns: Get the GType for GntComboBox */ GType gnt_combo_box_get_gtype(void); /** * Create a new GntComboBox * - * @return A new GntComboBox + * Returns: A new GntComboBox */ GntWidget * gnt_combo_box_new(void); /** * Add an entry * - * @param box The GntComboBox - * @param key The data - * @param text The text to display + * @box: The GntComboBox + * @key: The data + * @text: The text to display */ void gnt_combo_box_add_data(GntComboBox *box, gpointer key, const char *text); /** * Remove an entry * - * @param box The GntComboBox - * @param key The data to be removed + * @box: The GntComboBox + * @key: The data to be removed */ void gnt_combo_box_remove(GntComboBox *box, gpointer key); /** * Remove all entries * - * @param box The GntComboBox + * @box: The GntComboBox */ void gnt_combo_box_remove_all(GntComboBox *box); /** * Get the data that is currently selected * - * @param box The GntComboBox + * @box: The GntComboBox * - * @return The data of the currently selected entry + * Returns: The data of the currently selected entry */ gpointer gnt_combo_box_get_selected_data(GntComboBox *box); /** * Set the current selection to a specific entry * - * @param box The GntComboBox - * @param key The data to be set to + * @box: The GntComboBox + * @key: The data to be set to */ void gnt_combo_box_set_selected(GntComboBox *box, gpointer key);
--- a/finch/libgnt/gntentry.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntentry.h Wed Jan 29 05:28:33 2014 +0530 @@ -104,64 +104,64 @@ G_BEGIN_DECLS /** - * @return GType for GntEntry. + * Returns: GType for GntEntry. */ GType gnt_entry_get_gtype(void); /** * Create a new GntEntry. * - * @param text The text in the new entry box. + * @text: The text in the new entry box. * - * @return The newly created entry box. + * Returns: The newly created entry box. */ GntWidget * gnt_entry_new(const char *text); /** * Set the maximum length of the text in the entry box. * - * @param entry The entry box. - * @param max The maximum length for text. A value of 0 means infinite length. + * @entry: The entry box. + * @max: The maximum length for text. A value of 0 means infinite length. */ void gnt_entry_set_max(GntEntry *entry, int max); /** * Set the text in an entry box. * - * @param entry The entry box. - * @param text The text to set in the box. + * @entry: The entry box. + * @text: The text to set in the box. */ void gnt_entry_set_text(GntEntry *entry, const char *text); /** * Set flags an entry box. * - * @param entry The entry box. - * @param flag The flags to set for the entry box. + * @entry: The entry box. + * @flag: The flags to set for the entry box. */ void gnt_entry_set_flag(GntEntry *entry, GntEntryFlag flag); /** * Get the text in an entry box. * - * @param entry The entry box. + * @entry: The entry box. * - * @return The current text in the entry box. + * Returns: The current text in the entry box. */ const char *gnt_entry_get_text(GntEntry *entry); /** * Clear the text in the entry box. * - * @param entry The entry box. + * @entry: The entry box. */ void gnt_entry_clear(GntEntry *entry); /** * Set whether the text in the entry box should be masked for display. * - * @param entry The entry box. - * @param set @c TRUE if the text should be masked, @c FALSE otherwise. + * @entry: The entry box. + * @set: @c TRUE if the text should be masked, @c FALSE otherwise. */ void gnt_entry_set_masked(GntEntry *entry, gboolean set); @@ -169,16 +169,16 @@ * Add a text to the history list for the text. The history length for the * entry box needs to be set first by gnt_entry_set_history_length. * - * @param entry The entry box. - * @param text A new entry for the history list. + * @entry: The entry box. + * @text: A new entry for the history list. */ void gnt_entry_add_to_history(GntEntry *entry, const char *text); /** * Set the length of history for the entry box. * - * @param entry The entry box. - * @param num The maximum length of the history, -1 for unlimited. + * @entry: The entry box. + * @num: The maximum length of the history, -1 for unlimited. */ void gnt_entry_set_history_length(GntEntry *entry, int num); @@ -186,8 +186,8 @@ * Set whether the suggestions are for the entire entry box, or for each * individual word in the entry box. * - * @param entry The entry box. - * @param word @c TRUE if the suggestions are for individual words, @c FALSE otherwise. + * @entry: The entry box. + * @word: @c TRUE if the suggestions are for individual words, @c FALSE otherwise. */ void gnt_entry_set_word_suggest(GntEntry *entry, gboolean word); @@ -195,24 +195,24 @@ * Set whether to always display the suggestions list, or only when the * tab-completion key is pressed (the TAB key, by default). * - * @param entry The entry box. - * @param always @c TRUE if the suggestion list should always be displayed. + * @entry: The entry box. + * @always: @c TRUE if the suggestion list should always be displayed. */ void gnt_entry_set_always_suggest(GntEntry *entry, gboolean always); /** * Add an item to the suggestion list. * - * @param entry The entry box. - * @param text An item to add to the suggestion list. + * @entry: The entry box. + * @text: An item to add to the suggestion list. */ void gnt_entry_add_suggest(GntEntry *entry, const char *text); /** * Remove an entry from the suggestion list. * - * @param entry The entry box. - * @param text The item to remove from the suggestion list. + * @entry: The entry box. + * @text: The item to remove from the suggestion list. */ void gnt_entry_remove_suggest(GntEntry *entry, const char *text);
--- a/finch/libgnt/gntfilesel.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntfilesel.h Wed Jan 29 05:28:33 2014 +0530 @@ -98,32 +98,32 @@ G_BEGIN_DECLS /** - * @return GType for GntFileSel. + * Returns: GType for GntFileSel. */ GType gnt_file_sel_get_gtype(void); /** * Create a new file selector. * - * @return The newly created file selector. + * Returns: The newly created file selector. */ GntWidget * gnt_file_sel_new(void); /** * Set the current location of the file selector. * - * @param sel The file selector. - * @param path The current path of the selector. + * @sel: The file selector. + * @path: The current path of the selector. * - * @return @c TRUE if the current location was successfully changed, @c FALSE otherwise. + * Returns: @c TRUE if the current location was successfully changed, @c FALSE otherwise. */ gboolean gnt_file_sel_set_current_location(GntFileSel *sel, const char *path); /** * Set wheter to only allow selecting directories. * - * @param sel The file selector. - * @param dirs @c TRUE if only directories can be selected, @c FALSE if files + * @sel: The file selector. + * @dirs: @c TRUE if only directories can be selected, @c FALSE if files * can also be selected. */ void gnt_file_sel_set_dirs_only(GntFileSel *sel, gboolean dirs); @@ -131,26 +131,26 @@ /** * Check whether the file selector allows only selecting directories. * - * @param sel The file selector. + * @sel: The file selector. * - * @return @c TRUE if only directories can be selected. + * Returns: @c TRUE if only directories can be selected. */ gboolean gnt_file_sel_get_dirs_only(GntFileSel *sel); /** * Set whether a selected file must exist. * - * @param sel The file selector. - * @param must @c TRUE if the selected file must exist. + * @sel: The file selector. + * @must: @c TRUE if the selected file must exist. */ void gnt_file_sel_set_must_exist(GntFileSel *sel, gboolean must); /** * Check whether the selector allows selecting non-existent files. * - * @param sel The file selector. + * @sel: The file selector. * - * @return @c TRUE if the selected file must exist, @c FALSE if a non-existent + * Returns: @c TRUE if the selected file must exist, @c FALSE if a non-existent * file can be selected. */ gboolean gnt_file_sel_get_must_exist(GntFileSel *sel); @@ -158,9 +158,9 @@ /** * Get the selected file in the selector. * - * @param sel The file selector. + * @sel: The file selector. * - * @return The path of the selected file. The caller should g_free the returned + * Returns: The path of the selected file. The caller should g_free the returned * string. */ char * gnt_file_sel_get_selected_file(GntFileSel *sel); @@ -168,9 +168,9 @@ /** * Get the list of selected files in the selector. * - * @param sel The file selector. + * @sel: The file selector. * - * @return A list of paths for the selected files. The caller must g_free the + * Returns: A list of paths for the selected files. The caller must g_free the * contents of the list, and g_list_free the list. */ GList * gnt_file_sel_get_selected_multi_files(GntFileSel *sel); @@ -178,43 +178,43 @@ /** * Allow selecting multiple files. * - * @param sel The file selector. - * @param set @c TRUE if selecting multiple files should be allowed. + * @sel: The file selector. + * @set: @c TRUE if selecting multiple files should be allowed. */ void gnt_file_sel_set_multi_select(GntFileSel *sel, gboolean set); /** * Set the suggested file to have selected at startup. * - * @param sel The file selector. - * @param suggest The suggested filename. + * @sel: The file selector. + * @suggest: The suggested filename. */ void gnt_file_sel_set_suggested_filename(GntFileSel *sel, const char *suggest); /** * Set custom functions to read the names of files. * - * @param sel The file selector. - * @param read_fn The custom read function. + * @sel: The file selector. + * @read_fn: The custom read function. */ void gnt_file_sel_set_read_fn(GntFileSel *sel, gboolean (*read_fn)(const char *path, GList **files, GError **error)); /** * Create a new GntFile. * - * @param name The name of the file. - * @param size The size of the file. + * @name: The name of the file. + * @size: The size of the file. * - * @return The newly created GntFile. + * Returns: The newly created GntFile. */ GntFile* gnt_file_new(const char *name, unsigned long size); /** * Create a new GntFile for a directory. * - * @param name The name of the directory. + * @name: The name of the directory. * - * @return The newly created GntFile. + * Returns: The newly created GntFile. */ GntFile* gnt_file_new_dir(const char *name);
--- a/finch/libgnt/gntkeys.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntkeys.h Wed Jan 29 05:28:33 2014 +0530 @@ -112,48 +112,48 @@ * Refine input text. This usually looks at what the terminal claims it is, * and tries to change the text to work around some oft-broken terminfo entries. * - * @param text The input text to refine. + * @text: The input text to refine. */ void gnt_keys_refine(char *text); /** * Translate a user-readable representation of an input to a machine-readable representation. * - * @param name The user-readable representation of an input (eg.: c-t) + * @name: The user-readable representation of an input (eg.: c-t) * - * @return A machine-readable representation of the input. + * Returns: A machine-readable representation of the input. */ const char *gnt_key_translate(const char *name); /** * Translate a machine-readable representation of an input to a user-readable representation. * - * @param key The machine-readable representation of an input. + * @key: The machine-readable representation of an input. * - * @return A user-readable representation of the input (eg.: c-t). + * Returns: A user-readable representation of the input (eg.: c-t). */ const char *gnt_key_lookup(const char *key); /** * Add a key combination to the internal key-tree. * - * @param key The key to add + * @key: The key to add */ void gnt_keys_add_combination(const char *key); /** * Remove a key combination from the internal key-tree. * - * @param key The key to remove. + * @key: The key to remove. */ void gnt_keys_del_combination(const char *key); /** * Find a combination from the given string. * - * @param key The input string. + * @key: The input string. * - * @return The number of bytes in the combination that starts at the beginning + * Returns: The number of bytes in the combination that starts at the beginning * of key (can be 0). */ int gnt_keys_find_combination(const char *key);
--- a/finch/libgnt/gntlabel.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntlabel.h Wed Jan 29 05:28:33 2014 +0530 @@ -67,34 +67,34 @@ G_BEGIN_DECLS /** - * @return GType for GntLabel. + * Returns: GType for GntLabel. */ GType gnt_label_get_gtype(void); /** * Create a new GntLabel. * - * @param text The text of the label. + * @text: The text of the label. * - * @return The newly created label. + * Returns: The newly created label. */ GntWidget * gnt_label_new(const char *text); /** * Create a new label with specified text attributes. * - * @param text The text. - * @param flags Text attributes for the text. + * @text: The text. + * @flags: Text attributes for the text. * - * @return The newly created label. + * Returns: The newly created label. */ GntWidget * gnt_label_new_with_format(const char *text, GntTextFormatFlags flags); /** * Change the text of a label. * - * @param label The label. - * @param text The new text to set in the label. + * @label: The label. + * @text: The new text to set in the label. */ void gnt_label_set_text(GntLabel *label, const char *text);
--- a/finch/libgnt/gntline.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntline.h Wed Jan 29 05:28:33 2014 +0530 @@ -67,7 +67,7 @@ G_BEGIN_DECLS /** - * @return GType for GntLine. + * Returns: GType for GntLine. */ GType gnt_line_get_gtype(void); @@ -77,9 +77,9 @@ /** * Create new line * - * @param vertical @c TRUE if the line should be vertical, @c FALSE for a horizontal line. + * @vertical: @c TRUE if the line should be vertical, @c FALSE for a horizontal line. * - * @return The newly created line. + * Returns: The newly created line. */ GntWidget * gnt_line_new(gboolean vertical);
--- a/finch/libgnt/gntmenu.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntmenu.h Wed Jan 29 05:28:33 2014 +0530 @@ -86,34 +86,34 @@ G_BEGIN_DECLS /** - * @return The GType for GntMenu. + * Returns: The GType for GntMenu. */ GType gnt_menu_get_gtype(void); /** * Create a new menu. * - * @param type The type of the menu, whether it's a toplevel menu or a popup menu. + * @type: The type of the menu, whether it's a toplevel menu or a popup menu. * - * @return The newly created menu. + * Returns: The newly created menu. */ GntWidget * gnt_menu_new(GntMenuType type); /** * Add an item to the menu. * - * @param menu The menu. - * @param item The item to add to the menu. + * @menu: The menu. + * @item: The item to add to the menu. */ void gnt_menu_add_item(GntMenu *menu, GntMenuItem *item); /** * Return the GntMenuItem with the given ID. * - * @param menu The menu. - * @param id The ID for an item. + * @menu: The menu. + * @id: The ID for an item. * - * @return The menuitem with the given ID, or @c NULL. + * Returns: The menuitem with the given ID, or @c NULL. * * @since 2.3.0 */
--- a/finch/libgnt/gntmenuitem.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntmenuitem.h Wed Jan 29 05:28:33 2014 +0530 @@ -87,42 +87,42 @@ G_BEGIN_DECLS /** - * @return GType for GntMenuItem. + * Returns: GType for GntMenuItem. */ GType gnt_menuitem_get_gtype(void); /** * Create a new menuitem. * - * @param text Label for the menuitem. + * @text: Label for the menuitem. * - * @return The newly created menuitem. + * Returns: The newly created menuitem. */ GntMenuItem * gnt_menuitem_new(const char *text); /** * Set a callback function for a menuitem. * - * @param item The menuitem. - * @param callback The callback function. - * @param data Data to send to the callback function. + * @item: The menuitem. + * @callback: The callback function. + * @data: Data to send to the callback function. */ void gnt_menuitem_set_callback(GntMenuItem *item, GntMenuItemCallback callback, gpointer data); /** * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback. * - * @param item The menuitem. - * @param menu The submenu. + * @item: The menuitem. + * @menu: The submenu. */ void gnt_menuitem_set_submenu(GntMenuItem *item, GntMenu *menu); /** * Get the submenu for a menuitem. * - * @param item The menuitem. + * @item: The menuitem. * - * @return The submenu, or @c NULL. + * Returns: The submenu, or @c NULL. * * @since 2.3.0 */ @@ -131,17 +131,17 @@ /** * Set a trigger key for the item. * - * @param item The menuitem - * @param trigger The key that will trigger the item when the parent manu is visible + * @item: The menuitem + * @trigger: The key that will trigger the item when the parent manu is visible */ void gnt_menuitem_set_trigger(GntMenuItem *item, char trigger); /** * Get the trigger key for a menuitem. * - * @param item The menuitem + * @item: The menuitem * - * @return The trigger key for the menuitem. + * Returns: The trigger key for the menuitem. * * @see gnt_menuitem_set_trigger */ @@ -150,8 +150,8 @@ /** * Set an ID for the menuitem. * - * @param item The menuitem. - * @param id The ID for the menuitem. + * @item: The menuitem. + * @id: The ID for the menuitem. * * @since 2.3.0 */ @@ -160,9 +160,9 @@ /** * Get the ID of the menuitem. * - * @param item The menuitem. + * @item: The menuitem. * - * @return The ID for the menuitem. + * Returns: The ID for the menuitem. * * @since 2.3.0 */ @@ -173,9 +173,9 @@ * Activating the menuitem will first trigger the 'activate' signal for the * menuitem. Then the callback for the menuitem is triggered, if there is one. * - * @param item The menuitem. + * @item: The menuitem. * - * @return Whether the callback for the menuitem was called. + * Returns: Whether the callback for the menuitem was called. * * @since 2.3.0 */
--- a/finch/libgnt/gntmenuitemcheck.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntmenuitemcheck.h Wed Jan 29 05:28:33 2014 +0530 @@ -66,33 +66,33 @@ G_BEGIN_DECLS /** - * @return GType for GntMenuItemCheck. + * Returns: GType for GntMenuItemCheck. */ GType gnt_menuitem_check_get_gtype(void); /** * Create a new menuitem. * - * @param text The text for the menuitem. + * @text: The text for the menuitem. * - * @return The newly created menuitem. + * Returns: The newly created menuitem. */ GntMenuItem * gnt_menuitem_check_new(const char *text); /** * Check whether the menuitem is checked or not. * - * @param item The menuitem. + * @item: The menuitem. * - * @return @c TRUE if the item is checked, @c FALSE otherwise. + * Returns: @c TRUE if the item is checked, @c FALSE otherwise. */ gboolean gnt_menuitem_check_get_checked(GntMenuItemCheck *item); /** * Set whether the menuitem is checked or not. * - * @param item The menuitem. - * @param set @c TRUE if the item should be checked, @c FALSE otherwise. + * @item: The menuitem. + * @set: @c TRUE if the item should be checked, @c FALSE otherwise. */ void gnt_menuitem_check_set_checked(GntMenuItemCheck *item, gboolean set);
--- a/finch/libgnt/gntprogressbar.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntprogressbar.h Wed Jan 29 05:28:33 2014 +0530 @@ -61,14 +61,14 @@ /** * Get the GType for GntProgressBar - * @return The GType for GntProrgressBar + * Returns: The GType for GntProrgressBar **/ GType gnt_progress_bar_get_gtype (void); /** * Create a new GntProgressBar - * @return The new GntProgressBar + * Returns: The new GntProgressBar **/ GntWidget * gnt_progress_bar_new (void); @@ -76,8 +76,8 @@ /** * Set the progress for a progress bar * - * @param pbar The GntProgressBar - * @param fraction The value between 0 and 1 to display + * @pbar: The GntProgressBar + * @fraction: The value between 0 and 1 to display **/ void gnt_progress_bar_set_fraction (GntProgressBar *pbar, gdouble fraction); @@ -85,8 +85,8 @@ /** * Set the orientation for a progress bar * - * @param pbar The GntProgressBar - * @param orientation The orientation to use + * @pbar: The GntProgressBar + * @orientation: The orientation to use **/ void gnt_progress_bar_set_orientation (GntProgressBar *pbar, GntProgressBarOrientation orientation); @@ -94,8 +94,8 @@ /** * Controls whether the progress value is shown * - * @param pbar The GntProgressBar - * @param show A boolean indicating if the value is shown + * @pbar: The GntProgressBar + * @show: A boolean indicating if the value is shown **/ void gnt_progress_bar_set_show_progress (GntProgressBar *pbar, gboolean show); @@ -103,8 +103,8 @@ /** * Get the progress that is displayed * - * @param pbar The GntProgressBar - * @return The progress displayed as a value between 0 and 1 + * @pbar: The GntProgressBar + * Returns: The progress displayed as a value between 0 and 1 **/ gdouble gnt_progress_bar_get_fraction (GntProgressBar *pbar); @@ -112,8 +112,8 @@ /** * Get the orientation for the progress bar * - * @param pbar The GntProgressBar - * @return The current orientation of the progress bar + * @pbar: The GntProgressBar + * Returns: The current orientation of the progress bar **/ GntProgressBarOrientation gnt_progress_bar_get_orientation (GntProgressBar *pbar); @@ -121,8 +121,8 @@ /** * Get a boolean describing if the progress value is shown * - * @param pbar The GntProgressBar - * @return A boolean @c true if the progress value is shown, @c false otherwise. + * @pbar: The GntProgressBar + * Returns: A boolean @c true if the progress value is shown, @c false otherwise. **/ gboolean gnt_progress_bar_get_show_progress (GntProgressBar *pbar);
--- a/finch/libgnt/gntslider.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntslider.h Wed Jan 29 05:28:33 2014 +0530 @@ -74,7 +74,7 @@ G_BEGIN_DECLS /** - * @return The GType for GntSlider + * Returns: The GType for GntSlider * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -86,11 +86,11 @@ /** * Create a new slider. * - * @param orient A vertical slider is created if @c TRUE, otherwise the slider is horizontal. - * @param max The maximum value for the slider - * @param min The minimum value for the slider + * @orient: A vertical slider is created if @c TRUE, otherwise the slider is horizontal. + * @max: The maximum value for the slider + * @min: The minimum value for the slider * - * @return The newly created slider + * Returns: The newly created slider * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -99,9 +99,9 @@ /** * Set the range of the slider. * - * @param slider The slider - * @param max The maximum value - * @param min The minimum value + * @slider: The slider + * @max: The maximum value + * @min: The minimum value * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -110,8 +110,8 @@ /** * Sets the amount of change at each step. * - * @param slider The slider - * @param step The amount for each step + * @slider: The slider + * @step: The amount for each step * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -120,8 +120,8 @@ /** * Sets the amount of change a small step. * - * @param slider The slider - * @param step The amount for a small step (for the slider) + * @slider: The slider + * @step: The amount for a small step (for the slider) * * @since 2.2.0 */ @@ -130,8 +130,8 @@ /** * Sets the amount of change a large step. * - * @param slider The slider - * @param step The amount for a large step (for the slider) + * @slider: The slider + * @step: The amount for a large step (for the slider) * * @since 2.2.0 */ @@ -140,11 +140,11 @@ /** * Advance the slider forward or backward. * - * @param slider The slider - * @param steps The number of amounts to change, positive to change + * @slider: The slider + * @steps: The number of amounts to change, positive to change * forward, negative to change backward * - * @return The value of the slider after the change + * Returns: The value of the slider after the change * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -153,8 +153,8 @@ /** * Set the current value for the slider. * - * @param slider The slider - * @param value The current value + * @slider: The slider + * @value: The current value * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -163,7 +163,7 @@ /** * Get the current value for the slider. * - * @param slider The slider + * @slider: The slider * * * @since 2.0.0 (gnt), 2.1.0 (pidgin) @@ -173,8 +173,8 @@ /** * Update a label with the value of the slider whenever the value changes. * - * @param slider The slider - * @param label The label to update + * @slider: The slider + * @label: The label to update * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */
--- a/finch/libgnt/gntstyle.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntstyle.h Wed Jan 29 05:28:33 2014 +0530 @@ -40,25 +40,25 @@ /** * Read configuration from a file. * - * @param filename The filename to read configuration from. + * @filename: The filename to read configuration from. */ void gnt_style_read_configure_file(const char *filename); /** * Get the user-setting for a style. - * @param style The style. - * @return The user-setting, or @c NULL. + * @style: The style. + * Returns: The user-setting, or @c NULL. */ const char *gnt_style_get(GntStyle style); /** * Get the value of a preference in ~/.gntrc. * - * @param group The name of the group in the keyfile. If @c NULL, the prgname + * @group: The name of the group in the keyfile. If @c NULL, the prgname * will be used first, if available. Otherwise, "general" will be used. - * @param key The key + * @key: The key * - * @return The value of the setting as a string, or @c NULL + * Returns: The value of the setting as a string, or @c NULL * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -67,12 +67,12 @@ /** * Get the value of a preference in ~/.gntrc. * - * @param group The name of the group in the keyfile. If @c NULL, the prgname + * @group: The name of the group in the keyfile. If @c NULL, the prgname * will be used first, if available. Otherwise, "general" will be used. - * @param key The key - * @param length Return location for the number of strings returned, or NULL + * @key: The key + * @length: Return location for the number of strings returned, or NULL * - * @return NULL terminated string array. The array should be freed with g_strfreev(). + * Returns: NULL terminated string array. The array should be freed with g_strfreev(). * * @since 2.4.0 */ @@ -81,11 +81,11 @@ /** * Get the value of a color pair in ~/.gntrc. * - * @param group The name of the group in the keyfile. If @c NULL, the prgname + * @group: The name of the group in the keyfile. If @c NULL, the prgname * will be used first, if available. Otherwise, "general" will be used. - * @param key The key + * @key: The key * - * @return The value of the color as an int, or 0 on error. + * Returns: The value of the color as an int, or 0 on error. * * @since 2.4.0 */ @@ -95,8 +95,8 @@ * Parse a boolean preference. For example, if 'value' is "false" (ignoring case) * or "0", the return value will be @c FALSE, otherwise @c TRUE. * - * @param value The value of the boolean setting as a string - * @return The boolean value + * @value: The value of the boolean setting as a string + * Returns: The boolean value * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -105,11 +105,11 @@ /** * Get the boolean value for a user-setting. * - * @param style The style. - * @param def The default value (i.e, the value if the user didn't define + * @style: The style. + * @def: The default value (i.e, the value if the user didn't define * any value) * - * @return The value of the setting. + * Returns: The value of the setting. */ gboolean gnt_style_get_bool(GntStyle style, gboolean def); @@ -126,10 +126,10 @@ /** * Read menu-accels from ~/.gntrc * - * @param name The name of the window. - * @param table The hastable to store the accel information. + * @name: The name of the window. + * @table: The hastable to store the accel information. * - * @return @c TRUE if some accels were read, @c FALSE otherwise. + * Returns: @c TRUE if some accels were read, @c FALSE otherwise. */ gboolean gnt_style_read_menu_accels(const char *name, GHashTable *table);
--- a/finch/libgnt/gnttextview.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gnttextview.h Wed Jan 29 05:28:33 2014 +0530 @@ -88,40 +88,40 @@ G_BEGIN_DECLS /** - * @return GType for GntTextView. + * Returns: GType for GntTextView. */ GType gnt_text_view_get_gtype(void); /** * Create a new textview. * - * @return The newly created textview. + * Returns: The newly created textview. */ GntWidget * gnt_text_view_new(void); /** * Scroll the textview. - * @param view The textview to scroll. - * @param scroll scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end. + * @view: The textview to scroll. + * @scroll: scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end. */ void gnt_text_view_scroll(GntTextView *view, int scroll); /** * Append new text in a textview. * - * @param view The textview. - * @param text The text to append to the textview. - * @param flags The text-flags to apply to the new text. + * @view: The textview. + * @text: The text to append to the textview. + * @flags: The text-flags to apply to the new text. */ void gnt_text_view_append_text_with_flags(GntTextView *view, const char *text, GntTextFormatFlags flags); /** * Append text in the textview, with some identifier (tag) for the added text. * - * @param view The textview. - * @param text The text to append. - * @param flags The text-flags to apply to the new text. - * @param tag The tag for the appended text, so it can be changed later (@see gnt_text_view_tag_change) + * @view: The textview. + * @text: The text to append. + * @flags: The text-flags to apply to the new text. + * @tag: The tag for the appended text, so it can be changed later (@see gnt_text_view_tag_change) */ void gnt_text_view_append_text_with_tag(GntTextView *view, const char *text, GntTextFormatFlags flags, const char *tag); @@ -129,54 +129,54 @@ * Move the cursor to the beginning of the next line and resets text-attributes. * It first completes the current line with the current text-attributes. * - * @param view The textview. + * @view: The textview. */ void gnt_text_view_next_line(GntTextView *view); /** * Convert GNT-text formats to ncurses-text attributes. * - * @param flags The GNT text format. + * @flags: The GNT text format. * - * @return Nucrses text attribute. + * Returns: Nucrses text attribute. */ chtype gnt_text_format_flag_to_chtype(GntTextFormatFlags flags); /** * Clear the contents of the textview. * - * @param view The textview. + * @view: The textview. */ void gnt_text_view_clear(GntTextView *view); /** * The number of lines below the bottom-most visible line. * - * @param view The textview. + * @view: The textview. * - * @return Number of lines below the bottom-most visible line. + * Returns: Number of lines below the bottom-most visible line. */ int gnt_text_view_get_lines_below(GntTextView *view); /** * The number of lines above the topmost visible line. * - * @param view The textview. + * @view: The textview. * - * @return Number of lines above the topmost visible line. + * Returns: Number of lines above the topmost visible line. */ int gnt_text_view_get_lines_above(GntTextView *view); /** * Change the text of a tag. * - * @param view The textview. - * @param name The name of the tag. - * @param text The new text for the text. If 'text' is @c NULL, the tag is removed. - * @param all @c TRUE if all of the instancess of the tag should be changed, @c FALSE if + * @view: The textview. + * @name: The name of the tag. + * @text: The new text for the text. If 'text' is @c NULL, the tag is removed. + * @all: @c TRUE if all of the instancess of the tag should be changed, @c FALSE if * only the first instance should be changed. * - * @return The number of instances changed. + * Returns: The number of instances changed. */ int gnt_text_view_tag_change(GntTextView *view, const char *name, const char *text, gboolean all); @@ -184,8 +184,8 @@ * Setup hooks so that pressing up/down/page-up/page-down keys when 'widget' is * in focus scrolls the textview. * - * @param view The textview. - * @param widget The trigger widget. + * @view: The textview. + * @widget: The trigger widget. */ void gnt_text_view_attach_scroll_widget(GntTextView *view, GntWidget *widget); @@ -203,8 +203,8 @@ * path = /path/to/pager * @endcode * - * @param view The textview. - * @param pager The widget to trigger the PAGER. + * @view: The textview. + * @pager: The widget to trigger the PAGER. */ void gnt_text_view_attach_pager_widget(GntTextView *view, GntWidget *pager); @@ -222,16 +222,16 @@ * path = /path/to/editor * @endcode * - * @param view The textview. - * @param widget The widget to trigger the EDITOR. + * @view: The textview. + * @widget: The widget to trigger the EDITOR. */ void gnt_text_view_attach_editor_widget(GntTextView *view, GntWidget *widget); /** * Set a GntTextViewFlag for the textview widget. * - * @param view The textview widget - * @param flag The flag to set + * @view: The textview widget + * @flag: The flag to set * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */
--- a/finch/libgnt/gnttree.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gnttree.h Wed Jan 29 05:28:33 2014 +0530 @@ -102,14 +102,14 @@ G_BEGIN_DECLS /** - * @return The GType for GntTree + * Returns: The GType for GntTree */ GType gnt_tree_get_gtype(void); /** * Create a tree with one column. * - * @return The newly created tree + * Returns: The newly created tree * * @see gnt_tree_new_with_columns */ @@ -118,9 +118,9 @@ /** * Create a tree with a specified number of columns. * - * @param columns Number of columns + * @columns: Number of columns * - * @return The newly created tree + * Returns: The newly created tree * * @see gnt_tree_new */ @@ -129,25 +129,25 @@ /** * The number of rows the tree should display at a time. * - * @param tree The tree - * @param rows The number of rows + * @tree: The tree + * @rows: The number of rows */ void gnt_tree_set_visible_rows(GntTree *tree, int rows); /** * Get the number visible rows. * - * @param tree The tree + * @tree: The tree * - * @return The number of visible rows + * Returns: The number of visible rows */ int gnt_tree_get_visible_rows(GntTree *tree); /** * Scroll the contents of the tree. * - * @param tree The tree - * @param count If positive, the tree will be scrolled down by count rows, + * @tree: The tree + * @count: If positive, the tree will be scrolled down by count rows, * otherwise, it will be scrolled up by count rows. */ void gnt_tree_scroll(GntTree *tree, int count); @@ -155,13 +155,13 @@ /** * Insert a row in the tree. * - * @param tree The tree - * @param key The key for the row - * @param row The row to insert - * @param parent The key for the parent row - * @param bigbro The key for the row to insert the new row after. + * @tree: The tree + * @key: The key for the row + * @row: The row to insert + * @parent: The key for the parent row + * @bigbro: The key for the row to insert the new row after. * - * @return The inserted row + * Returns: The inserted row * * @see gnt_tree_create_row * @see gnt_tree_add_row_last @@ -172,12 +172,12 @@ /** * Insert a row at the end of the tree. * - * @param tree The tree - * @param key The key for the row - * @param row The row to insert - * @param parent The key for the parent row + * @tree: The tree + * @key: The key for the row + * @row: The row to insert + * @parent: The key for the parent row * - * @return The inserted row + * Returns: The inserted row * * @see gnt_tree_create_row * @see gnt_tree_add_row_after @@ -188,18 +188,18 @@ /** * Get the key for the selected row. * - * @param tree The tree + * @tree: The tree * - * @return The key for the selected row + * Returns: The key for the selected row */ gpointer gnt_tree_get_selection_data(GntTree *tree); /** * Get the text displayed for the selected row. * - * @param tree The tree + * @tree: The tree * - * @return The text, which needs to be freed by the caller + * Returns: The text, which needs to be freed by the caller * @see gnt_tree_get_row_text_list * @see gnt_tree_get_selection_text_list */ @@ -208,12 +208,12 @@ /** * Get a list of text for a row. * - * @param tree The tree - * @param key A key corresponding to the row in question. If key + * @tree: The tree + * @key: A key corresponding to the row in question. If key * is @c NULL, the text list for the selected row will * be returned. * - * @return A list of texts of a row. The list and its data should be + * Returns: A list of texts of a row. The list and its data should be * freed by the caller. The caller should make sure that if * any column of the tree contains binary data, it's not freed. * @see gnt_tree_get_selection_text_list @@ -224,10 +224,10 @@ /** * Get the key of a row. * - * @param tree The tree - * @param row The GntTreeRow object + * @tree: The tree + * @row: The GntTreeRow object * - * @return The key of the row. + * Returns: The key of the row. * @since 2.8.0 (gnt), 2.7.2 (pidgin) */ gpointer gnt_tree_row_get_key(GntTree *tree, GntTreeRow *row); @@ -235,10 +235,10 @@ /** * Get the next row. * - * @param tree The tree - * @param row The GntTreeRow object + * @tree: The tree + * @row: The GntTreeRow object * - * @return The next row. + * Returns: The next row. * @since 2.8.0 (gnt), 2.7.2 (pidgin) */ GntTreeRow * gnt_tree_row_get_next(GntTree *tree, GntTreeRow *row); @@ -246,10 +246,10 @@ /** * Get the previous row. * - * @param tree The tree - * @param row The GntTreeRow object + * @tree: The tree + * @row: The GntTreeRow object * - * @return The previous row. + * Returns: The previous row. * @since 2.8.0 (gnt), 2.7.2 (pidgin) */ GntTreeRow * gnt_tree_row_get_prev(GntTree *tree, GntTreeRow *row); @@ -257,10 +257,10 @@ /** * Get the child row. * - * @param tree The tree - * @param row The GntTreeRow object + * @tree: The tree + * @row: The GntTreeRow object * - * @return The child row. + * Returns: The child row. * @since 2.8.0 (gnt), 2.7.2 (pidgin) */ GntTreeRow * gnt_tree_row_get_child(GntTree *tree, GntTreeRow *row); @@ -268,10 +268,10 @@ /** * Get the parent row. * - * @param tree The tree - * @param row The GntTreeRow object + * @tree: The tree + * @row: The GntTreeRow object * - * @return The parent row. + * Returns: The parent row. * @since 2.8.0 (gnt), 2.7.2 (pidgin) */ GntTreeRow * gnt_tree_row_get_parent(GntTree *tree, GntTreeRow *row); @@ -279,9 +279,9 @@ /** * Get a list of text of the current row. * - * @param tree The tree + * @tree: The tree * - * @return A list of texts of the currently selected row. The list + * Returns: A list of texts of the currently selected row. The list * and its data should be freed by the caller. The caller * should make sure that if any column of the tree contains * binary data, it's not freed. @@ -293,56 +293,56 @@ /** * Returns the list of rows in the tree. * - * @param tree The tree + * @tree: The tree * - * @return The list of the rows. The list should not be modified by the caller. + * Returns: The list of the rows. The list should not be modified by the caller. */ GList *gnt_tree_get_rows(GntTree *tree); /** * Remove a row from the tree. * - * @param tree The tree - * @param key The key for the row to remove + * @tree: The tree + * @key: The key for the row to remove */ void gnt_tree_remove(GntTree *tree, gpointer key); /** * Remove all the item from the tree. * - * @param tree The tree + * @tree: The tree */ void gnt_tree_remove_all(GntTree *tree); /** * Get the visible line number of the selected row. * - * @param tree The tree + * @tree: The tree * - * @return The line number of the currently selected row + * Returns: The line number of the currently selected row */ int gnt_tree_get_selection_visible_line(GntTree *tree); /** * Change the text of a column in a row. * - * @param tree The tree - * @param key The key for the row - * @param colno The index of the column - * @param text The new text + * @tree: The tree + * @key: The key for the row + * @colno: The index of the column + * @text: The new text */ void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text); /** * Add a checkable item in the tree. * - * @param tree The tree - * @param key The key for the row - * @param row The row to add - * @param parent The parent of the row, or @c NULL - * @param bigbro The row to insert after, or @c NULL + * @tree: The tree + * @key: The key for the row + * @row: The row to add + * @parent: The parent of the row, or @c NULL + * @bigbro: The row to insert after, or @c NULL * - * @return The row inserted. + * Returns: The row inserted. * * @see gnt_tree_create_row * @see gnt_tree_create_row_from_list @@ -354,37 +354,37 @@ /** * Set whether a checkable item is checked or not. * - * @param tree The tree - * @param key The key for the row - * @param set @c TRUE if the item should be checked, @c FALSE if not + * @tree: The tree + * @key: The key for the row + * @set: @c TRUE if the item should be checked, @c FALSE if not */ void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set); /** * Return whether a row is selected or not, where the row is a checkable item. * - * @param tree The tree - * @param key The key for the row + * @tree: The tree + * @key: The key for the row * - * @return @c TRUE if the row is checked, @c FALSE otherwise. + * Returns: @c TRUE if the row is checked, @c FALSE otherwise. */ gboolean gnt_tree_get_choice(GntTree *tree, void *key); /** * Set flags for the text in a row in the tree. * - * @param tree The tree - * @param key The key for the row - * @param flags The flags to set + * @tree: The tree + * @key: The key for the row + * @flags: The flags to set */ void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags); /** * Set color for the text in a row in the tree. * - * @param tree The tree - * @param key The key for the row - * @param color The color + * @tree: The tree + * @key: The key for the row + * @color: The color * @since 2.4.0 */ void gnt_tree_set_row_color(GntTree *tree, void *key, int color); @@ -392,18 +392,18 @@ /** * Select a row. * - * @param tree The tree - * @param key The key of the row to select + * @tree: The tree + * @key: The key of the row to select */ void gnt_tree_set_selected(GntTree *tree , void *key); /** * Create a row to insert in the tree. * - * @param tree The tree - * @param ... A string for each column in the tree + * @tree: The tree + * @...: A string for each column in the tree * - * @return The row + * Returns: The row * * @see gnt_tree_create_row_from_list * @see gnt_tree_add_row_after @@ -415,10 +415,10 @@ /** * Create a row from a list of text. * - * @param tree The tree - * @param list The list containing the text for each column + * @tree: The tree + * @list: The list containing the text for each column * - * @return The row + * Returns: The row * * @see gnt_tree_create_row * @see gnt_tree_add_row_after @@ -430,9 +430,9 @@ /** * Set the width of a column in the tree. * - * @param tree The tree - * @param col The index of the column - * @param width The width for the column + * @tree: The tree + * @col: The index of the column + * @width: The width for the column * * @see gnt_tree_set_column_width_ratio * @see gnt_tree_set_column_resizable @@ -442,9 +442,9 @@ /** * Set the title for a column. * - * @param tree The tree - * @param index The index of the column - * @param title The title for the column + * @tree: The tree + * @index: The index of the column + * @title: The title for the column * * @see gnt_tree_set_column_titles * @see gnt_tree_set_show_title @@ -456,8 +456,8 @@ /** * Set the titles of the columns * - * @param tree The tree - * @param ... One title for each column in the tree + * @tree: The tree + * @...: One title for each column in the tree * * @see gnt_tree_set_column_title * @see gnt_tree_set_show_title @@ -467,8 +467,8 @@ /** * Set whether to display the title of the columns. * - * @param tree The tree - * @param set If @c TRUE, the column titles are displayed + * @tree: The tree + * @set: If @c TRUE, the column titles are displayed * * @see gnt_tree_set_column_title * @see gnt_tree_set_column_titles @@ -478,8 +478,8 @@ /** * Set the compare function for sorting the data. * - * @param tree The tree - * @param func The comparison function, which is used to compare + * @tree: The tree + * @func: The comparison function, which is used to compare * the keys * * @see gnt_tree_sort_row @@ -489,25 +489,25 @@ /** * Set whether a row, which has child rows, should be expanded. * - * @param tree The tree - * @param key The key of the row - * @param expanded Whether to expand the child rows + * @tree: The tree + * @key: The key of the row + * @expanded: Whether to expand the child rows */ void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded); /** * Set whether to show column separators. * - * @param tree The tree - * @param set If @c TRUE, the column separators are displayed + * @tree: The tree + * @set: If @c TRUE, the column separators are displayed */ void gnt_tree_set_show_separator(GntTree *tree, gboolean set); /** * Sort a row in the tree. * - * @param tree The tree - * @param row The row to sort + * @tree: The tree + * @row: The row to sort * * @see gnt_tree_set_compare_func */ @@ -516,17 +516,17 @@ /** * Automatically adjust the width of the columns in the tree. * - * @param tree The tree + * @tree: The tree */ void gnt_tree_adjust_columns(GntTree *tree); /** * Set the hash functions to use to hash, compare and free the keys. * - * @param tree The tree - * @param hash The hashing function - * @param eq The function to compare keys - * @param kd The function to use to free the keys when a row is removed + * @tree: The tree + * @hash: The hashing function + * @eq: The function to compare keys + * @kd: The function to use to free the keys when a row is removed * from the tree */ void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd); @@ -536,9 +536,9 @@ * This can be useful when, for example, we want to store some data * which we don't want/need to display. * - * @param tree The tree - * @param col The index of the column - * @param vis If @c FALSE, the column will not be displayed + * @tree: The tree + * @col: The index of the column + * @vis: If @c FALSE, the column will not be displayed */ void gnt_tree_set_column_visible(GntTree *tree, int col, gboolean vis); @@ -546,9 +546,9 @@ * Set whether a column can be resized to keep the same ratio when the * tree is resized. * - * @param tree The tree - * @param col The index of the column - * @param res If @c FALSE, the column will not be resized when the + * @tree: The tree + * @col: The index of the column + * @res: If @c FALSE, the column will not be resized when the * tree is resized * * @see gnt_tree_set_col_width @@ -562,18 +562,18 @@ * Set whether data in a column should be considered as binary data, and * not as strings. A column containing binary data will be display empty text. * - * @param tree The tree - * @param col The index of the column - * @param bin @c TRUE if the data for the column is binary + * @tree: The tree + * @col: The index of the column + * @bin: @c TRUE if the data for the column is binary */ void gnt_tree_set_column_is_binary(GntTree *tree, int col, gboolean bin); /** * Set whether text in a column should be right-aligned. * - * @param tree The tree - * @param col The index of the column - * @param right @c TRUE if the text in the column should be right aligned + * @tree: The tree + * @col: The index of the column + * @right: @c TRUE if the text in the column should be right aligned * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -583,8 +583,8 @@ * Set column widths to use when calculating column widths after a tree * is resized. * - * @param tree The tree - * @param cols Array of widths. The width must have the same number + * @tree: The tree + * @cols: Array of widths. The width must have the same number * of entries as the number of columns in the tree, or * end with a negative value for a column-width. * @@ -598,8 +598,8 @@ /** * Set the column to use for typeahead searching. * - * @param tree The tree - * @param col The index of the column + * @tree: The tree + * @col: The index of the column * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -608,8 +608,8 @@ /** * Check whether the user is currently in the middle of a search. * - * @param tree The tree - * @return @c TRUE if the user is searching, @c FALSE otherwise. + * @tree: The tree + * Returns: @c TRUE if the user is searching, @c FALSE otherwise. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -618,8 +618,8 @@ /** * Set a custom search function. * - * @param tree The tree - * @param func The custom search function. The search function is + * @tree: The tree + * @func: The custom search function. The search function is * sent the tree itself, the key of a row, the search * string and the content of row in the search column. * If the function returns @c TRUE, the row is dislayed, @@ -633,10 +633,10 @@ /** * Get the parent key for a row. * - * @param tree The tree - * @param key The key for the row. + * @tree: The tree + * @key: The key for the row. * - * @return The key of the parent row. + * Returns: The key of the parent row. * @since 2.4.0 */ gpointer gnt_tree_get_parent_key(GntTree *tree, gpointer key);
--- a/finch/libgnt/gntutils.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntutils.h Wed Jan 29 05:28:33 2014 +0530 @@ -35,9 +35,9 @@ /** * Compute the width and height required to view the text on the screen. * - * @param text The text to be displayed. - * @param width The width required is set here, if not @c NULL. - * @param height The height required is set here, if not @c NULL. + * @text: The text to be displayed. + * @width: The width required is set here, if not @c NULL. + * @height: The height required is set here, if not @c NULL. */ void gnt_util_get_text_bound(const char *text, int *width, int *height); @@ -45,23 +45,23 @@ /** * Get the onscreen width of a string, or a substring. * - * @param start The beginning of the string. - * @param end The end of the string. The width returned is the width + * @start: The beginning of the string. + * @end: The end of the string. The width returned is the width * upto (but not including) end. If end is NULL, then start * is considered as a @c NULL-terminated string. * - * @return The on-screen width of the string. + * Returns: The on-screen width of the string. */ int gnt_util_onscreen_width(const char *start, const char *end); /** * Computes and returns the string after a specific number of onscreen characters. * - * @param str The string. - * @param len The length to consider. If non-positive, the entire screenlength is used. + * @str: The string. + * @len: The length to consider. If non-positive, the entire screenlength is used. * @param w The actual width of the string upto the returned offset, if not @c NULL. * - * @return The string after len offset. + * Returns: The string after len offset. */ const char *gnt_util_onscreen_width_to_pointer(const char *str, int len, int *w); @@ -69,26 +69,26 @@ * Inserts newlines in 'string' where necessary so that its onscreen width is * no more than 'maxw'. * - * @param string The string. - * @param maxw The width that the string should fit into. If maxw is <= 0, + * @string: The string. + * @maxw: The width that the string should fit into. If maxw is <= 0, * then the available maximum width is used. * - * @return A newly allocated string that needs to be freed by the caller. + * Returns: A newly allocated string that needs to be freed by the caller. */ char * gnt_util_onscreen_fit_string(const char *string, int maxw); /** * Duplicate the contents of a hastable. * - * @param src The source hashtable. - * @param hash The hash-function to use. - * @param equal The hash-equal function to use. - * @param key_d The key-destroy function to use. - * @param value_d The value-destroy function to use. - * @param key_dup The function to use to duplicate the key. - * @param value_dup The function to use to duplicate the value. + * @src: The source hashtable. + * @hash: The hash-function to use. + * @equal: The hash-equal function to use. + * @key_d: The key-destroy function to use. + * @value_d: The value-destroy function to use. + * @key_dup: The function to use to duplicate the key. + * @value_dup: The function to use to duplicate the value. * - * @return The new hashtable. + * Returns: The new hashtable. */ GHashTable * g_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GDupFunc key_dup, GDupFunc value_dup); @@ -96,21 +96,21 @@ * To be used with g_signal_new. Look in the key_pressed signal-definition in * gntwidget.c for usage. * - * @param ihint NA - * @param return_accu NA - * @param handler_return NA - * @param dummy NA + * @ihint: NA + * Returns:_accu: NA + * @handler_return: NA + * @dummy: NA * - * @return NA + * Returns: NA */ gboolean gnt_boolean_handled_accumulator(GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy); /** * Get a helpful display about the bindings of a widget. * - * @param widget The widget to get bindings for. + * @widget: The widget to get bindings for. * - * @return Returns a GntTree populated with "key" -> "binding" for the widget. + * Returns: Returns a GntTree populated with "key" -> "binding" for the widget. */ GntWidget * gnt_widget_bindings_view(GntWidget *widget); @@ -127,8 +127,8 @@ * 2, &win, &button); * @endcode * - * @param string The XML string. - * @param num The number of widgets to return, followed by 'num' GntWidget ** + * @string: The XML string. + * @num: The number of widgets to return, followed by 'num' GntWidget ** */ void gnt_util_parse_widgets(const char *string, int num, ...); @@ -136,9 +136,9 @@ * Parse an XHTML string and add it in a GntTextView with * appropriate text flags. * - * @param string The XHTML string - * @param tv The GntTextView - * @return @c TRUE if the string was added to the textview properly, @c FALSE otherwise. + * @string: The XHTML string + * @tv: The GntTextView + * Returns: @c TRUE if the string was added to the textview properly, @c FALSE otherwise. * * @since 2.2.0 */ @@ -147,9 +147,9 @@ /** * Make some keypress activate a button when some key is pressed with 'wid' in focus. * - * @param widget The widget - * @param key The key to trigger the button - * @param button The button to trigger + * @widget: The widget + * @key: The key to trigger the button + * @button: The button to trigger * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */
--- a/finch/libgnt/gntwidget.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntwidget.h Wed Jan 29 05:28:33 2014 +0530 @@ -140,13 +140,13 @@ G_BEGIN_DECLS /** - * @return GType for GntWidget. + * Returns: GType for GntWidget. */ GType gnt_widget_get_gtype(void); /** * Destroy a widget. - * @param widget The widget to destroy. + * @widget: The widget to destroy. */ void gnt_widget_destroy(GntWidget *widget); @@ -154,13 +154,13 @@ * Show a widget. This should only be used for toplevel widgets. For the rest * of the widgets, use #gnt_widget_draw instead. * - * @param widget The widget to show. + * @widget: The widget to show. */ void gnt_widget_show(GntWidget *widget); /** * Draw a widget. - * @param widget The widget to draw. + * @widget: The widget to draw. */ void gnt_widget_draw(GntWidget *widget); @@ -172,14 +172,14 @@ /** * Hide a widget. - * @param widget The widget to hide. + * @widget: The widget to hide. */ void gnt_widget_hide(GntWidget *widget); /** * Get the position of a widget. * - * @param widget The widget. + * @widget: The widget. * @param x Location to store the x-coordinate of the widget. * @param y Location to store the y-coordinate of the widget. */ @@ -187,7 +187,7 @@ /** * Set the position of a widget. - * @param widget The widget to reposition. + * @widget: The widget to reposition. * @param x The x-coordinate of the widget. * @param y The x-coordinate of the widget. */ @@ -195,89 +195,89 @@ /** * Request a widget to calculate its desired size. - * @param widget The widget. + * @widget: The widget. */ void gnt_widget_size_request(GntWidget *widget); /** * Get the size of a widget. - * @param widget The widget. - * @param width Location to store the width of the widget. - * @param height Location to store the height of the widget. + * @widget: The widget. + * @width: Location to store the width of the widget. + * @height: Location to store the height of the widget. */ void gnt_widget_get_size(GntWidget *widget, int *width, int *height); /** * Set the size of a widget. * - * @param widget The widget to resize. - * @param width The width of the widget. - * @param height The height of the widget. + * @widget: The widget to resize. + * @width: The width of the widget. + * @height: The height of the widget. * - * @return If the widget was resized to the new size. + * Returns: If the widget was resized to the new size. */ gboolean gnt_widget_set_size(GntWidget *widget, int width, int height); /** * Confirm a requested a size for a widget. * - * @param widget The widget. - * @param width The requested width. - * @param height The requested height. + * @widget: The widget. + * @width: The requested width. + * @height: The requested height. * - * @return @c TRUE if the new size was confirmed, @c FALSE otherwise. + * Returns: @c TRUE if the new size was confirmed, @c FALSE otherwise. */ gboolean gnt_widget_confirm_size(GntWidget *widget, int width, int height); /** * Trigger the key-press callbacks for a widget. * - * @param widget The widget. - * @param keys The keypress on the widget. + * @widget: The widget. + * @keys: The keypress on the widget. * - * @return @c TRUE if the key-press was handled, @c FALSE otherwise. + * Returns: @c TRUE if the key-press was handled, @c FALSE otherwise. */ gboolean gnt_widget_key_pressed(GntWidget *widget, const char *keys); /** * Trigger the 'click' callback of a widget. * - * @param widget The widget. - * @param event The mouseevent. + * @widget: The widget. + * @event: The mouseevent. * @param x The x-coordinate of the mouse. * @param y The y-coordinate of the mouse. * - * @return @c TRUE if the event was handled, @c FALSE otherwise. + * Returns: @c TRUE if the event was handled, @c FALSE otherwise. */ gboolean gnt_widget_clicked(GntWidget *widget, GntMouseEvent event, int x, int y); /** * Give or remove focus to a widget. - * @param widget The widget. - * @param set @c TRUE of focus should be given to the widget, @c FALSE if + * @widget: The widget. + * @set: @c TRUE of focus should be given to the widget, @c FALSE if * focus should be removed. * - * @return @c TRUE if the focus has been changed, @c FALSE otherwise. + * Returns: @c TRUE if the focus has been changed, @c FALSE otherwise. */ gboolean gnt_widget_set_focus(GntWidget *widget, gboolean set); /** * Activate a widget. This only applies to widgets that can be activated (eg. GntButton) - * @param widget The widget to activate. + * @widget: The widget to activate. */ void gnt_widget_activate(GntWidget *widget); /** * Set the name of a widget. - * @param widget The widget. - * @param name A new name for the widget. + * @widget: The widget. + * @name: A new name for the widget. */ void gnt_widget_set_name(GntWidget *widget, const char *name); /** * Get the name of a widget. - * @param widget The widget. - * @return The name of the widget. + * @widget: The widget. + * Returns: The name of the widget. */ const char *gnt_widget_get_name(GntWidget *widget); @@ -290,25 +290,25 @@ /** * Set whether a widget can take focus or not. * - * @param widget The widget. - * @param set @c TRUE if the widget can take focus. + * @widget: The widget. + * @set: @c TRUE if the widget can take focus. */ void gnt_widget_set_take_focus(GntWidget *widget, gboolean set); /** * Set the visibility of a widget. * - * @param widget The widget. - * @param set Whether the widget is visible or not. + * @widget: The widget. + * @set: Whether the widget is visible or not. */ void gnt_widget_set_visible(GntWidget *widget, gboolean set); /** * Check whether the widget has shadows. * - * @param widget The widget. + * @widget: The widget. * - * @return @c TRUE if the widget has shadows. This checks both the user-setting + * Returns: @c TRUE if the widget has shadows. This checks both the user-setting * and whether the widget can have shadows at all. */ gboolean gnt_widget_has_shadow(GntWidget *widget);
--- a/finch/libgnt/gntwindow.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntwindow.h Wed Jan 29 05:28:33 2014 +0530 @@ -74,7 +74,7 @@ G_BEGIN_DECLS /** - * @return GType for GntWindow. + * Returns: GType for GntWindow. */ GType gnt_window_get_gtype(void); @@ -84,35 +84,35 @@ /** * Create a new window. * - * @return The newly created window. + * Returns: The newly created window. */ GntWidget * gnt_window_new(void); /** * Create a new window. * - * @param homo @c TRUE if the widgets inside the window should have the same dimensions. - * @param vert @c TRUE if the widgets inside the window should be stacked vertically. + * @homo: @c TRUE if the widgets inside the window should have the same dimensions. + * @vert: @c TRUE if the widgets inside the window should be stacked vertically. * - * @return The newly created window. + * Returns: The newly created window. */ GntWidget * gnt_window_box_new(gboolean homo, gboolean vert); /** * Set the menu for a window. * - * @param window The window. - * @param menu The menu for the window. + * @window: The window. + * @menu: The menu for the window. */ void gnt_window_set_menu(GntWindow *window, GntMenu *menu); /** * Return the id of a menuitem specified to a keystroke. * - * @param window The window. - * @param key The keystroke. + * @window: The window. + * @key: The keystroke. * - * @return The id of the menuitem bound to the keystroke, or @c NULL. + * Returns: The id of the menuitem bound to the keystroke, or @c NULL. * * @since 2.3.0 */ @@ -121,8 +121,8 @@ /** * Maximize a window, either horizontally or vertically, or both. * - * @param window The window to maximize. - * @param maximize The maximization state of the window. + * @window: The window to maximize. + * @maximize: The maximization state of the window. * * @since 2.3.0 */ @@ -131,9 +131,9 @@ /** * Get the maximization state of a window. * - * @param window The window. + * @window: The window. * - * @return The maximization state of the window. + * Returns: The maximization state of the window. * * @since 2.3.0 */
--- a/finch/libgnt/gntwm.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntwm.h Wed Jan 29 05:28:33 2014 +0530 @@ -184,118 +184,118 @@ G_BEGIN_DECLS /** - * @return GType for GntWM. + * Returns: GType for GntWM. */ GType gnt_wm_get_gtype(void); /** * Add a workspace. - * @param wm The window-manager. - * @param ws The workspace to add. + * @wm: The window-manager. + * @ws: The workspace to add. */ void gnt_wm_add_workspace(GntWM *wm, GntWS *ws); /** * Switch to a workspace. - * @param wm The window-manager. + * @wm: The window-manager. * @param n Index of the workspace to switch to. * - * @return @c TRUE if the switch was successful. + * Returns: @c TRUE if the switch was successful. */ gboolean gnt_wm_switch_workspace(GntWM *wm, gint n); /** * Switch to the previous workspace from the current one. - * @param wm The window-manager. + * @wm: The window-manager. */ gboolean gnt_wm_switch_workspace_prev(GntWM *wm); /** * Switch to the next workspace from the current one. - * @param wm The window-manager. + * @wm: The window-manager. */ gboolean gnt_wm_switch_workspace_next(GntWM *wm); /** * Move a window to a specific workspace. - * @param wm The window manager. - * @param neww The new workspace. - * @param widget The widget to move. + * @wm: The window manager. + * @neww: The new workspace. + * @widget: The widget to move. */ void gnt_wm_widget_move_workspace(GntWM *wm, GntWS *neww, GntWidget *widget); /** * Set the list of workspaces . - * @param wm The window manager. - * @param workspaces The list of workspaces. + * @wm: The window manager. + * @workspaces: The list of workspaces. */ void gnt_wm_set_workspaces(GntWM *wm, GList *workspaces); /** * Find the workspace that contains a specific widget. - * @param wm The window-manager. - * @param widget The widget to find. - * @return The workspace that has the widget. + * @wm: The window-manager. + * @widget: The widget to find. + * Returns: The workspace that has the widget. */ GntWS *gnt_wm_widget_find_workspace(GntWM *wm, GntWidget *widget); /** * Process a new window. * - * @param wm The window-manager. - * @param widget The new window. + * @wm: The window-manager. + * @widget: The new window. */ void gnt_wm_new_window(GntWM *wm, GntWidget *widget); /** * Decorate a window. - * @param wm The window-manager. - * @param widget The widget to decorate. + * @wm: The window-manager. + * @widget: The widget to decorate. */ void gnt_wm_window_decorate(GntWM *wm, GntWidget *widget); /** * Close a window. - * @param wm The window-manager. - * @param widget The window to close. + * @wm: The window-manager. + * @widget: The window to close. */ void gnt_wm_window_close(GntWM *wm, GntWidget *widget); /** * Process input. * - * @param wm The window-manager. - * @param string The input string to process. + * @wm: The window-manager. + * @string: The input string to process. * - * @return @c TRUE of the string was processed, @c FALSE otherwise. + * Returns: @c TRUE of the string was processed, @c FALSE otherwise. */ gboolean gnt_wm_process_input(GntWM *wm, const char *string); /** * Process a click event. - * @param wm The window manager. - * @param event The mouse event. + * @wm: The window manager. + * @event: The mouse event. * @param x The x-coordinate of the mouse. * @param y The y-coordinate of the mouse. - * @param widget The widget under the mouse. + * @widget: The widget under the mouse. * - * @return @c TRUE if the event was handled, @c FALSE otherwise. + * Returns: @c TRUE if the event was handled, @c FALSE otherwise. */ gboolean gnt_wm_process_click(GntWM *wm, GntMouseEvent event, int x, int y, GntWidget *widget); /** * Resize a window. - * @param wm The window manager. - * @param widget The window to resize. - * @param width The desired width of the window. - * @param height The desired height of the window. + * @wm: The window manager. + * @widget: The window to resize. + * @width: The desired width of the window. + * @height: The desired height of the window. */ void gnt_wm_resize_window(GntWM *wm, GntWidget *widget, int width, int height); /** * Move a window. - * @param wm The window manager. - * @param widget The window to move. + * @wm: The window manager. + * @widget: The window to move. * @param x The desired x-coordinate of the window. * @param y The desired y-coordinate of the window. */ @@ -303,15 +303,15 @@ /** * Update a window. - * @param wm The window-manager. - * @param widget The window to update. + * @wm: The window-manager. + * @widget: The window to update. */ void gnt_wm_update_window(GntWM *wm, GntWidget *widget); /** * Raise a window. - * @param wm The window-manager. - * @param widget The window to raise. + * @wm: The window-manager. + * @widget: The window to raise. */ void gnt_wm_raise_window(GntWM *wm, GntWidget *widget); @@ -326,7 +326,7 @@ void gnt_wm_copy_win(GntWidget *widget, GntNode *node); /** - * @return The idle time of the user. + * Returns: The idle time of the user. */ time_t gnt_wm_get_idle_time(void);
--- a/finch/libgnt/gntws.h Wed Jan 29 00:28:08 2014 +0530 +++ b/finch/libgnt/gntws.h Wed Jan 29 05:28:33 2014 +0530 @@ -70,7 +70,7 @@ G_BEGIN_DECLS /** - * @return The GType for GntWS. + * Returns: The GType for GntWS. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -79,9 +79,9 @@ /** * Create a new workspace with the specified name. * - * @param name The desired name of the workspace, or @c NULL. + * @name: The desired name of the workspace, or @c NULL. * - * @return The newly created workspace. + * Returns: The newly created workspace. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -90,8 +90,8 @@ /** * Set the name of a workspace. * - * @param ws The workspace to rename. - * @param name The new name of the workspace. + * @ws: The workspace to rename. + * @name: The new name of the workspace. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -100,8 +100,8 @@ /** * Add a widget to a workspace. * - * @param ws The workspace. - * @param widget The widget to add. + * @ws: The workspace. + * @widget: The widget to add. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -110,8 +110,8 @@ /** * Remove a widget from a workspace. * - * @param ws The workspace - * @param widget The widget to remove from the workspace. + * @ws: The workspace + * @widget: The widget to remove from the workspace. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -120,8 +120,8 @@ /** * Hide a widget in a workspace. * - * @param widget The widget to hide. - * @param nodes A hashtable containing information about the widgets. + * @widget: The widget to hide. + * @nodes: A hashtable containing information about the widgets. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -130,8 +130,8 @@ /** * Show a widget in a workspace. * - * @param widget The widget to show. - * @param nodes A hashtable containing information about the widgets. + * @widget: The widget to show. + * @nodes: A hashtable containing information about the widgets. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -140,8 +140,8 @@ /** * Draw the taskbar in a workspace. * - * @param ws The workspace. - * @param reposition Whether the workspace should reposition the taskbar. + * @ws: The workspace. + * @reposition: Whether the workspace should reposition the taskbar. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -150,8 +150,8 @@ /** * Hide a workspace. * - * @param ws The workspace to hide. - * @param table A hashtable containing information about the widgets. + * @ws: The workspace to hide. + * @table: A hashtable containing information about the widgets. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -160,8 +160,8 @@ /** * Show a workspace. * - * @param ws The workspace to hide. - * @param table A hashtable containing information about the widgets. + * @ws: The workspace to hide. + * @table: A hashtable containing information about the widgets. * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */ @@ -170,8 +170,8 @@ /** * Get the name of a workspace. * - * @param ws The workspace. - * @return The name of the workspace (can be @c NULL). + * @ws: The workspace. + * Returns: The name of the workspace (can be @c NULL). * * @since 2.0.0 (gnt), 2.1.0 (pidgin) */
--- a/libpurple/account.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/account.h Wed Jan 29 05:28:33 2014 +0530 @@ -132,33 +132,33 @@ /** * Creates a new account. * - * @param username The username. - * @param protocol_id The protocol ID. + * @username: The username. + * @protocol_id: The protocol ID. * - * @return The new account. + * Returns: The new account. */ PurpleAccount *purple_account_new(const char *username, const char *protocol_id); /** * Connects to an account. * - * @param account The account to connect to. + * @account: The account to connect to. */ void purple_account_connect(PurpleAccount *account); /** * Sets the callback for successful registration. * - * @param account The account for which this callback should be used - * @param cb The callback - * @param user_data The user data passed to the callback + * @account: The account for which this callback should be used + * @cb: The callback + * @user_data: The user data passed to the callback */ void purple_account_set_register_callback(PurpleAccount *account, PurpleAccountRegistrationCb cb, void *user_data); /** * Registers an account. * - * @param account The account to register. + * @account: The account to register. */ void purple_account_register(PurpleAccount *account); @@ -166,33 +166,33 @@ * Registration of the account was completed. * Calls the registration call-back set with purple_account_set_register_callback(). * - * @param account The account being registered. - * @param succeeded Was the account registration successful? + * @account: The account being registered. + * @succeeded: Was the account registration successful? */ void purple_account_register_completed(PurpleAccount *account, gboolean succeeded); /** * Unregisters an account (deleting it from the server). * - * @param account The account to unregister. - * @param cb Optional callback to be called when unregistration is complete - * @param user_data user data to pass to the callback + * @account: The account to unregister. + * @cb: Optional callback to be called when unregistration is complete + * @user_data: user data to pass to the callback */ void purple_account_unregister(PurpleAccount *account, PurpleAccountUnregistrationCb cb, void *user_data); /** * Disconnects from an account. * - * @param account The account to disconnect from. + * @account: The account to disconnect from. */ void purple_account_disconnect(PurpleAccount *account); /** * Indicates if the account is currently being disconnected. * - * @param account The account + * @account: The account * - * @return TRUE if the account is being disconnected. + * Returns: TRUE if the account is being disconnected. */ gboolean purple_account_is_disconnecting(const PurpleAccount *account); @@ -203,11 +203,11 @@ * This will present a dialog informing the user that he was added to the * remote user's buddy list. * - * @param account The account that was added. - * @param remote_user The name of the user that added this account. - * @param id The optional ID of the local account. Rarely used. - * @param alias The optional alias of the user. - * @param message The optional message sent from the user adding you. + * @account: The account that was added. + * @remote_user: The name of the user that added this account. + * @id: The optional ID of the local account. Rarely used. + * @alias: The optional alias of the user. + * @message: The optional message sent from the user adding you. */ void purple_account_notify_added(PurpleAccount *account, const char *remote_user, const char *id, const char *alias, @@ -222,11 +222,11 @@ * added them to the remote user's buddy list and will ask if they want to add * the remote user to the buddy list. * - * @param account The account that was added. - * @param remote_user The name of the user that added this account. - * @param id The optional ID of the local account. Rarely used. - * @param alias The optional alias of the user. - * @param message The optional message sent from the user adding you. + * @account: The account that was added. + * @remote_user: The name of the user that added this account. + * @id: The optional ID of the local account. Rarely used. + * @alias: The optional alias of the user. + * @message: The optional message sent from the user adding you. */ void purple_account_request_add(PurpleAccount *account, const char *remote_user, const char *id, const char *alias, @@ -239,17 +239,17 @@ * This will present a dialog informing the user of this and ask if the * user authorizes or denies the remote user from adding him. * - * @param account The account that was added - * @param remote_user The name of the user that added this account. - * @param id The optional ID of the local account. Rarely used. - * @param alias The optional alias of the remote user. - * @param message The optional message sent by the user wanting to add you. - * @param on_list Is the remote user already on the buddy list? - * @param auth_cb The callback called when the local user accepts - * @param deny_cb The callback called when the local user rejects - * @param user_data Data to be passed back to the above callbacks + * @account: The account that was added + * @remote_user: The name of the user that added this account. + * @id: The optional ID of the local account. Rarely used. + * @alias: The optional alias of the remote user. + * @message: The optional message sent by the user wanting to add you. + * @on_list: Is the remote user already on the buddy list? + * @auth_cb: The callback called when the local user accepts + * @deny_cb: The callback called when the local user rejects + * @user_data: Data to be passed back to the above callbacks * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_account_request_authorization(PurpleAccount *account, const char *remote_user, const char *id, const char *alias, const char *message, gboolean on_list, @@ -258,14 +258,14 @@ /** * Close account requests registered for the given PurpleAccount * - * @param account The account for which requests should be closed + * @account: The account for which requests should be closed */ void purple_account_request_close_with_account(PurpleAccount *account); /** * Close the account request for the given ui handle * - * @param ui_handle The ui specific handle for which requests should be closed + * @ui_handle: The ui specific handle for which requests should be closed */ void purple_account_request_close(void *ui_handle); @@ -273,10 +273,10 @@ * Requests a password from the user for the account. Does not set the * account password on success; do that in ok_cb if desired. * - * @param account The account to request the password for. - * @param ok_cb The callback for the OK button. - * @param cancel_cb The callback for the cancel button. - * @param user_data User data to be passed into callbacks. + * @account: The account to request the password for. + * @ok_cb: The callback for the OK button. + * @cancel_cb: The callback for the cancel button. + * @user_data: User data to be passed into callbacks. */ void purple_account_request_password(PurpleAccount *account, GCallback ok_cb, GCallback cancel_cb, void *user_data); @@ -284,7 +284,7 @@ /** * Requests information from the user to change the account's password. * - * @param account The account to change the password on. + * @account: The account to change the password on. */ void purple_account_request_change_password(PurpleAccount *account); @@ -292,15 +292,15 @@ * Requests information from the user to change the account's * user information. * - * @param account The account to change the user information on. + * @account: The account to change the user information on. */ void purple_account_request_change_user_info(PurpleAccount *account); /** * Sets the account's username. * - * @param account The account. - * @param username The username. + * @account: The account. + * @username: The username. */ void purple_account_set_username(PurpleAccount *account, const char *username); @@ -312,10 +312,10 @@ * the callback has been triggered. One can also set a NULL callback if * notification of saving to the keyring is not required. * - * @param account The account. - * @param password The password. - * @param cb A callback for once the password is saved. - * @param data A pointer to be passed to the callback. + * @account: The account. + * @password: The password. + * @cb: A callback for once the password is saved. + * @data: A pointer to be passed to the callback. */ void purple_account_set_password(PurpleAccount *account, const gchar *password, PurpleKeyringSaveCallback cb, gpointer data); @@ -323,32 +323,32 @@ /** * Sets the account's private alias. * - * @param account The account. - * @param alias The alias. + * @account: The account. + * @alias: The alias. */ void purple_account_set_private_alias(PurpleAccount *account, const char *alias); /** * Sets the account's user information * - * @param account The account. - * @param user_info The user information. + * @account: The account. + * @user_info: The user information. */ void purple_account_set_user_info(PurpleAccount *account, const char *user_info); /** * Sets the account's buddy icon path. * - * @param account The account. - * @param path The buddy icon non-cached path. + * @account: The account. + * @path: The buddy icon non-cached path. */ void purple_account_set_buddy_icon_path(PurpleAccount *account, const char *path); /** * Sets the account's protocol ID. * - * @param account The account. - * @param protocol_id The protocol ID. + * @account: The account. + * @protocol_id: The protocol ID. */ void purple_account_set_protocol_id(PurpleAccount *account, const char *protocol_id); @@ -356,24 +356,24 @@ /** * Sets the account's connection. * - * @param account The account. - * @param gc The connection. + * @account: The account. + * @gc: The connection. */ void purple_account_set_connection(PurpleAccount *account, PurpleConnection *gc); /** * Sets whether or not this account should save its password. * - * @param account The account. - * @param value @c TRUE if it should remember the password. + * @account: The account. + * @value: @c TRUE if it should remember the password. */ void purple_account_set_remember_password(PurpleAccount *account, gboolean value); /** * Sets whether or not this account should check for mail. * - * @param account The account. - * @param value @c TRUE if it should check for mail. + * @account: The account. + * @value: @c TRUE if it should check for mail. */ void purple_account_set_check_mail(PurpleAccount *account, gboolean value); @@ -381,9 +381,9 @@ * Sets whether or not this account is enabled for the specified * UI. * - * @param account The account. - * @param ui The UI. - * @param value @c TRUE if it is enabled. + * @account: The account. + * @ui: The UI. + * @value: @c TRUE if it is enabled. */ void purple_account_set_enabled(PurpleAccount *account, const char *ui, gboolean value); @@ -391,24 +391,24 @@ /** * Sets the account's proxy information. * - * @param account The account. - * @param info The proxy information. + * @account: The account. + * @info: The proxy information. */ void purple_account_set_proxy_info(PurpleAccount *account, PurpleProxyInfo *info); /** * Sets the account's privacy type. * - * @param account The account. - * @param privacy_type The privacy type. + * @account: The account. + * @privacy_type: The privacy type. */ void purple_account_set_privacy_type(PurpleAccount *account, PurpleAccountPrivacyType privacy_type); /** * Sets the account's status types. * - * @param account The account. - * @param status_types The list of status types. + * @account: The account. + * @status_types: The list of status types. */ void purple_account_set_status_types(PurpleAccount *account, GList *status_types); @@ -430,11 +430,11 @@ * status. So, if @a status_id is an exclusive status and @a active is @c * FALSE, this function does nothing. * - * @param account The account. - * @param status_id The ID of the status. - * @param active Whether @a status_id is to be activated (<tt>TRUE</tt>) or + * @account: The account. + * @status_id: The ID of the status. + * @active: Whether @a status_id is to be activated (<tt>TRUE</tt>) or * deactivated (<tt>FALSE</tt>). - * @param attrs A list of <tt>const char *</tt> attribute names followed by + * @attrs: A list of <tt>const char *</tt> attribute names followed by * <tt>const char *</tt> attribute values for the status. * (For example, one pair might be <tt>"message"</tt> followed * by <tt>"hello, talk to me!"</tt>.) @@ -449,13 +449,13 @@ * Currently, the public alias is not stored locally, although this * may change in a later version. * - * @param account The account - * @param alias The new public alias for this account or NULL + * @account: The account + * @alias: The new public alias for this account or NULL * to unset the alias/nickname (or return it to * a protocol-specific "default", like the username) - * @param success_cb A callback which will be called if the alias + * @success_cb: A callback which will be called if the alias * is successfully set on the server (or NULL). - * @param failure_cb A callback which will be called if the alias + * @failure_cb: A callback which will be called if the alias * is not successfully set on the server (or NULL). */ void purple_account_set_public_alias(PurpleAccount *account, @@ -466,9 +466,9 @@ * Fetch the server-side (public) alias for this account. The account * must already be connected. * - * @param account The account - * @param success_cb A callback which will be called with the alias - * @param failure_cb A callback which will be called if the protocol is + * @account: The account + * @success_cb: A callback which will be called with the alias + * @failure_cb: A callback which will be called if the protocol is * unable to retrieve the server-side alias. */ void purple_account_get_public_alias(PurpleAccount *account, @@ -478,17 +478,17 @@ /** * Return whether silence suppression is used during voice call. * - * @param account The account. + * @account: The account. * - * @return @c TRUE if suppression is used, or @c FALSE if not. + * Returns: @c TRUE if suppression is used, or @c FALSE if not. */ gboolean purple_account_get_silence_suppression(const PurpleAccount *account); /** * Sets whether silence suppression is used during voice call. * - * @param account The account. - * @param value @c TRUE if suppression should be used. + * @account: The account. + * @value: @c TRUE if suppression should be used. */ void purple_account_set_silence_suppression(PurpleAccount *account, gboolean value); @@ -496,33 +496,33 @@ /** * Clears all protocol-specific settings on an account. * - * @param account The account. + * @account: The account. */ void purple_account_clear_settings(PurpleAccount *account); /** * Removes an account-specific setting by name. * - * @param account The account. - * @param setting The setting to remove. + * @account: The account. + * @setting: The setting to remove. */ void purple_account_remove_setting(PurpleAccount *account, const char *setting); /** * Sets a protocol-specific integer setting for an account. * - * @param account The account. - * @param name The name of the setting. - * @param value The setting's value. + * @account: The account. + * @name: The name of the setting. + * @value: The setting's value. */ void purple_account_set_int(PurpleAccount *account, const char *name, int value); /** * Sets a protocol-specific string setting for an account. * - * @param account The account. - * @param name The name of the setting. - * @param value The setting's value. + * @account: The account. + * @name: The name of the setting. + * @value: The setting's value. */ void purple_account_set_string(PurpleAccount *account, const char *name, const char *value); @@ -530,9 +530,9 @@ /** * Sets a protocol-specific boolean setting for an account. * - * @param account The account. - * @param name The name of the setting. - * @param value The setting's value. + * @account: The account. + * @name: The name of the setting. + * @value: The setting's value. */ void purple_account_set_bool(PurpleAccount *account, const char *name, gboolean value); @@ -540,10 +540,10 @@ /** * Sets a UI-specific integer setting for an account. * - * @param account The account. - * @param ui The UI name. - * @param name The name of the setting. - * @param value The setting's value. + * @account: The account. + * @ui: The UI name. + * @name: The name of the setting. + * @value: The setting's value. */ void purple_account_set_ui_int(PurpleAccount *account, const char *ui, const char *name, int value); @@ -551,10 +551,10 @@ /** * Sets a UI-specific string setting for an account. * - * @param account The account. - * @param ui The UI name. - * @param name The name of the setting. - * @param value The setting's value. + * @account: The account. + * @ui: The UI name. + * @name: The name of the setting. + * @value: The setting's value. */ void purple_account_set_ui_string(PurpleAccount *account, const char *ui, const char *name, const char *value); @@ -562,10 +562,10 @@ /** * Sets a UI-specific boolean setting for an account. * - * @param account The account. - * @param ui The UI name. - * @param name The name of the setting. - * @param value The setting's value. + * @account: The account. + * @ui: The UI name. + * @name: The name of the setting. + * @value: The setting's value. */ void purple_account_set_ui_bool(PurpleAccount *account, const char *ui, const char *name, gboolean value); @@ -573,17 +573,17 @@ /** * Set the UI data associated with this account. * - * @param account The account. - * @param ui_data A pointer to associate with this object. + * @account: The account. + * @ui_data: A pointer to associate with this object. */ void purple_account_set_ui_data(PurpleAccount *account, gpointer ui_data); /** * Returns the UI data associated with this account. * - * @param account The account. + * @account: The account. * - * @return The UI data associated with this account. This is a + * Returns: The UI data associated with this account. This is a * convenience field provided to the UIs--it is not * used by the libpurple core. */ @@ -592,36 +592,36 @@ /** * Returns whether or not the account is connected. * - * @param account The account. + * @account: The account. * - * @return @c TRUE if connected, or @c FALSE otherwise. + * Returns: @c TRUE if connected, or @c FALSE otherwise. */ gboolean purple_account_is_connected(const PurpleAccount *account); /** * Returns whether or not the account is connecting. * - * @param account The account. + * @account: The account. * - * @return @c TRUE if connecting, or @c FALSE otherwise. + * Returns: @c TRUE if connecting, or @c FALSE otherwise. */ gboolean purple_account_is_connecting(const PurpleAccount *account); /** * Returns whether or not the account is disconnected. * - * @param account The account. + * @account: The account. * - * @return @c TRUE if disconnected, or @c FALSE otherwise. + * Returns: @c TRUE if disconnected, or @c FALSE otherwise. */ gboolean purple_account_is_disconnected(const PurpleAccount *account); /** * Returns the account's username. * - * @param account The account. + * @account: The account. * - * @return The username. + * Returns: The username. */ const char *purple_account_get_username(const PurpleAccount *account); @@ -633,9 +633,9 @@ * require the password immediately, then consider using @ref * purple_connection_get_password instead. * - * @param account The account. - * @param cb The callback to give the password. - * @param data A pointer passed to the callback. + * @account: The account. + * @cb: The callback to give the password. + * @data: A pointer passed to the callback. */ void purple_account_get_password(PurpleAccount *account, PurpleKeyringReadCallback cb, gpointer data); @@ -643,54 +643,54 @@ /** * Returns the account's private alias. * - * @param account The account. + * @account: The account. * - * @return The alias. + * Returns: The alias. */ const char *purple_account_get_private_alias(const PurpleAccount *account); /** * Returns the account's user information. * - * @param account The account. + * @account: The account. * - * @return The user information. + * Returns: The user information. */ const char *purple_account_get_user_info(const PurpleAccount *account); /** * Gets the account's buddy icon path. * - * @param account The account. + * @account: The account. * - * @return The buddy icon's non-cached path. + * Returns: The buddy icon's non-cached path. */ const char *purple_account_get_buddy_icon_path(const PurpleAccount *account); /** * Returns the account's protocol ID. * - * @param account The account. + * @account: The account. * - * @return The protocol ID. + * Returns: The protocol ID. */ const char *purple_account_get_protocol_id(const PurpleAccount *account); /** * Returns the account's protocol name. * - * @param account The account. + * @account: The account. * - * @return The protocol name. + * Returns: The protocol name. */ const char *purple_account_get_protocol_name(const PurpleAccount *account); /** * Returns the account's connection. * - * @param account The account. + * @account: The account. * - * @return The connection. + * Returns: The connection. */ PurpleConnection *purple_account_get_connection(const PurpleAccount *account); @@ -700,27 +700,27 @@ * the account exists on its own buddy list); the connection's display name; * the account's username. * - * @param account The account. + * @account: The account. * - * @return The name to display. + * Returns: The name to display. */ const gchar *purple_account_get_name_for_display(const PurpleAccount *account); /** * Returns whether or not this account should save its password. * - * @param account The account. + * @account: The account. * - * @return @c TRUE if it should remember the password. + * Returns: @c TRUE if it should remember the password. */ gboolean purple_account_get_remember_password(const PurpleAccount *account); /** * Returns whether or not this account should check for mail. * - * @param account The account. + * @account: The account. * - * @return @c TRUE if it should check for mail. + * Returns: @c TRUE if it should check for mail. */ gboolean purple_account_get_check_mail(const PurpleAccount *account); @@ -728,10 +728,10 @@ * Returns whether or not this account is enabled for the * specified UI. * - * @param account The account. - * @param ui The UI. + * @account: The account. + * @ui: The UI. * - * @return @c TRUE if it enabled on this UI. + * Returns: @c TRUE if it enabled on this UI. */ gboolean purple_account_get_enabled(const PurpleAccount *account, const char *ui); @@ -739,30 +739,30 @@ /** * Returns the account's proxy information. * - * @param account The account. + * @account: The account. * - * @return The proxy information. + * Returns: The proxy information. */ PurpleProxyInfo *purple_account_get_proxy_info(const PurpleAccount *account); /** * Returns the account's privacy type. * - * @param account The account. + * @account: The account. * - * @return The privacy type. + * Returns: The privacy type. */ PurpleAccountPrivacyType purple_account_get_privacy_type(const PurpleAccount *account); /** * Adds a user to the account's permit list. * - * @param account The account. - * @param name The name of the user to add to the list. - * @param local_only If TRUE, only the local list is updated, and not + * @account: The account. + * @name: The name of the user to add to the list. + * @local_only: If TRUE, only the local list is updated, and not * the server. * - * @return TRUE if the user was added successfully, or @c FALSE otherwise. + * Returns: TRUE if the user was added successfully, or @c FALSE otherwise. */ gboolean purple_account_privacy_permit_add(PurpleAccount *account, const char *name, gboolean local_only); @@ -770,12 +770,12 @@ /** * Removes a user from the account's permit list. * - * @param account The account. - * @param name The name of the user to add to the list. - * @param local_only If TRUE, only the local list is updated, and not + * @account: The account. + * @name: The name of the user to add to the list. + * @local_only: If TRUE, only the local list is updated, and not * the server. * - * @return TRUE if the user was removed successfully, or @c FALSE otherwise. + * Returns: TRUE if the user was removed successfully, or @c FALSE otherwise. */ gboolean purple_account_privacy_permit_remove(PurpleAccount *account, const char *name, gboolean local_only); @@ -783,12 +783,12 @@ /** * Adds a user to the account's deny list. * - * @param account The account. - * @param name The name of the user to add to the list. - * @param local_only If TRUE, only the local list is updated, and not + * @account: The account. + * @name: The name of the user to add to the list. + * @local_only: If TRUE, only the local list is updated, and not * the server. * - * @return TRUE if the user was added successfully, or @c FALSE otherwise. + * Returns: TRUE if the user was added successfully, or @c FALSE otherwise. */ gboolean purple_account_privacy_deny_add(PurpleAccount *account, const char *name, gboolean local_only); @@ -796,12 +796,12 @@ /** * Removes a user from the account's deny list. * - * @param account The account. - * @param name The name of the user to add to the list. - * @param local_only If TRUE, only the local list is updated, and not + * @account: The account. + * @name: The name of the user to add to the list. + * @local_only: If TRUE, only the local list is updated, and not * the server. * - * @return TRUE if the user was removed successfully, or @c FALSE otherwise. + * Returns: TRUE if the user was removed successfully, or @c FALSE otherwise. */ gboolean purple_account_privacy_deny_remove(PurpleAccount *account, const char *name, gboolean local_only); @@ -825,8 +825,8 @@ * The changes are reflected on the server. The previous allow/deny list is not * restored if the privacy setting is changed. * - * @param account The account. - * @param who The name of the user. + * @account: The account. + * @who: The name of the user. */ void purple_account_privacy_allow(PurpleAccount *account, const char *who); @@ -849,34 +849,34 @@ * The changes are reflected on the server. The previous allow/deny list is not * restored if the privacy setting is changed. * - * @param account The account. - * @param who The name of the user. + * @account: The account. + * @who: The name of the user. */ void purple_account_privacy_deny(PurpleAccount *account, const char *who); /** * Returns the account's permit list. * - * @param account The account. - * @constreturn A list of the permitted users + * @account: The account. + * Returns: (TODO const): A list of the permitted users */ GSList *purple_account_privacy_get_permitted(PurpleAccount *account); /** * Returns the account's deny list. * - * @param account The account. - * @constreturn A list of the denied users + * @account: The account. + * Returns: (TODO const): A list of the denied users */ GSList *purple_account_privacy_get_denied(PurpleAccount *account); /** * Check the privacy-setting for a user. * - * @param account The account. - * @param who The name of the user. + * @account: The account. + * @who: The name of the user. * - * @return @c FALSE if the specified account's privacy settings block the user + * Returns: @c FALSE if the specified account's privacy settings block the user * or @c TRUE otherwise. The meaning of "block" is protocol-dependent and * generally relates to status and/or sending of messages. */ @@ -888,9 +888,9 @@ * PurpleStatus that has its active flag set to "TRUE." There can be * only one active PurpleStatus in a PurplePresence. * - * @param account The account. + * @account: The account. * - * @return The active status. + * Returns: The active status. */ PurpleStatus *purple_account_get_active_status(const PurpleAccount *account); @@ -900,10 +900,10 @@ * Note that this works differently than purple_buddy_get_status() in that * it will only return NULL if the status was not registered. * - * @param account The account. - * @param status_id The status ID. + * @account: The account. + * @status_id: The status ID. * - * @return The status, or NULL if it was never registered. + * Returns: The status, or NULL if it was never registered. */ PurpleStatus *purple_account_get_status(const PurpleAccount *account, const char *status_id); @@ -911,10 +911,10 @@ /** * Returns the account status type with the specified ID. * - * @param account The account. - * @param id The ID of the status type to find. + * @account: The account. + * @id: The ID of the status type to find. * - * @return The status type if found, or NULL. + * Returns: The status type if found, or NULL. */ PurpleStatusType *purple_account_get_status_type(const PurpleAccount *account, const char *id); @@ -925,10 +925,10 @@ * PurpleStatusType with the same primitive. In this case, the * first PurpleStatusType is returned. * - * @param account The account. - * @param primitive The type of the status type to find. + * @account: The account. + * @primitive: The type of the status type to find. * - * @return The status if found, or NULL. + * Returns: The status if found, or NULL. */ PurpleStatusType *purple_account_get_status_type_with_primitive( const PurpleAccount *account, @@ -937,19 +937,19 @@ /** * Returns the account's presence. * - * @param account The account. + * @account: The account. * - * @return The account's presence. + * Returns: The account's presence. */ PurplePresence *purple_account_get_presence(const PurpleAccount *account); /** * Returns whether or not an account status is active. * - * @param account The account. - * @param status_id The status ID. + * @account: The account. + * @status_id: The status ID. * - * @return TRUE if active, or FALSE if not. + * Returns: TRUE if active, or FALSE if not. */ gboolean purple_account_is_status_active(const PurpleAccount *account, const char *status_id); @@ -957,20 +957,20 @@ /** * Returns the account's status types. * - * @param account The account. + * @account: The account. * - * @constreturn The account's status types. + * Returns: (TODO const): The account's status types. */ GList *purple_account_get_status_types(const PurpleAccount *account); /** * Returns a protocol-specific integer setting for an account. * - * @param account The account. - * @param name The name of the setting. - * @param default_value The default value. + * @account: The account. + * @name: The name of the setting. + * @default_value: The default value. * - * @return The value. + * Returns: The value. */ int purple_account_get_int(const PurpleAccount *account, const char *name, int default_value); @@ -978,11 +978,11 @@ /** * Returns a protocol-specific string setting for an account. * - * @param account The account. - * @param name The name of the setting. - * @param default_value The default value. + * @account: The account. + * @name: The name of the setting. + * @default_value: The default value. * - * @return The value. + * Returns: The value. */ const char *purple_account_get_string(const PurpleAccount *account, const char *name, @@ -991,11 +991,11 @@ /** * Returns a protocol-specific boolean setting for an account. * - * @param account The account. - * @param name The name of the setting. - * @param default_value The default value. + * @account: The account. + * @name: The name of the setting. + * @default_value: The default value. * - * @return The value. + * Returns: The value. */ gboolean purple_account_get_bool(const PurpleAccount *account, const char *name, gboolean default_value); @@ -1003,12 +1003,12 @@ /** * Returns a UI-specific integer setting for an account. * - * @param account The account. - * @param ui The UI name. - * @param name The name of the setting. - * @param default_value The default value. + * @account: The account. + * @ui: The UI name. + * @name: The name of the setting. + * @default_value: The default value. * - * @return The value. + * Returns: The value. */ int purple_account_get_ui_int(const PurpleAccount *account, const char *ui, const char *name, int default_value); @@ -1016,12 +1016,12 @@ /** * Returns a UI-specific string setting for an account. * - * @param account The account. - * @param ui The UI name. - * @param name The name of the setting. - * @param default_value The default value. + * @account: The account. + * @ui: The UI name. + * @name: The name of the setting. + * @default_value: The default value. * - * @return The value. + * Returns: The value. */ const char *purple_account_get_ui_string(const PurpleAccount *account, const char *ui, const char *name, @@ -1030,12 +1030,12 @@ /** * Returns a UI-specific boolean setting for an account. * - * @param account The account. - * @param ui The UI name. - * @param name The name of the setting. - * @param default_value The default value. + * @account: The account. + * @ui: The UI name. + * @name: The name of the setting. + * @default_value: The default value. * - * @return The value. + * Returns: The value. */ gboolean purple_account_get_ui_bool(const PurpleAccount *account, const char *ui, const char *name, gboolean default_value); @@ -1044,10 +1044,10 @@ /** * Returns the system log for an account. * - * @param account The account. - * @param create Should it be created if it doesn't exist? + * @account: The account. + * @create: Should it be created if it doesn't exist? * - * @return The log. + * Returns: The log. * * @note Callers should almost always pass @c FALSE for @a create. * Passing @c TRUE could result in an existing log being reopened, @@ -1059,34 +1059,34 @@ /** * Frees the system log of an account * - * @param account The account. + * @account: The account. */ void purple_account_destroy_log(PurpleAccount *account); /** * Adds a buddy to the server-side buddy list for the specified account. * - * @param account The account. - * @param buddy The buddy to add. - * @param message The invite message. This may be ignored by a protocol. + * @account: The account. + * @buddy: The buddy to add. + * @message: The invite message. This may be ignored by a protocol. */ void purple_account_add_buddy(PurpleAccount *account, PurpleBuddy *buddy, const char *message); /** * Adds a list of buddies to the server-side buddy list. * - * @param account The account. - * @param buddies The list of PurpleBlistNodes representing the buddies to add. - * @param message The invite message. This may be ignored by a protocol. + * @account: The account. + * @buddies: The list of PurpleBlistNodes representing the buddies to add. + * @message: The invite message. This may be ignored by a protocol. */ void purple_account_add_buddies(PurpleAccount *account, GList *buddies, const char *message); /** * Removes a buddy from the server-side buddy list. * - * @param account The account. - * @param buddy The buddy to remove. - * @param group The group to remove the buddy from. + * @account: The account. + * @buddy: The buddy to remove. + * @group: The group to remove the buddy from. */ void purple_account_remove_buddy(PurpleAccount *account, PurpleBuddy *buddy, PurpleGroup *group); @@ -1097,9 +1097,9 @@ * @note The lists buddies and groups are parallel lists. Be sure that node n of * groups matches node n of buddies. * - * @param account The account. - * @param buddies The list of buddies to remove. - * @param groups The list of groups to remove buddies from. Each node of this + * @account: The account. + * @buddies: The list of buddies to remove. + * @groups: The list of groups to remove buddies from. Each node of this * list should match the corresponding node of buddies. */ void purple_account_remove_buddies(PurpleAccount *account, GList *buddies, @@ -1108,17 +1108,17 @@ /** * Removes a group from the server-side buddy list. * - * @param account The account. - * @param group The group to remove. + * @account: The account. + * @group: The group to remove. */ void purple_account_remove_group(PurpleAccount *account, PurpleGroup *group); /** * Changes the password on the specified account. * - * @param account The account. - * @param orig_pw The old password. - * @param new_pw The new password. + * @account: The account. + * @orig_pw: The old password. + * @new_pw: The new password. */ void purple_account_change_password(PurpleAccount *account, const char *orig_pw, const char *new_pw); @@ -1126,8 +1126,8 @@ /** * Whether the account supports sending offline messages to buddy. * - * @param account The account - * @param buddy The buddy + * @account: The account + * @buddy: The buddy */ gboolean purple_account_supports_offline_message(PurpleAccount *account, PurpleBuddy *buddy); @@ -1135,8 +1135,8 @@ * Get the error that caused the account to be disconnected, or @c NULL if the * account is happily connected or disconnected without an error. * - * @param account The account whose error should be retrieved. - * @constreturn The type of error and a human-readable description of the + * @account: The account whose error should be retrieved. + * Returns: (TODO const): The type of error and a human-readable description of the * current error, or @c NULL if there is no current error. This * pointer is guaranteed to remain valid until the @ref * account-error-changed signal is emitted for @a account. @@ -1146,7 +1146,7 @@ /** * Clear an account's current error state, resetting it to @c NULL. * - * @param account The account whose error state should be cleared. + * @account: The account whose error state should be cleared. */ void purple_account_clear_current_error(PurpleAccount *account);
--- a/libpurple/accountopt.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/accountopt.h Wed Jan 29 05:28:33 2014 +0530 @@ -50,11 +50,11 @@ * purple_account_option_int_new(), purple_account_option_string_new() or * purple_account_option_list_new() (as appropriate) instead. * - * @param type The type of option. - * @param text The text of the option. - * @param pref_name The account preference name for the option. + * @type: The type of option. + * @text: The text of the option. + * @pref_name: The account preference name for the option. * - * @return The account option. + * Returns: The account option. */ PurpleAccountOption *purple_account_option_new(PurplePrefType type, const char *text, const char *pref_name); @@ -62,11 +62,11 @@ /** * Creates a new boolean account option. * - * @param text The text of the option. - * @param pref_name The account preference name for the option. - * @param default_value The default value. + * @text: The text of the option. + * @pref_name: The account preference name for the option. + * @default_value: The default value. * - * @return The account option. + * Returns: The account option. */ PurpleAccountOption *purple_account_option_bool_new(const char *text, const char *pref_name, gboolean default_value); @@ -74,11 +74,11 @@ /** * Creates a new integer account option. * - * @param text The text of the option. - * @param pref_name The account preference name for the option. - * @param default_value The default value. + * @text: The text of the option. + * @pref_name: The account preference name for the option. + * @default_value: The default value. * - * @return The account option. + * Returns: The account option. */ PurpleAccountOption *purple_account_option_int_new(const char *text, const char *pref_name, int default_value); @@ -86,11 +86,11 @@ /** * Creates a new string account option. * - * @param text The text of the option. - * @param pref_name The account preference name for the option. - * @param default_value The default value. + * @text: The text of the option. + * @pref_name: The account preference name for the option. + * @default_value: The default value. * - * @return The account option. + * Returns: The account option. */ PurpleAccountOption *purple_account_option_string_new(const char *text, const char *pref_name, const char *default_value); @@ -106,11 +106,11 @@ * the internal ID that should be passed to purple_account_set_string() to * choose that value. * - * @param text The text of the option. - * @param pref_name The account preference name for the option. - * @param list The key, value list. + * @text: The text of the option. + * @pref_name: The account preference name for the option. + * @list: The key, value list. * - * @return The account option. + * Returns: The account option. */ PurpleAccountOption *purple_account_option_list_new(const char *text, const char *pref_name, GList *list); @@ -118,15 +118,15 @@ /** * Destroys an account option. * - * @param option The option to destroy. + * @option: The option to destroy. */ void purple_account_option_destroy(PurpleAccountOption *option); /** * Sets the default boolean value for an account option. * - * @param option The account option. - * @param value The default boolean value. + * @option: The account option. + * @value: The default boolean value. */ void purple_account_option_set_default_bool(PurpleAccountOption *option, gboolean value); @@ -134,8 +134,8 @@ /** * Sets the default integer value for an account option. * - * @param option The account option. - * @param value The default integer value. + * @option: The account option. + * @value: The default integer value. */ void purple_account_option_set_default_int(PurpleAccountOption *option, int value); @@ -143,8 +143,8 @@ /** * Sets the default string value for an account option. * - * @param option The account option. - * @param value The default string value. + * @option: The account option. + * @value: The default string value. */ void purple_account_option_set_default_string(PurpleAccountOption *option, const char *value); @@ -154,8 +154,8 @@ * as a hint to the UI that the option's value should be obscured from * view, like a password. * - * @param option The account option. - * @param masked The masking. + * @option: The account option. + * @masked: The masking. */ void purple_account_option_string_set_masked(PurpleAccountOption *option, gboolean masked); @@ -166,8 +166,8 @@ * The list passed will be owned by the account option, and the * strings inside will be freed automatically. * - * @param option The account option. - * @param hints The list of hints, stored as strings. + * @option: The account option. + * @hints: The list of hints, stored as strings. */ void purple_account_option_string_set_hints(PurpleAccountOption *option, GSList *hints); @@ -181,17 +181,17 @@ * The list is in key, value pairs. The key is the ID stored and used * internally, and the value is the label displayed. * - * @param option The account option. - * @param values The default list value. + * @option: The account option. + * @values: The default list value. */ void purple_account_option_set_list(PurpleAccountOption *option, GList *values); /** * Adds an item to a list account option. * - * @param option The account option. - * @param key The key. - * @param value The value. + * @option: The account option. + * @key: The key. + * @value: The value. */ void purple_account_option_add_list_item(PurpleAccountOption *option, const char *key, const char *value); @@ -199,18 +199,18 @@ /** * Returns the specified account option's type. * - * @param option The account option. + * @option: The account option. * - * @return The account option's type. + * Returns: The account option's type. */ PurplePrefType purple_account_option_get_type(const PurpleAccountOption *option); /** * Returns the text for an account option. * - * @param option The account option. + * @option: The account option. * - * @return The account option's text. + * Returns: The account option's text. */ const char *purple_account_option_get_text(const PurpleAccountOption *option); @@ -219,36 +219,36 @@ * parameter supplied to purple_account_option_new() or one of the * type-specific constructors. * - * @param option The account option. + * @option: The account option. * - * @return The option's name. + * Returns: The option's name. */ const char *purple_account_option_get_setting(const PurpleAccountOption *option); /** * Returns the default boolean value for an account option. * - * @param option The account option. + * @option: The account option. * - * @return The default boolean value. + * Returns: The default boolean value. */ gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option); /** * Returns the default integer value for an account option. * - * @param option The account option. + * @option: The account option. * - * @return The default integer value. + * Returns: The default integer value. */ int purple_account_option_get_default_int(const PurpleAccountOption *option); /** * Returns the default string value for an account option. * - * @param option The account option. + * @option: The account option. * - * @return The default string value. + * Returns: The default string value. */ const char *purple_account_option_get_default_string( const PurpleAccountOption *option); @@ -256,9 +256,9 @@ /** * Returns the default string value for a list account option. * - * @param option The account option. + * @option: The account option. * - * @return The default list string value. + * Returns: The default list string value. */ const char *purple_account_option_get_default_list_value( const PurpleAccountOption *option); @@ -268,9 +268,9 @@ * password. If so, the UI might display each character of the option * as a '*' (for example). * - * @param option The account option. + * @option: The account option. * - * @return %TRUE if the option's value should be obscured. + * Returns: %TRUE if the option's value should be obscured. */ gboolean purple_account_option_string_get_masked(const PurpleAccountOption *option); @@ -278,18 +278,18 @@ /** * Returns the list of hints for an account option. * - * @param option The account option. + * @option: The account option. * - * @constreturn A list of hints, stored as strings. + * Returns: (TODO const): A list of hints, stored as strings. */ const GSList * purple_account_option_string_get_hints(const PurpleAccountOption *option); /** * Returns the list values for an account option. * - * @param option The account option. + * @option: The account option. * - * @constreturn A list of #PurpleKeyValuePair, mapping the human-readable + * Returns: (TODO const): A list of #PurpleKeyValuePair, mapping the human-readable * description of the value to the <tt>(const char *)</tt> that * should be passed to purple_account_set_string() to set the * option. @@ -307,11 +307,11 @@ /** * Creates a new account username split. * - * @param text The text of the option. - * @param default_value The default value. - * @param sep The field separator. + * @text: The text of the option. + * @default_value: The default value. + * @sep: The field separator. * - * @return The new user split. + * Returns: The new user split. */ PurpleAccountUserSplit *purple_account_user_split_new(const char *text, const char *default_value, @@ -320,25 +320,25 @@ /** * Destroys an account username split. * - * @param split The split to destroy. + * @split: The split to destroy. */ void purple_account_user_split_destroy(PurpleAccountUserSplit *split); /** * Returns the text for an account username split. * - * @param split The account username split. + * @split: The account username split. * - * @return The account username split's text. + * Returns: The account username split's text. */ const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split); /** * Returns the default string value for an account split. * - * @param split The account username split. + * @split: The account username split. * - * @return The default string. + * Returns: The default string. */ const char *purple_account_user_split_get_default_value( const PurpleAccountUserSplit *split); @@ -346,26 +346,26 @@ /** * Returns the field separator for an account split. * - * @param split The account username split. + * @split: The account username split. * - * @return The field separator. + * Returns: The field separator. */ char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split); /** * Returns the 'reverse' value for an account split. * - * @param split The account username split. + * @split: The account username split. * - * @return The 'reverse' value. + * Returns: The 'reverse' value. */ gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split); /** * Sets the 'reverse' value for an account split. * - * @param split The account username split. - * @param reverse The 'reverse' value + * @split: The account username split. + * @reverse: The 'reverse' value */ void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse);
--- a/libpurple/accounts.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/accounts.h Wed Jan 29 05:28:33 2014 +0530 @@ -62,7 +62,7 @@ * list. To authorize them to see this account's presence, call \a * authorize_cb (\a message, \a user_data); otherwise call * \a deny_cb (\a message, \a user_data); - * @return a UI-specific handle, as passed to #close_account_request. + * Returns: a UI-specific handle, as passed to #close_account_request. */ void *(*request_authorize)(PurpleAccount *account, const char *remote_user, @@ -101,14 +101,14 @@ /** * Adds an account to the list of accounts. * - * @param account The account. + * @account: The account. */ void purple_accounts_add(PurpleAccount *account); /** * Removes an account from the list of accounts. * - * @param account The account. + * @account: The account. */ void purple_accounts_remove(PurpleAccount *account); @@ -119,29 +119,29 @@ * account, buddy pounces that belong to this account, and will also * destroy @a account. * - * @param account The account. + * @account: The account. */ void purple_accounts_delete(PurpleAccount *account); /** * Reorders an account. * - * @param account The account to reorder. - * @param new_index The new index for the account. + * @account: The account to reorder. + * @new_index: The new index for the account. */ void purple_accounts_reorder(PurpleAccount *account, guint new_index); /** * Returns a list of all accounts. * - * @constreturn A list of all accounts. + * Returns: (TODO const): A list of all accounts. */ GList *purple_accounts_get_all(void); /** * Returns a list of all enabled accounts * - * @return A list of all enabled accounts. The list is owned + * Returns: A list of all enabled accounts. The list is owned * by the caller, and must be g_list_free()d to avoid * leaking the nodes. */ @@ -150,10 +150,10 @@ /** * Finds an account with the specified name and protocol id. * - * @param name The account username. - * @param protocol The account protocol ID. + * @name: The account username. + * @protocol: The account protocol ID. * - * @return The account, if found, or @c FALSE otherwise. + * Returns: The account, if found, or @c FALSE otherwise. */ PurpleAccount *purple_accounts_find(const char *name, const char *protocol); @@ -178,14 +178,14 @@ /** * Sets the UI operations structure to be used for accounts. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_accounts_set_ui_ops(PurpleAccountUiOps *ops); /** * Returns the UI operations structure used for accounts. * - * @return The UI operations structure in use. + * Returns: The UI operations structure in use. */ PurpleAccountUiOps *purple_accounts_get_ui_ops(void); @@ -200,7 +200,7 @@ /** * Returns the accounts subsystem handle. * - * @return The accounts subsystem handle. + * Returns: The accounts subsystem handle. */ void *purple_accounts_get_handle(void);
--- a/libpurple/blistnode.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/blistnode.h Wed Jan 29 05:28:33 2014 +0530 @@ -129,9 +129,9 @@ * Returns the next node of a given node. This function is to be used to iterate * over the tree returned by purple_blist_get_buddy_list. * - * @param node A node. - * @param offline Whether to include nodes for offline accounts - * @return The next node + * @node: A node. + * @offline: Whether to include nodes for offline accounts + * Returns: The next node * @see purple_blist_node_get_parent * @see purple_blist_node_get_first_child * @see purple_blist_node_get_sibling_next @@ -142,8 +142,8 @@ /** * Returns the parent node of a given node. * - * @param node A node. - * @return The parent node. + * @node: A node. + * Returns: The parent node. * * @see purple_blist_node_get_first_child * @see purple_blist_node_get_sibling_next @@ -155,8 +155,8 @@ /** * Returns the the first child node of a given node. * - * @param node A node. - * @return The child node. + * @node: A node. + * Returns: The child node. * * @see purple_blist_node_get_parent * @see purple_blist_node_get_sibling_next @@ -168,8 +168,8 @@ /** * Returns the sibling node of a given node. * - * @param node A node. - * @return The sibling node. + * @node: A node. + * Returns: The sibling node. * * @see purple_blist_node_get_parent * @see purple_blist_node_get_first_child @@ -181,8 +181,8 @@ /** * Returns the previous sibling node of a given node. * - * @param node A node. - * @return The sibling node. + * @node: A node. + * Returns: The sibling node. * * @see purple_blist_node_get_parent * @see purple_blist_node_get_first_child @@ -194,82 +194,82 @@ /** * Returns the UI data of a given node. * - * @param node The node. - * @return The UI data. + * @node: The node. + * Returns: The UI data. */ gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node); /** * Sets the UI data of a given node. * - * @param node The node. - * @param ui_data The UI data. + * @node: The node. + * @ui_data: The UI data. */ void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data); /** * Returns a node's settings * - * @param node The node to from which to get settings + * @node: The node to from which to get settings * - * @return The hash table with the node's settings + * Returns: The hash table with the node's settings */ GHashTable *purple_blist_node_get_settings(PurpleBlistNode *node); /** * Checks whether a named setting exists for a node in the buddy list * - * @param node The node to check from which to check settings - * @param key The identifier of the data + * @node: The node to check from which to check settings + * @key: The identifier of the data * - * @return TRUE if a value exists, or FALSE if there is no setting + * Returns: TRUE if a value exists, or FALSE if there is no setting */ gboolean purple_blist_node_has_setting(PurpleBlistNode *node, const char *key); /** * Associates a boolean with a node in the buddy list * - * @param node The node to associate the data with - * @param key The identifier for the data - * @param value The value to set + * @node: The node to associate the data with + * @key: The identifier for the data + * @value: The value to set */ void purple_blist_node_set_bool(PurpleBlistNode *node, const char *key, gboolean value); /** * Retrieves a named boolean setting from a node in the buddy list * - * @param node The node to retrieve the data from - * @param key The identifier of the data + * @node: The node to retrieve the data from + * @key: The identifier of the data * - * @return The value, or FALSE if there is no setting + * Returns: The value, or FALSE if there is no setting */ gboolean purple_blist_node_get_bool(PurpleBlistNode *node, const char *key); /** * Associates an integer with a node in the buddy list * - * @param node The node to associate the data with - * @param key The identifier for the data - * @param value The value to set + * @node: The node to associate the data with + * @key: The identifier for the data + * @value: The value to set */ void purple_blist_node_set_int(PurpleBlistNode *node, const char *key, int value); /** * Retrieves a named integer setting from a node in the buddy list * - * @param node The node to retrieve the data from - * @param key The identifier of the data + * @node: The node to retrieve the data from + * @key: The identifier of the data * - * @return The value, or 0 if there is no setting + * Returns: The value, or 0 if there is no setting */ int purple_blist_node_get_int(PurpleBlistNode *node, const char *key); /** * Associates a string with a node in the buddy list * - * @param node The node to associate the data with - * @param key The identifier for the data - * @param value The value to set + * @node: The node to associate the data with + * @key: The identifier for the data + * @value: The value to set */ void purple_blist_node_set_string(PurpleBlistNode *node, const char *key, const char *value); @@ -277,26 +277,26 @@ /** * Retrieves a named string setting from a node in the buddy list * - * @param node The node to retrieve the data from - * @param key The identifier of the data + * @node: The node to retrieve the data from + * @key: The identifier of the data * - * @return The value, or NULL if there is no setting + * Returns: The value, or NULL if there is no setting */ const char *purple_blist_node_get_string(PurpleBlistNode *node, const char *key); /** * Removes a named setting from a blist node * - * @param node The node from which to remove the setting - * @param key The name of the setting + * @node: The node from which to remove the setting + * @key: The name of the setting */ void purple_blist_node_remove_setting(PurpleBlistNode *node, const char *key); /** * Sets whether the node should be saved with the buddy list or not * - * @param node The node - * @param transient TRUE if the node should NOT be saved, FALSE if node should + * @node: The node + * @transient: TRUE if the node should NOT be saved, FALSE if node should * be saved */ void purple_blist_node_set_transient(PurpleBlistNode *node, gboolean transient); @@ -304,9 +304,9 @@ /** * Gets whether the node should be saved with the buddy list or not * - * @param node The node + * @node: The node * - * @return TRUE if the node should NOT be saved, FALSE if node should be saved + * Returns: TRUE if the node should NOT be saved, FALSE if node should be saved */ gboolean purple_blist_node_is_transient(PurpleBlistNode *node); @@ -315,7 +315,7 @@ /** * Retrieves the extended menu items for a buddy list node. * @param n The blist node for which to obtain the extended menu items. - * @return A list of PurpleMenuAction items, as harvested by the + * Returns: A list of PurpleMenuAction items, as harvested by the * blist-node-extended-menu signal. */ GList *purple_blist_node_get_extended_menu(PurpleBlistNode *n); @@ -335,9 +335,9 @@ /** * Returns the total number of children of the counting node. * - * @param counter The node + * @counter: The node * - * @return The total number of children of the node + * Returns: The total number of children of the node */ int purple_counting_node_get_total_size(PurpleCountingNode *counter); @@ -345,18 +345,18 @@ * Returns the number of children of the counting node corresponding to online * accounts. * - * @param counter The node + * @counter: The node * - * @return The number of children with online accounts + * Returns: The number of children with online accounts */ int purple_counting_node_get_current_size(PurpleCountingNode *counter); /** * Returns the number of children of the counting node that are online. * - * @param counter The node + * @counter: The node * - * @return The total number of online children + * Returns: The total number of online children */ int purple_counting_node_get_online_count(PurpleCountingNode *counter); @@ -365,8 +365,8 @@ * delta value is added to the count, or if it's negative, the count is * decreased. * - * @param counter The node - * @param delta The value to change the total size by + * @counter: The node + * @delta: The value to change the total size by */ void purple_counting_node_change_total_size(PurpleCountingNode *counter, int delta); @@ -375,8 +375,8 @@ * accounts. The provided delta value is added to the count, or if it's * negative, the count is decreased. * - * @param counter The node - * @param delta The value to change the current size by + * @counter: The node + * @delta: The value to change the current size by */ void purple_counting_node_change_current_size(PurpleCountingNode *counter, int delta); @@ -385,16 +385,16 @@ * provided delta value is added to the count, or if it's negative, the count is * decreased. * - * @param counter The node - * @param delta The value to change the online count by + * @counter: The node + * @delta: The value to change the online count by */ void purple_counting_node_change_online_count(PurpleCountingNode *counter, int delta); /** * Sets the total number of children of the counting node. * - * @param counter The node - * @param totalsize The total number of children of the node + * @counter: The node + * @totalsize: The total number of children of the node */ void purple_counting_node_set_total_size(PurpleCountingNode *counter, int totalsize); @@ -402,16 +402,16 @@ * Sets the number of children of the counting node corresponding to online * accounts. * - * @param counter The node - * @param currentsize The number of children with online accounts + * @counter: The node + * @currentsize: The number of children with online accounts */ void purple_counting_node_set_current_size(PurpleCountingNode *counter, int currentsize); /** * Sets the number of children of the counting node that are online. * - * @param counter The node - * @param onlinecount The total number of online children + * @counter: The node + * @onlinecount: The total number of online children */ void purple_counting_node_set_online_count(PurpleCountingNode *counter, int onlinecount);
--- a/libpurple/blistnodetypes.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/blistnodetypes.h Wed Jan 29 05:28:33 2014 +0530 @@ -194,10 +194,10 @@ * to add the buddy to the list and purple_account_add_buddy to sync up * with the server. * - * @param account The account this buddy will get added to - * @param name The name of the new buddy - * @param alias The alias of the new buddy (or NULL if unaliased) - * @return A newly allocated buddy + * @account: The account this buddy will get added to + * @name: The name of the new buddy + * @alias: The alias of the new buddy (or NULL if unaliased) + * Returns: A newly allocated buddy * * @see purple_account_add_buddy * @see purple_blist_add_buddy @@ -210,8 +210,8 @@ * This should only be called from within Purple. You probably want to * call purple_buddy_icon_set_data(). * - * @param buddy The buddy. - * @param icon The buddy icon. + * @buddy: The buddy. + * @icon: The buddy icon. * * @see purple_buddy_icon_set_data() */ @@ -220,35 +220,35 @@ /** * Returns a buddy's icon. * - * @param buddy The buddy. + * @buddy: The buddy. * - * @return The buddy icon. + * Returns: The buddy icon. */ PurpleBuddyIcon *purple_buddy_get_icon(const PurpleBuddy *buddy); /** * Returns a buddy's account. * - * @param buddy The buddy. + * @buddy: The buddy. * - * @return The account + * Returns: The account */ PurpleAccount *purple_buddy_get_account(const PurpleBuddy *buddy); /** * Sets a buddy's name * - * @param buddy The buddy. - * @param name The name. + * @buddy: The buddy. + * @name: The name. */ void purple_buddy_set_name(PurpleBuddy *buddy, const char *name); /** * Returns a buddy's name * - * @param buddy The buddy. + * @buddy: The buddy. * - * @return The name. + * Returns: The name. */ const char *purple_buddy_get_name(const PurpleBuddy *buddy); @@ -257,8 +257,8 @@ * * This should only be called from the associated protocol. * - * @param buddy The buddy. - * @return The protocol data. + * @buddy: The buddy. + * Returns: The protocol data. * * @see purple_buddy_set_protocol_data() */ @@ -269,8 +269,8 @@ * * This should only be called from the associated protocol. * - * @param buddy The buddy. - * @param data The data. + * @buddy: The buddy. + * @data: The data. * * @see purple_buddy_get_protocol_data() */ @@ -279,18 +279,18 @@ /** * Returns a buddy's contact. * - * @param buddy The buddy. + * @buddy: The buddy. * - * @return The buddy's contact. + * Returns: The buddy's contact. */ PurpleContact *purple_buddy_get_contact(PurpleBuddy *buddy); /** * Returns a buddy's presence. * - * @param buddy The buddy. + * @buddy: The buddy. * - * @return The buddy's presence. + * Returns: The buddy's presence. */ PurplePresence *purple_buddy_get_presence(const PurpleBuddy *buddy); @@ -299,32 +299,32 @@ * * This should only be called from within Purple. * - * @param buddy The buddy whose status has changed. - * @param old_status The status from which we are changing. + * @buddy: The buddy whose status has changed. + * @old_status: The status from which we are changing. */ void purple_buddy_update_status(PurpleBuddy *buddy, PurpleStatus *old_status); /** * Gets the media caps from a buddy. * - * @param buddy The buddy. - * @return The media caps. + * @buddy: The buddy. + * Returns: The media caps. */ PurpleMediaCaps purple_buddy_get_media_caps(const PurpleBuddy *buddy); /** * Sets the media caps for a buddy. * - * @param buddy The PurpleBuddy. - * @param media_caps The PurpleMediaCaps. + * @buddy: The PurpleBuddy. + * @media_caps: The PurpleMediaCaps. */ void purple_buddy_set_media_caps(PurpleBuddy *buddy, PurpleMediaCaps media_caps); /** * Returns the alias of a buddy. * - * @param buddy The buddy whose alias will be returned. - * @return The alias (if set), server alias (if set), + * @buddy: The buddy whose alias will be returned. + * Returns: The alias (if set), server alias (if set), * or NULL. */ const char *purple_buddy_get_alias_only(PurpleBuddy *buddy); @@ -332,16 +332,16 @@ /** * Sets the server alias for a buddy. * - * @param buddy The buddy. - * @param alias The server alias to be set. + * @buddy: The buddy. + * @alias: The server alias to be set. */ void purple_buddy_set_server_alias(PurpleBuddy *buddy, const char *alias); /** * Gets the server alias for a buddy. * - * @param buddy The buddy whose server alias will be returned - * @return The server alias, or NULL if it is not set. + * @buddy: The buddy whose server alias will be returned + * Returns: The server alias, or NULL if it is not set. */ const char *purple_buddy_get_server_alias(PurpleBuddy *buddy); @@ -350,8 +350,8 @@ * into account. In order of precedence: the buddy's alias; the buddy's * contact alias; the buddy's server alias; the buddy's user name. * - * @param buddy The buddy whose alias will be returned - * @return The appropriate name or alias, or NULL. + * @buddy: The buddy whose alias will be returned + * Returns: The appropriate name or alias, or NULL. * */ const char *purple_buddy_get_contact_alias(PurpleBuddy *buddy); @@ -361,32 +361,32 @@ * the buddy's local alias; the buddy's server alias; the buddy's contact alias; * the buddy's user name. * - * @param buddy The buddy whose alias will be returned. - * @return The appropriate name or alias, or NULL + * @buddy: The buddy whose alias will be returned. + * Returns: The appropriate name or alias, or NULL */ const char *purple_buddy_get_alias(PurpleBuddy *buddy); /** * Sets the local alias for the buddy. * - * @param buddy The buddy - * @param alias The local alias for the buddy + * @buddy: The buddy + * @alias: The local alias for the buddy */ void purple_buddy_set_local_alias(PurpleBuddy *buddy, const char *alias); /** * Returns the local alias for the buddy, or @c NULL if none exists. * - * @param buddy The buddy - * @return The local alias for the buddy + * @buddy: The buddy + * Returns: The local alias for the buddy */ const char *purple_buddy_get_local_alias(PurpleBuddy *buddy); /** * Returns the group of which the buddy is a member. * - * @param buddy The buddy - * @return The group or NULL if the buddy is not in a group + * @buddy: The buddy + * Returns: The group or NULL if the buddy is not in a group */ PurpleGroup *purple_buddy_get_group(PurpleBuddy *buddy); @@ -405,49 +405,49 @@ /** * Creates a new contact * - * @return A new contact struct + * Returns: A new contact struct */ PurpleContact *purple_contact_new(void); /** * Gets the PurpleGroup from a PurpleContact * - * @param contact The contact - * @return The group + * @contact: The contact + * Returns: The group */ PurpleGroup *purple_contact_get_group(const PurpleContact *contact); /** * Returns the highest priority buddy for a given contact. * - * @param contact The contact - * @return The highest priority buddy + * @contact: The contact + * Returns: The highest priority buddy */ PurpleBuddy *purple_contact_get_priority_buddy(PurpleContact *contact); /** * Sets the alias for a contact. * - * @param contact The contact - * @param alias The alias + * @contact: The contact + * @alias: The alias */ void purple_contact_set_alias(PurpleContact *contact, const char *alias); /** * Gets the alias for a contact. * - * @param contact The contact - * @return The alias, or NULL if it is not set. + * @contact: The contact + * Returns: The alias, or NULL if it is not set. */ const char *purple_contact_get_alias(PurpleContact *contact); /** * Determines whether an account owns any buddies in a given contact * - * @param contact The contact to search through. - * @param account The account. + * @contact: The contact to search through. + * @account: The account. * - * @return TRUE if there are any buddies from account in the contact, or FALSE otherwise. + * Returns: TRUE if there are any buddies from account in the contact, or FALSE otherwise. */ gboolean purple_contact_on_account(PurpleContact *contact, PurpleAccount *account); @@ -455,7 +455,7 @@ * Invalidates the priority buddy so that the next call to * purple_contact_get_priority_buddy recomputes it. * - * @param contact The contact + * @contact: The contact */ void purple_contact_invalidate_priority_buddy(PurpleContact *contact); @@ -464,8 +464,8 @@ * * All of the buddies from source will be moved to target * - * @param source The contact to merge - * @param node The place to merge to (a buddy or contact) + * @source: The contact to merge + * @node: The place to merge to (a buddy or contact) */ void purple_contact_merge(PurpleContact *source, PurpleBlistNode *node); @@ -484,63 +484,63 @@ /** * Creates a new chat for the buddy list * - * @param account The account this chat will get added to - * @param alias The alias of the new chat - * @param components The info the protocol needs to join the chat. The + * @account: The account this chat will get added to + * @alias: The alias of the new chat + * @components: The info the protocol needs to join the chat. The * hash function should be g_str_hash() and the * equal function should be g_str_equal(). - * @return A newly allocated chat + * Returns: A newly allocated chat */ PurpleChat *purple_chat_new(PurpleAccount *account, const char *alias, GHashTable *components); /** * Returns the correct name to display for a blist chat. * - * @param chat The chat whose name will be returned. - * @return The alias (if set), or first component value. + * @chat: The chat whose name will be returned. + * Returns: The alias (if set), or first component value. */ const char *purple_chat_get_name(PurpleChat *chat); /** * Returns the name of the chat * - * @param chat The chat whose name will be returned. - * @return The first component value. + * @chat: The chat whose name will be returned. + * Returns: The first component value. */ const char *purple_chat_get_name_only(PurpleChat *chat); /** * Sets the alias for a blist chat. * - * @param chat The chat - * @param alias The alias + * @chat: The chat + * @alias: The alias */ void purple_chat_set_alias(PurpleChat *chat, const char *alias); /** * Returns the group of which the chat is a member. * - * @param chat The chat. + * @chat: The chat. * - * @return The parent group, or @c NULL if the chat is not in a group. + * Returns: The parent group, or @c NULL if the chat is not in a group. */ PurpleGroup *purple_chat_get_group(PurpleChat *chat); /** * Returns the account the chat belongs to. * - * @param chat The chat. + * @chat: The chat. * - * @return The account the chat belongs to. + * Returns: The account the chat belongs to. */ PurpleAccount *purple_chat_get_account(PurpleChat *chat); /** * Get a hashtable containing information about a chat. * - * @param chat The chat. + * @chat: The chat. * - * @constreturn The hashtable. + * Returns: (TODO const): The hashtable. */ GHashTable *purple_chat_get_components(PurpleChat *chat); @@ -562,8 +562,8 @@ * You can't have more than one group with the same name. Sorry. If you pass * this the name of a group that already exists, it will return that group. * - * @param name The name of the new group - * @return A new group struct + * @name: The name of the new group + * Returns: A new group struct */ PurpleGroup *purple_group_new(const char *name); @@ -572,7 +572,7 @@ * * @param g The group * - * @return A GSList of accounts (which must be freed), or NULL if the group + * Returns: A GSList of accounts (which must be freed), or NULL if the group * has no accounts. */ GSList *purple_group_get_accounts(PurpleGroup *g); @@ -581,26 +581,26 @@ * Determines whether an account owns any buddies in a given group * * @param g The group to search through. - * @param account The account. + * @account: The account. * - * @return TRUE if there are any buddies in the group, or FALSE otherwise. + * Returns: TRUE if there are any buddies in the group, or FALSE otherwise. */ gboolean purple_group_on_account(PurpleGroup *g, PurpleAccount *account); /** * Sets the name of a group. * - * @param group The group. - * @param name The name of the group. + * @group: The group. + * @name: The name of the group. */ void purple_group_set_name(PurpleGroup *group, const char *name); /** * Returns the name of a group. * - * @param group The group. + * @group: The group. * - * @return The name of the group. + * Returns: The name of the group. */ const char *purple_group_get_name(PurpleGroup *group);
--- a/libpurple/buddyicon.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/buddyicon.h Wed Jan 29 05:28:33 2014 +0530 @@ -86,13 +86,13 @@ * If an icon for this account+username already exists, you'll get a reference * to that structure, which will have been updated with the data supplied. * - * @param account The account the user is on. - * @param username The username the icon belongs to. - * @param icon_data The buddy icon data. - * @param icon_len The buddy icon length. - * @param checksum A protocol checksum from the protocol or @c NULL. + * @account: The account the user is on. + * @username: The username the icon belongs to. + * @icon_data: The buddy icon data. + * @icon_len: The buddy icon length. + * @checksum: A protocol checksum from the protocol or @c NULL. * - * @return The buddy icon structure, with a reference for the caller. + * Returns: The buddy icon structure, with a reference for the caller. */ PurpleBuddyIcon *purple_buddy_icon_new(PurpleAccount *account, const char *username, void *icon_data, size_t icon_len, @@ -101,9 +101,9 @@ /** * Increments the reference count on a buddy icon. * - * @param icon The buddy icon. + * @icon: The buddy icon. * - * @return @a icon. + * Returns: @a icon. */ PurpleBuddyIcon *purple_buddy_icon_ref(PurpleBuddyIcon *icon); @@ -112,25 +112,25 @@ * * If the reference count reaches 0, the icon will be destroyed. * - * @param icon The buddy icon. + * @icon: The buddy icon. */ void purple_buddy_icon_unref(PurpleBuddyIcon *icon); /** * Updates every instance of this icon. * - * @param icon The buddy icon. + * @icon: The buddy icon. */ void purple_buddy_icon_update(PurpleBuddyIcon *icon); /** * Sets the buddy icon's data. * - * @param icon The buddy icon. - * @param data The buddy icon data, which the buddy icon code + * @icon: The buddy icon. + * @data: The buddy icon data, which the buddy icon code * takes ownership of and will free. - * @param len The length of the data in @a data. - * @param checksum A protocol checksum from the protocol or @c NULL. + * @len: The length of the data in @a data. + * @checksum: A protocol checksum from the protocol or @c NULL. */ void purple_buddy_icon_set_data(PurpleBuddyIcon *icon, guchar *data, @@ -139,18 +139,18 @@ /** * Returns the buddy icon's account. * - * @param icon The buddy icon. + * @icon: The buddy icon. * - * @return The account. + * Returns: The account. */ PurpleAccount *purple_buddy_icon_get_account(const PurpleBuddyIcon *icon); /** * Returns the buddy icon's username. * - * @param icon The buddy icon. + * @icon: The buddy icon. * - * @return The username. + * Returns: The username. */ const char *purple_buddy_icon_get_username(const PurpleBuddyIcon *icon); @@ -159,29 +159,29 @@ * * This function is really only for protocol use. * - * @param icon The buddy icon. + * @icon: The buddy icon. * - * @return The checksum. + * Returns: The checksum. */ const char *purple_buddy_icon_get_checksum(const PurpleBuddyIcon *icon); /** * Returns the buddy icon's data. * - * @param icon The buddy icon. - * @param len If not @c NULL, the length of the icon data returned will be + * @icon: The buddy icon. + * @len: If not @c NULL, the length of the icon data returned will be * set in the location pointed to by this. * - * @return A pointer to the icon data. + * Returns: A pointer to the icon data. */ gconstpointer purple_buddy_icon_get_data(const PurpleBuddyIcon *icon, size_t *len); /** * Returns an extension corresponding to the buddy icon's file type. * - * @param icon The buddy icon. + * @icon: The buddy icon. * - * @return The icon's extension, "icon" if unknown, or @c NULL if + * Returns: The icon's extension, "icon" if unknown, or @c NULL if * the image data has disappeared. */ const char *purple_buddy_icon_get_extension(const PurpleBuddyIcon *icon); @@ -196,9 +196,9 @@ * directly. If you find yourself wanting to use this function, think * very long and hard about it, and then don't. * - * @param icon The buddy icon + * @icon: The buddy icon * - * @return A full path to the file, or @c NULL under various conditions. + * Returns: A full path to the file, or @c NULL under various conditions. */ char *purple_buddy_icon_get_full_path(PurpleBuddyIcon *icon); @@ -212,12 +212,12 @@ /** * Sets a buddy icon for a user. * - * @param account The account the user is on. - * @param username The username of the user. - * @param icon_data The buddy icon data, which the buddy icon code + * @account: The account the user is on. + * @username: The username of the user. + * @icon_data: The buddy icon data, which the buddy icon code * takes ownership of and will free. - * @param icon_len The length of the icon data. - * @param checksum A protocol checksum from the protocol or @c NULL. + * @icon_len: The length of the icon data. + * @checksum: A protocol checksum from the protocol or @c NULL. */ void purple_buddy_icons_set_for_user(PurpleAccount *account, const char *username, @@ -230,9 +230,9 @@ * This avoids loading the icon image data from the cache if it's * not already loaded for some other reason. * - * @param buddy The buddy + * @buddy: The buddy * - * @return The checksum. + * Returns: The checksum. */ const char * purple_buddy_icons_get_checksum_for_user(PurpleBuddy *buddy); @@ -240,10 +240,10 @@ /** * Returns the buddy icon information for a user. * - * @param account The account the user is on. - * @param username The username of the user. + * @account: The account the user is on. + * @username: The username of the user. * - * @return The icon (with a reference for the caller) if found, or @c NULL if + * Returns: The icon (with a reference for the caller) if found, or @c NULL if * not found. */ PurpleBuddyIcon * @@ -259,9 +259,9 @@ * needed, so it should be called in any case where you want the * appropriate icon. * - * @param account The account + * @account: The account * - * @return The account's buddy icon image. + * Returns: The account's buddy icon image. */ PurpleStoredImage * purple_buddy_icons_find_account_icon(PurpleAccount *account); @@ -272,12 +272,12 @@ * This function will deal with saving a record of the icon, * caching the data, etc. * - * @param account The account for which to set a custom icon. - * @param icon_data The image data of the icon, which the + * @account: The account for which to set a custom icon. + * @icon_data: The image data of the icon, which the * buddy icon code will free. - * @param icon_len The length of the data in @a icon_data. + * @icon_len: The length of the data in @a icon_data. * - * @return The icon that was set. The caller does NOT own + * Returns: The icon that was set. The caller does NOT own * a reference to this, and must call purple_imgstore_ref() * if it wants one. */ @@ -291,9 +291,9 @@ * This is intended for use in protocols that require a timestamp for * buddy icon update reasons. * - * @param account The account + * @account: The account * - * @return The time the icon was set, or 0 if an error occurred. + * Returns: The time the icon was set, or 0 if an error occurred. */ time_t purple_buddy_icons_get_account_icon_timestamp(PurpleAccount *account); @@ -301,9 +301,9 @@ /** * Returns a boolean indicating if a given blist node has a custom buddy icon. * - * @param node The blist node. + * @node: The blist node. * - * @return A boolean indicating if @a node has a custom buddy icon. + * Returns: A boolean indicating if @a node has a custom buddy icon. */ gboolean purple_buddy_icons_node_has_custom_icon(PurpleBlistNode *node); @@ -318,9 +318,9 @@ * needed, so it should be called in any case where you want the * appropriate icon. * - * @param node The node. + * @node: The node. * - * @return The custom buddy icon. + * Returns: The custom buddy icon. */ PurpleStoredImage * purple_buddy_icons_node_find_custom_icon(PurpleBlistNode *node); @@ -331,12 +331,12 @@ * This function will deal with saving a record of the icon, caching the data, * etc. * - * @param node The blist node for which to set a custom icon. - * @param icon_data The image data of the icon, which the buddy icon code will + * @node: The blist node for which to set a custom icon. + * @icon_data: The image data of the icon, which the buddy icon code will * free. Use NULL to unset the icon. - * @param icon_len The length of the data in @a icon_data. + * @icon_len: The length of the data in @a icon_data. * - * @return The icon that was set. The caller does NOT own a reference to this, + * Returns: The icon that was set. The caller does NOT own a reference to this, * and must call purple_imgstore_ref() if it wants one. */ PurpleStoredImage * @@ -349,11 +349,11 @@ * Convenience wrapper around purple_buddy_icons_node_set_custom_icon. * @see purple_buddy_icons_node_set_custom_icon() * - * @param node The blist node for which to set a custom icon. - * @param filename The path to the icon to set for the blist node. Use NULL + * @node: The blist node for which to set a custom icon. + * @filename: The path to the icon to set for the blist node. Use NULL * to unset the custom icon. * - * @return The icon that was set. The caller does NOT own a reference to this, + * Returns: The icon that was set. The caller does NOT own a reference to this, * and must call purple_imgstore_ref() if it wants one. */ PurpleStoredImage * @@ -363,7 +363,7 @@ /** * Sets whether or not buddy icon caching is enabled. * - * @param caching TRUE if buddy icon caching should be enabled, or + * @caching: TRUE if buddy icon caching should be enabled, or * FALSE otherwise. */ void purple_buddy_icons_set_caching(gboolean caching); @@ -374,14 +374,14 @@ * The default is TRUE, unless otherwise specified by * purple_buddy_icons_set_caching(). * - * @return TRUE if buddy icon caching is enabled, or FALSE otherwise. + * Returns: TRUE if buddy icon caching is enabled, or FALSE otherwise. */ gboolean purple_buddy_icons_is_caching(void); /** * Sets the directory used to store buddy icon cache files. * - * @param cache_dir The directory to store buddy icon cache files to. + * @cache_dir: The directory to store buddy icon cache files to. */ void purple_buddy_icons_set_cache_dir(const char *cache_dir); @@ -391,14 +391,14 @@ * The default directory is PURPLEDIR/icons, unless otherwise specified * by purple_buddy_icons_set_cache_dir(). * - * @return The directory to store buddy icon cache files to. + * Returns: The directory to store buddy icon cache files to. */ const char *purple_buddy_icons_get_cache_dir(void); /** * Returns the buddy icon subsystem handle. * - * @return The subsystem handle. + * Returns: The subsystem handle. */ void *purple_buddy_icons_get_handle(void); @@ -427,16 +427,16 @@ /** * Creates a new #PurpleBuddyIconSpec instance. * - * @param format A comma-delimited list of image formats or @c NULL if + * @format: A comma-delimited list of image formats or @c NULL if * icons are not supported - * @param min_width Minimum width of an icon - * @param min_height Minimum height of an icon - * @param max_width Maximum width of an icon - * @param max_height Maximum height of an icon - * @param max_filesize Maximum file size in bytes - * @param scale_rules How to stretch this icon + * @min_width: Minimum width of an icon + * @min_height: Minimum height of an icon + * @max_width: Maximum width of an icon + * @max_height: Maximum height of an icon + * @max_filesize: Maximum file size in bytes + * @scale_rules: How to stretch this icon * - * @return A new buddy icon spec. + * Returns: A new buddy icon spec. */ PurpleBuddyIconSpec *purple_buddy_icon_spec_new(char *format, int min_width, int min_height, int max_width, int max_height, size_t max_filesize,
--- a/libpurple/buddylist.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/buddylist.h Wed Jan 29 05:28:33 2014 +0530 @@ -106,7 +106,7 @@ * be set to a fallback function that saves data to blist.xml like in * previous libpurple versions. * - * @param node The node which has been modified. + * @node: The node which has been modified. */ void (*save_node)(PurpleBlistNode *node); @@ -119,7 +119,7 @@ * be set to a fallback function that saves data to blist.xml like in * previous libpurple versions. * - * @param node The node which has been modified. + * @node: The node which has been modified. */ void (*remove_node)(PurpleBlistNode *node); @@ -132,7 +132,7 @@ * be set to a fallback function that saves data to blist.xml like in * previous libpurple versions. * - * @param account The account whose data to save. If NULL, save all data + * @account: The account whose data to save. If NULL, save all data * for all accounts. */ void (*save_account)(PurpleAccount *account); @@ -159,14 +159,14 @@ /** * Returns the main buddy list. * - * @return The main buddy list. + * Returns: The main buddy list. */ PurpleBuddyList *purple_blist_get_buddy_list(void); /** * Returns the root node of the main buddy list. * - * @return The root node. + * Returns: The root node. */ PurpleBlistNode *purple_blist_get_root(void); @@ -175,7 +175,7 @@ * discouraged if you do not actually need every buddy in the list. Use * purple_blist_find_buddies instead. * - * @return A list of every buddy in the list. Caller is responsible for + * Returns: A list of every buddy in the list. Caller is responsible for * freeing the list. * * @see purple_blist_find_buddies @@ -185,14 +185,14 @@ /** * Returns the UI data for the list. * - * @return The UI data for the list. + * Returns: The UI data for the list. */ gpointer purple_blist_get_ui_data(void); /** * Sets the UI data for the list. * - * @param ui_data The UI data for the list. + * @ui_data: The UI data for the list. */ void purple_blist_set_ui_data(gpointer ui_data); @@ -204,7 +204,7 @@ /** * Hides or unhides the buddy list. * - * @param show Whether or not to show the buddy list + * @show: Whether or not to show the buddy list */ void purple_blist_set_visible(gboolean show); @@ -213,8 +213,8 @@ * updates the cache, the caller is responsible for the actual renaming of * the buddy after updating the cache. * - * @param buddy The buddy whose name will be changed. - * @param name The new name of the buddy. + * @buddy: The buddy whose name will be changed. + * @name: The new name of the buddy. */ void purple_blist_update_buddies_cache(PurpleBuddy *buddy, const char *new_name); @@ -223,8 +223,8 @@ * updates the cache, the caller is responsible for the actual renaming of * the group after updating the cache. * - * @param group The group whose name will be changed. - * @param name The new name of the group. + * @group: The group whose name will be changed. + * @name: The new name of the group. */ void purple_blist_update_groups_cache(PurpleGroup *group, const char *new_name); @@ -235,9 +235,9 @@ * of group if node is NULL. If both are NULL, the buddy will be added to * the "Chats" group. * - * @param chat The new chat who gets added - * @param group The group to add the new chat to. - * @param node The insertion point + * @chat: The new chat who gets added + * @group: The group to add the new chat to. + * @node: The insertion point */ void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node); @@ -248,10 +248,10 @@ * group if node is NULL. If both are NULL, the buddy will be added to * the "Buddies" group. * - * @param buddy The new buddy who gets added - * @param contact The optional contact to place the buddy in. - * @param group The group to add the new buddy to. - * @param node The insertion point. Pass in NULL to add the node as + * @buddy: The new buddy who gets added + * @contact: The optional contact to place the buddy in. + * @group: The group to add the new buddy to. + * @node: The insertion point. Pass in NULL to add the node as * the first child in the given group. */ void purple_blist_add_buddy(PurpleBuddy *buddy, PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node); @@ -262,8 +262,8 @@ * The new group will be inserted after insert or prepended to the list if * node is NULL. * - * @param group The group - * @param node The insertion point + * @group: The group + * @node: The insertion point */ void purple_blist_add_group(PurpleGroup *group, PurpleBlistNode *node); @@ -273,9 +273,9 @@ * The new contact will be inserted after insert or prepended to the list if * node is NULL. * - * @param contact The contact - * @param group The group to add the contact to - * @param node The insertion point + * @contact: The contact + * @group: The group to add the contact to + * @node: The insertion point */ void purple_blist_add_contact(PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node); @@ -283,7 +283,7 @@ * Removes a buddy from the buddy list and frees the memory allocated to it. * This doesn't actually try to remove the buddy from the server list. * - * @param buddy The buddy to be removed + * @buddy: The buddy to be removed * * @see purple_account_remove_buddy */ @@ -294,7 +294,7 @@ * allocated to it. This calls purple_blist_remove_buddy and therefore * doesn't remove the buddies from the server list. * - * @param contact The contact to be removed + * @contact: The contact to be removed * * @see purple_blist_remove_buddy */ @@ -303,7 +303,7 @@ /** * Removes a chat from the buddy list and frees the memory allocated to it. * - * @param chat The chat to be removed + * @chat: The chat to be removed */ void purple_blist_remove_chat(PurpleChat *chat); @@ -311,26 +311,26 @@ * Removes a group from the buddy list and frees the memory allocated to it and to * its children * - * @param group The group to be removed + * @group: The group to be removed */ void purple_blist_remove_group(PurpleGroup *group); /** * Finds the buddy struct given a name and an account * - * @param account The account this buddy belongs to - * @param name The buddy's name - * @return The buddy or NULL if the buddy does not exist + * @account: The account this buddy belongs to + * @name: The buddy's name + * Returns: The buddy or NULL if the buddy does not exist */ PurpleBuddy *purple_blist_find_buddy(PurpleAccount *account, const char *name); /** * Finds the buddy struct given a name, an account, and a group * - * @param account The account this buddy belongs to - * @param name The buddy's name - * @param group The group to look in - * @return The buddy or NULL if the buddy does not exist in the group + * @account: The account this buddy belongs to + * @name: The buddy's name + * @group: The group to look in + * Returns: The buddy or NULL if the buddy does not exist in the group */ PurpleBuddy *purple_blist_find_buddy_in_group(PurpleAccount *account, const char *name, PurpleGroup *group); @@ -338,10 +338,10 @@ /** * Finds all PurpleBuddy structs given a name and an account * - * @param account The account this buddy belongs to - * @param name The buddy's name (or NULL to return all buddies for the account) + * @account: The account this buddy belongs to + * @name: The buddy's name (or NULL to return all buddies for the account) * - * @return NULL if the buddy doesn't exist, or a GSList of + * Returns: NULL if the buddy doesn't exist, or a GSList of * PurpleBuddy structs. You must free the GSList using * g_slist_free. Do not free the PurpleBuddy structs that * the list points to. @@ -351,18 +351,18 @@ /** * Finds a group by name * - * @param name The group's name - * @return The group or NULL if the group does not exist + * @name: The group's name + * Returns: The group or NULL if the group does not exist */ PurpleGroup *purple_blist_find_group(const char *name); /** * Finds a chat by name. * - * @param account The chat's account. - * @param name The chat's name. + * @account: The chat's account. + * @name: The chat's name. * - * @return The chat, or @c NULL if the chat does not exist. + * Returns: The chat, or @c NULL if the chat does not exist. */ PurpleChat *purple_blist_find_chat(PurpleAccount *account, const char *name); @@ -370,7 +370,7 @@ * Called when an account connects. Tells the UI to update all the * buddies. * - * @param account The account + * @account: The account */ void purple_blist_add_account(PurpleAccount *account); @@ -378,7 +378,7 @@ * Called when an account disconnects. Sets the presence of all the buddies to 0 * and tells the UI to update them. * - * @param account The account + * @account: The account */ void purple_blist_remove_account(PurpleAccount *account); @@ -401,10 +401,10 @@ * Requests from the user information needed to add a buddy to the * buddy list. * - * @param account The account the buddy is added to. - * @param username The username of the buddy. - * @param group The name of the group to place the buddy in. - * @param alias The optional alias for the buddy. + * @account: The account the buddy is added to. + * @username: The username of the buddy. + * @group: The name of the group to place the buddy in. + * @alias: The optional alias for the buddy. */ void purple_blist_request_add_buddy(PurpleAccount *account, const char *username, const char *group, const char *alias); @@ -413,10 +413,10 @@ * Requests from the user information needed to add a chat to the * buddy list. * - * @param account The account the buddy is added to. - * @param group The optional group to add the chat to. - * @param alias The optional alias for the chat. - * @param name The required chat name. + * @account: The account the buddy is added to. + * @group: The optional group to add the chat to. + * @alias: The optional alias for the chat. + * @name: The required chat name. */ void purple_blist_request_add_chat(PurpleAccount *account, PurpleGroup *group, const char *alias, const char *name); @@ -435,14 +435,14 @@ /** * Sets the UI operations structure to be used for the buddy list. * - * @param ops The ops struct. + * @ops: The ops struct. */ void purple_blist_set_ui_ops(PurpleBlistUiOps *ops); /** * Returns the UI operations structure to be used for the buddy list. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleBlistUiOps *purple_blist_get_ui_ops(void); @@ -456,7 +456,7 @@ /** * Returns the handle for the buddy list subsystem. * - * @return The buddy list subsystem handle. + * Returns: The buddy list subsystem handle. */ void *purple_blist_get_handle(void);
--- a/libpurple/certificate.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/certificate.h Wed Jan 29 05:28:33 2014 +0530 @@ -93,8 +93,8 @@ /** * Callback function for the results of a verification check - * @param st Status code - * @param userdata User-defined data + * @st: Status code + * @userdata: User-defined data */ typedef void (*PurpleCertificateVerifiedCallback) (PurpleCertificateVerificationStatus st, @@ -141,7 +141,7 @@ * * Upon calling purple_certificate_register_pool() , this function will * be called. May be NULL. - * @return TRUE if the initialization succeeded, otherwise FALSE + * Returns: TRUE if the initialization succeeded, otherwise FALSE */ gboolean (* init)(void); @@ -158,7 +158,7 @@ PurpleCertificate * (* get_cert)(const gchar *id); /** Add a certificate to the pool. Must overwrite any other * certificates sharing the same ID in the pool. - * @return TRUE if the operation succeeded, otherwise FALSE + * Returns: TRUE if the operation succeeded, otherwise FALSE */ gboolean (* put_cert)(const gchar *id, PurpleCertificate *crt); /** Delete a certificate from the pool */ @@ -200,8 +200,8 @@ /** Imports a certificate from a file * - * @param filename File to import the certificate from - * @return Pointer to the newly allocated Certificate struct + * @filename: File to import the certificate from + * Returns: Pointer to the newly allocated Certificate struct * or NULL on failure. */ PurpleCertificate * (* import_certificate)(const gchar * filename); @@ -209,9 +209,9 @@ /** * Exports a certificate to a file * - * @param filename File to export the certificate to - * @param crt Certificate to export - * @return TRUE if the export succeeded, otherwise FALSE + * @filename: File to export the certificate to + * @crt: Certificate to export + * Returns: TRUE if the export succeeded, otherwise FALSE * @see purple_certificate_export() */ gboolean (* export_certificate)(const gchar *filename, PurpleCertificate *crt); @@ -222,7 +222,7 @@ * Certificates are generally assumed to be read-only, so feel free to * do any sort of reference-counting magic you want here. If this ever * changes, please remember to change the magic accordingly. - * @return Reference to the new copy + * Returns: Reference to the new copy */ PurpleCertificate * (* copy_certificate)(PurpleCertificate *crt); @@ -231,7 +231,7 @@ * Destroys a Certificate's internal data structures and calls * free(crt) * - * @param crt Certificate instance to be destroyed. It WILL NOT be + * @crt: Certificate instance to be destroyed. It WILL NOT be * destroyed if it is not of the correct * CertificateScheme. Can be NULL */ @@ -243,8 +243,8 @@ /** * Retrieves the certificate public key fingerprint using SHA1 * - * @param crt Certificate instance - * @return Binary representation of SHA1 hash - must be freed using + * @crt: Certificate instance + * Returns: Binary representation of SHA1 hash - must be freed using * g_byte_array_free() */ GByteArray * (* get_fingerprint_sha1)(PurpleCertificate *crt); @@ -252,8 +252,8 @@ /** * Retrieves a unique certificate identifier * - * @param crt Certificate instance - * @return Newly allocated string that can be used to uniquely + * @crt: Certificate instance + * Returns: Newly allocated string that can be used to uniquely * identify the certificate. */ gchar * (* get_unique_id)(PurpleCertificate *crt); @@ -261,8 +261,8 @@ /** * Retrieves a unique identifier for the certificate's issuer * - * @param crt Certificate instance - * @return Newly allocated string that can be used to uniquely + * @crt: Certificate instance + * Returns: Newly allocated string that can be used to uniquely * identify the issuer's certificate. */ gchar * (* get_issuer_unique_id)(PurpleCertificate *crt); @@ -275,15 +275,15 @@ * * @see purple_certificate_get_subject_name() * - * @param crt Certificate instance - * @return Newly allocated string with the certificate subject. + * @crt: Certificate instance + * Returns: Newly allocated string with the certificate subject. */ gchar * (* get_subject_name)(PurpleCertificate *crt); /** * Check the subject name against that on the certificate * @see purple_certificate_check_subject_name() - * @return TRUE if it is a match, else FALSE + * Returns: TRUE if it is a match, else FALSE */ gboolean (* check_subject_name)(PurpleCertificate *crt, const gchar *name); @@ -292,8 +292,8 @@ /** Imports certificates from a file * - * @param filename File to import the certificates from - * @return GSList of pointers to the newly allocated Certificate structs + * @filename: File to import the certificates from + * Returns: GSList of pointers to the newly allocated Certificate structs * or NULL on failure. */ GSList * (* import_certificates)(const gchar * filename); @@ -301,8 +301,8 @@ /** * Retrieves the certificate data in DER form * - * @param crt Certificate instance - * @return Binary DER representation of certificate - must be freed using + * @crt: Certificate instance + * Returns: Binary DER representation of certificate - must be freed using * g_byte_array_free() */ GByteArray * (* get_der_data)(PurpleCertificate *crt); @@ -310,8 +310,8 @@ /** * Retrieves a string representation of the certificate suitable for display * - * @param crt Certificate instance - * @return User-displayable string representation of certificate - must be + * @crt: Certificate instance + * Returns: User-displayable string representation of certificate - must be * freed using g_free(). */ gchar * (* get_display_string)(PurpleCertificate *crt); @@ -349,7 +349,7 @@ * given VerificationRequest to check the certificate and callback * the requester with the verification results. * - * @param vrq Request to process + * @vrq: Request to process */ void (* start_verification)(PurpleCertificateVerificationRequest *vrq); @@ -359,7 +359,7 @@ * whatever PurpleCertificateVerificationRequest::data points to. * It should not call free(vrq) * - * @param vrq Request to destroy + * @vrq: Request to destroy */ void (* destroy_request)(PurpleCertificateVerificationRequest *vrq); @@ -421,22 +421,22 @@ * It is possible that the callback will be called immediately upon calling * this function. Plan accordingly. * - * @param verifier Verification logic to use. + * @verifier: Verification logic to use. * @see purple_certificate_find_verifier() * - * @param subject_name Name that should match the first certificate in the + * @subject_name: Name that should match the first certificate in the * chain for the certificate to be valid. Will be strdup'd * into the Request struct * - * @param cert_chain Certificate chain to check. If there is more than one + * @cert_chain: Certificate chain to check. If there is more than one * certificate in the chain (X.509), the peer's * certificate comes first, then the issuer/signer's * certificate, etc. The whole list is duplicated into the * Request struct. * - * @param cb Callback function to be called with whether the + * @cb: Callback function to be called with whether the * certificate was approved or not. - * @param cb_data User-defined data for the above. + * @cb_data: User-defined data for the above. */ void purple_certificate_verify (PurpleCertificateVerifier *verifier, @@ -447,8 +447,8 @@ /** * Completes and destroys a VerificationRequest * - * @param vrq Request to conclude - * @param st Success/failure code to pass to the request's + * @vrq: Request to conclude + * @st: Success/failure code to pass to the request's * completion callback. */ void @@ -470,8 +470,8 @@ /** * Makes a duplicate of a certificate * - * @param crt Instance to duplicate - * @return Pointer to new instance + * @crt: Instance to duplicate + * Returns: Pointer to new instance */ PurpleCertificate * purple_certificate_copy(PurpleCertificate *crt); @@ -479,8 +479,8 @@ /** * Duplicates an entire list of certificates * - * @param crt_list List to duplicate - * @return New list copy + * @crt_list: List to duplicate + * Returns: New list copy */ GList * purple_certificate_copy_list(GList *crt_list); @@ -488,7 +488,7 @@ /** * Destroys and free()'s a Certificate * - * @param crt Instance to destroy. May be NULL. + * @crt: Instance to destroy. May be NULL. */ void purple_certificate_destroy (PurpleCertificate *crt); @@ -496,7 +496,7 @@ /** * Destroy an entire list of Certificate instances and the containing list * - * @param crt_list List of certificates to destroy. May be NULL. + * @crt_list: List of certificates to destroy. May be NULL. */ void purple_certificate_destroy_list (GList * crt_list); @@ -504,10 +504,10 @@ /** * Check whether 'crt' has a valid signature made by 'issuer' * - * @param crt Certificate instance to check signature of - * @param issuer Certificate thought to have signed 'crt' + * @crt: Certificate instance to check signature of + * @issuer: Certificate thought to have signed 'crt' * - * @return TRUE if 'crt' has a valid signature made by 'issuer', + * Returns: TRUE if 'crt' has a valid signature made by 'issuer', * otherwise FALSE * @todo Find a way to give the reason (bad signature, not the issuer, etc.) */ @@ -521,12 +521,12 @@ * in the chain carries a valid signature from the next. A single-certificate * chain is considered to be valid. * - * @param chain List of PurpleCertificate instances comprising the chain, + * @chain: List of PurpleCertificate instances comprising the chain, * in the order certificate, issuer, issuer's issuer, etc. - * @param failing A pointer to a PurpleCertificate*. If not NULL, if the + * @failing: A pointer to a PurpleCertificate*. If not NULL, if the * chain fails to validate, this will be set to the * certificate whose signature could not be validated. - * @return TRUE if the chain is valid. See description. + * Returns: TRUE if the chain is valid. See description. */ gboolean purple_certificate_check_signature_chain(GList *chain, @@ -535,9 +535,9 @@ /** * Imports a PurpleCertificate from a file * - * @param scheme Scheme to import under - * @param filename File path to import from - * @return Pointer to a new PurpleCertificate, or NULL on failure + * @scheme: Scheme to import under + * @filename: File path to import from + * Returns: Pointer to a new PurpleCertificate, or NULL on failure */ PurpleCertificate * purple_certificate_import(PurpleCertificateScheme *scheme, const gchar *filename); @@ -545,9 +545,9 @@ /** * Imports a list of PurpleCertificates from a file * - * @param scheme Scheme to import under - * @param filename File path to import from - * @return Pointer to a GSList of new PurpleCertificates, or NULL on failure + * @scheme: Scheme to import under + * @filename: File path to import from + * Returns: Pointer to a GSList of new PurpleCertificates, or NULL on failure */ GSList * purple_certificates_import(PurpleCertificateScheme *scheme, const gchar *filename); @@ -555,9 +555,9 @@ /** * Exports a PurpleCertificate to a file * - * @param filename File to export the certificate to - * @param crt Certificate to export - * @return TRUE if the export succeeded, otherwise FALSE + * @filename: File to export the certificate to + * @crt: Certificate to export + * Returns: TRUE if the export succeeded, otherwise FALSE */ gboolean purple_certificate_export(const gchar *filename, PurpleCertificate *crt); @@ -566,8 +566,8 @@ /** * Retrieves the certificate public key fingerprint using SHA1. * - * @param crt Certificate instance - * @return Binary representation of the hash. You are responsible for free()ing + * @crt: Certificate instance + * Returns: Binary representation of the hash. You are responsible for free()ing * this. * @see purple_base16_encode_chunked() */ @@ -577,8 +577,8 @@ /** * Get a unique identifier for the certificate * - * @param crt Certificate instance - * @return String representing the certificate uniquely. Must be g_free()'ed + * @crt: Certificate instance + * Returns: String representing the certificate uniquely. Must be g_free()'ed */ gchar * purple_certificate_get_unique_id(PurpleCertificate *crt); @@ -586,8 +586,8 @@ /** * Get a unique identifier for the certificate's issuer * - * @param crt Certificate instance - * @return String representing the certificate's issuer uniquely. Must be + * @crt: Certificate instance + * Returns: String representing the certificate's issuer uniquely. Must be * g_free()'ed */ gchar * @@ -599,17 +599,17 @@ * For X.509, this is the "Common Name" field, as we're only using it * for hostname verification at the moment * - * @param crt Certificate instance - * @return Newly allocated string with the certificate subject. + * @crt: Certificate instance + * Returns: Newly allocated string with the certificate subject. */ gchar * purple_certificate_get_subject_name(PurpleCertificate *crt); /** * Check the subject name against that on the certificate - * @param crt Certificate instance - * @param name Name to check. - * @return TRUE if it is a match, else FALSE + * @crt: Certificate instance + * @name: Name to check. + * Returns: TRUE if it is a match, else FALSE */ gboolean purple_certificate_check_subject_name(PurpleCertificate *crt, const gchar *name); @@ -617,12 +617,12 @@ /** * Get the expiration/activation times. * - * @param crt Certificate instance - * @param activation Reference to store the activation time at. May be NULL + * @crt: Certificate instance + * @activation: Reference to store the activation time at. May be NULL * if you don't actually want it. - * @param expiration Reference to store the expiration time at. May be NULL + * @expiration: Reference to store the expiration time at. May be NULL * if you don't actually want it. - * @return TRUE if the requested values were obtained, otherwise FALSE. + * Returns: TRUE if the requested values were obtained, otherwise FALSE. */ gboolean purple_certificate_get_times(PurpleCertificate *crt, gint64 *activation, gint64 *expiration); @@ -630,9 +630,9 @@ /** * Retrieves the certificate data in DER form. * - * @param crt Certificate instance + * @crt: Certificate instance * - * @return Binary DER representation of the certificate - must be freed using + * Returns: Binary DER representation of the certificate - must be freed using * g_byte_array_free(). */ GByteArray * @@ -641,9 +641,9 @@ /** * Retrieves a string suitable for displaying a certificate to the user. * - * @param crt Certificate instance + * @crt: Certificate instance * - * @return String representing the certificate that may be displayed to the user + * Returns: String representing the certificate that may be displayed to the user * - must be freed using g_free(). */ char * @@ -670,9 +670,9 @@ * * All components will be escaped for filesystem friendliness. * - * @param pool CertificatePool to build a path for - * @param id Key to look up a Certificate by. May be NULL. - * @return A newly allocated path of the form + * @pool: CertificatePool to build a path for + * @id: Key to look up a Certificate by. May be NULL. + * Returns: A newly allocated path of the form * ~/.purple/certificates/scheme_name/pool_name/unique_id */ gchar * @@ -683,9 +683,9 @@ * * Checks whether the associated CertificateScheme is loaded. * - * @param pool Pool to check + * @pool: Pool to check * - * @return TRUE if the pool can be used, otherwise FALSE + * Returns: TRUE if the pool can be used, otherwise FALSE */ gboolean purple_certificate_pool_usable(PurpleCertificatePool *pool); @@ -693,9 +693,9 @@ /** * Looks up the scheme the pool operates under * - * @param pool Pool to get the scheme of + * @pool: Pool to get the scheme of * - * @return Pointer to the pool's scheme, or NULL if it isn't loaded. + * Returns: Pointer to the pool's scheme, or NULL if it isn't loaded. * @see purple_certificate_pool_usable() */ PurpleCertificateScheme * @@ -703,18 +703,18 @@ /** * Check for presence of an ID in a pool. - * @param pool Pool to look in - * @param id ID to look for - * @return TRUE if the ID is in the pool, else FALSE + * @pool: Pool to look in + * @id: ID to look for + * Returns: TRUE if the ID is in the pool, else FALSE */ gboolean purple_certificate_pool_contains(PurpleCertificatePool *pool, const gchar *id); /** * Retrieve a certificate from a pool. - * @param pool Pool to fish in - * @param id ID to look up - * @return Retrieved certificate, or NULL if it wasn't there + * @pool: Pool to fish in + * @id: ID to look up + * Returns: Retrieved certificate, or NULL if it wasn't there */ PurpleCertificate * purple_certificate_pool_retrieve(PurpleCertificatePool *pool, const gchar *id); @@ -724,10 +724,10 @@ * * Any pre-existing certificate of the same ID will be overwritten. * - * @param pool Pool to add to - * @param id ID to store the certificate with - * @param crt Certificate to store - * @return TRUE if the operation succeeded, otherwise FALSE + * @pool: Pool to add to + * @id: ID to store the certificate with + * @crt: Certificate to store + * Returns: TRUE if the operation succeeded, otherwise FALSE */ gboolean purple_certificate_pool_store(PurpleCertificatePool *pool, const gchar *id, PurpleCertificate *crt); @@ -735,9 +735,9 @@ /** * Remove a certificate from a pool * - * @param pool Pool to remove from - * @param id ID to remove - * @return TRUE if the operation succeeded, otherwise FALSE + * @pool: Pool to remove from + * @id: ID to remove + * Returns: TRUE if the operation succeeded, otherwise FALSE */ gboolean purple_certificate_pool_delete(PurpleCertificatePool *pool, const gchar *id); @@ -745,8 +745,8 @@ /** * Get the list of IDs currently in the pool. * - * @param pool Pool to enumerate - * @return GList pointing to newly-allocated id strings. Free using + * @pool: Pool to enumerate + * Returns: GList pointing to newly-allocated id strings. Free using * purple_certificate_pool_destroy_idlist() */ GList * @@ -755,7 +755,7 @@ /** * Destroys the result given by purple_certificate_pool_get_idlist() * - * @param idlist ID List to destroy + * @idlist: ID List to destroy */ void purple_certificate_pool_destroy_idlist(GList *idlist); @@ -786,8 +786,8 @@ purple_certificate_get_handle(void); /** Look up a registered CertificateScheme by name - * @param name The scheme name. Case insensitive. - * @return Pointer to the located Scheme, or NULL if it isn't found. + * @name: The scheme name. Case insensitive. + * Returns: Pointer to the located Scheme, or NULL if it isn't found. */ PurpleCertificateScheme * purple_certificate_find_scheme(const gchar *name); @@ -795,7 +795,7 @@ /** * Get all registered CertificateSchemes * - * @return GList pointing to all registered CertificateSchemes . This value + * Returns: GList pointing to all registered CertificateSchemes . This value * is owned by libpurple */ GList * @@ -806,26 +806,26 @@ * No two schemes can be registered with the same name; this function enforces * that. * - * @param scheme Pointer to the scheme to register. - * @return TRUE if the scheme was successfully added, otherwise FALSE + * @scheme: Pointer to the scheme to register. + * Returns: TRUE if the scheme was successfully added, otherwise FALSE */ gboolean purple_certificate_register_scheme(PurpleCertificateScheme *scheme); /** Unregister a CertificateScheme from libpurple * - * @param scheme Scheme to unregister. + * @scheme: Scheme to unregister. * If the scheme is not registered, this is a no-op. * - * @return TRUE if the unregister completed successfully + * Returns: TRUE if the unregister completed successfully */ gboolean purple_certificate_unregister_scheme(PurpleCertificateScheme *scheme); /** Look up a registered PurpleCertificateVerifier by scheme and name - * @param scheme_name Scheme name. Case insensitive. - * @param ver_name The verifier name. Case insensitive. - * @return Pointer to the located Verifier, or NULL if it isn't found. + * @scheme_name: Scheme name. Case insensitive. + * @ver_name: The verifier name. Case insensitive. + * Returns: Pointer to the located Verifier, or NULL if it isn't found. */ PurpleCertificateVerifier * purple_certificate_find_verifier(const gchar *scheme_name, const gchar *ver_name); @@ -833,7 +833,7 @@ /** * Get the list of registered CertificateVerifiers * - * @return GList of all registered PurpleCertificateVerifier. This value + * Returns: GList of all registered PurpleCertificateVerifier. This value * is owned by libpurple */ GList * @@ -842,8 +842,8 @@ /** * Register a CertificateVerifier with libpurple * - * @param vr Verifier to register. - * @return TRUE if register succeeded, otherwise FALSE + * @vr: Verifier to register. + * Returns: TRUE if register succeeded, otherwise FALSE */ gboolean purple_certificate_register_verifier(PurpleCertificateVerifier *vr); @@ -851,16 +851,16 @@ /** * Unregister a CertificateVerifier with libpurple * - * @param vr Verifier to unregister. - * @return TRUE if unregister succeeded, otherwise FALSE + * @vr: Verifier to unregister. + * Returns: TRUE if unregister succeeded, otherwise FALSE */ gboolean purple_certificate_unregister_verifier(PurpleCertificateVerifier *vr); /** Look up a registered PurpleCertificatePool by scheme and name - * @param scheme_name Scheme name. Case insensitive. - * @param pool_name Pool name. Case insensitive. - * @return Pointer to the located Pool, or NULL if it isn't found. + * @scheme_name: Scheme name. Case insensitive. + * @pool_name: Pool name. Case insensitive. + * Returns: Pointer to the located Pool, or NULL if it isn't found. */ PurpleCertificatePool * purple_certificate_find_pool(const gchar *scheme_name, const gchar *pool_name); @@ -868,7 +868,7 @@ /** * Get the list of registered Pools * - * @return GList of all registered PurpleCertificatePool s. This value + * Returns: GList of all registered PurpleCertificatePool s. This value * is owned by libpurple */ GList * @@ -877,8 +877,8 @@ /** * Register a CertificatePool with libpurple and call its init function * - * @param pool Pool to register. - * @return TRUE if the register succeeded, otherwise FALSE + * @pool: Pool to register. + * Returns: TRUE if the register succeeded, otherwise FALSE */ gboolean purple_certificate_register_pool(PurpleCertificatePool *pool); @@ -886,8 +886,8 @@ /** * Unregister a CertificatePool with libpurple and call its uninit function * - * @param pool Pool to unregister. - * @return TRUE if the unregister succeeded, otherwise FALSE + * @pool: Pool to unregister. + * Returns: TRUE if the unregister succeeded, otherwise FALSE */ gboolean purple_certificate_unregister_pool(PurpleCertificatePool *pool); @@ -898,7 +898,7 @@ /** * Add a search path for certificates. * - * @param path Path to search for certificates. + * @path: Path to search for certificates. */ void purple_certificate_add_ca_search_path(const char *path);
--- a/libpurple/cipher.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/cipher.h Wed Jan 29 05:28:33 2014 +0530 @@ -186,7 +186,7 @@ * Resets a cipher to it's default value * @note If you have set an IV you will have to set it after resetting * - * @param cipher The cipher + * @cipher: The cipher */ void purple_cipher_reset(PurpleCipher *cipher); @@ -197,7 +197,7 @@ * That means, IV and digest will be wiped out, but keys, ops or salt * will remain untouched. * - * @param cipher The cipher + * @cipher: The cipher */ void purple_cipher_reset_state(PurpleCipher *cipher); @@ -205,106 +205,106 @@ * Sets the initialization vector for a cipher * @note This should only be called right after a cipher is created or reset * - * @param cipher The cipher - * @param iv The initialization vector to set - * @param len The len of the IV + * @cipher: The cipher + * @iv: The initialization vector to set + * @len: The len of the IV */ void purple_cipher_set_iv(PurpleCipher *cipher, guchar *iv, size_t len); /** * Appends data to the cipher context * - * @param cipher The cipher - * @param data The data to append - * @param len The length of the data + * @cipher: The cipher + * @data: The data to append + * @len: The length of the data */ void purple_cipher_append(PurpleCipher *cipher, const guchar *data, size_t len); /** * Digests a cipher context * - * @param cipher The cipher - * @param digest The return buffer for the digest - * @param len The length of the buffer + * @cipher: The cipher + * @digest: The return buffer for the digest + * @len: The length of the buffer */ gboolean purple_cipher_digest(PurpleCipher *cipher, guchar digest[], size_t len); /** * Converts a guchar digest into a hex string * - * @param cipher The cipher - * @param digest_s The return buffer for the string digest - * @param len The length of the buffer + * @cipher: The cipher + * @digest_s: The return buffer for the string digest + * @len: The length of the buffer */ gboolean purple_cipher_digest_to_str(PurpleCipher *cipher, gchar digest_s[], size_t len); /** * Gets the digest size of a cipher * - * @param cipher The cipher whose digest size to get + * @cipher: The cipher whose digest size to get * - * @return The digest size of the cipher + * Returns: The digest size of the cipher */ size_t purple_cipher_get_digest_size(PurpleCipher *cipher); /** * Encrypts data using the cipher * - * @param cipher The cipher - * @param input The data to encrypt - * @param in_len The length of the data - * @param output The output buffer - * @param out_size The size of the output buffer + * @cipher: The cipher + * @input: The data to encrypt + * @in_len: The length of the data + * @output: The output buffer + * @out_size: The size of the output buffer * - * @return A length of data that was outputed or -1, if failed + * Returns: A length of data that was outputed or -1, if failed */ ssize_t purple_cipher_encrypt(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size); /** * Decrypts data using the cipher * - * @param cipher The cipher - * @param input The data to encrypt - * @param in_len The length of the returned value - * @param output The output buffer - * @param out_size The size of the output buffer + * @cipher: The cipher + * @input: The data to encrypt + * @in_len: The length of the returned value + * @output: The output buffer + * @out_size: The size of the output buffer * - * @return A length of data that was outputed or -1, if failed + * Returns: A length of data that was outputed or -1, if failed */ ssize_t purple_cipher_decrypt(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size); /** * Sets the salt on a cipher * - * @param cipher The cipher whose salt to set - * @param salt The salt - * @param len The length of the salt + * @cipher: The cipher whose salt to set + * @salt: The salt + * @len: The length of the salt */ void purple_cipher_set_salt(PurpleCipher *cipher, const guchar *salt, size_t len); /** * Sets the key on a cipher * - * @param cipher The cipher whose key to set - * @param key The key - * @param len The size of the key + * @cipher: The cipher whose key to set + * @key: The key + * @len: The size of the key */ void purple_cipher_set_key(PurpleCipher *cipher, const guchar *key, size_t len); /** * Gets the size of the key if the cipher supports it * - * @param cipher The cipher whose key size to get + * @cipher: The cipher whose key size to get * - * @return The size of the key + * Returns: The size of the key */ size_t purple_cipher_get_key_size(PurpleCipher *cipher); /** * Sets the batch mode of a cipher * - * @param cipher The cipher whose batch mode to set - * @param mode The batch mode under which the cipher should operate + * @cipher: The cipher whose batch mode to set + * @mode: The batch mode under which the cipher should operate * */ void purple_cipher_set_batch_mode(PurpleCipher *cipher, PurpleCipherBatchMode mode); @@ -312,18 +312,18 @@ /** * Gets the batch mode of a cipher * - * @param cipher The cipher whose batch mode to get + * @cipher: The cipher whose batch mode to get * - * @return The batch mode under which the cipher is operating + * Returns: The batch mode under which the cipher is operating */ PurpleCipherBatchMode purple_cipher_get_batch_mode(PurpleCipher *cipher); /** * Gets the block size of a cipher * - * @param cipher The cipher whose block size to get + * @cipher: The cipher whose block size to get * - * @return The block size of the cipher + * Returns: The block size of the cipher */ size_t purple_cipher_get_block_size(PurpleCipher *cipher); @@ -343,7 +343,7 @@ * Resets a hash to it's default value * @note If you have set an IV you will have to set it after resetting * - * @param hash The hash + * @hash: The hash */ void purple_hash_reset(PurpleHash *hash); @@ -354,52 +354,52 @@ * That means, IV and digest will be wiped out, but keys, ops or salt * will remain untouched. * - * @param hash The hash + * @hash: The hash */ void purple_hash_reset_state(PurpleHash *hash); /** * Appends data to the hash context * - * @param hash The hash - * @param data The data to append - * @param len The length of the data + * @hash: The hash + * @data: The data to append + * @len: The length of the data */ void purple_hash_append(PurpleHash *hash, const guchar *data, size_t len); /** * Digests a hash context * - * @param hash The hash - * @param digest The return buffer for the digest - * @param len The length of the buffer + * @hash: The hash + * @digest: The return buffer for the digest + * @len: The length of the buffer */ gboolean purple_hash_digest(PurpleHash *hash, guchar digest[], size_t len); /** * Converts a guchar digest into a hex string * - * @param hash The hash - * @param digest_s The return buffer for the string digest - * @param len The length of the buffer + * @hash: The hash + * @digest_s: The return buffer for the string digest + * @len: The length of the buffer */ gboolean purple_hash_digest_to_str(PurpleHash *hash, gchar digest_s[], size_t len); /** * Gets the digest size of a hash * - * @param hash The hash whose digest size to get + * @hash: The hash whose digest size to get * - * @return The digest size of the hash + * Returns: The digest size of the hash */ size_t purple_hash_get_digest_size(PurpleHash *hash); /** * Gets the block size of a hash * - * @param hash The hash whose block size to get + * @hash: The hash whose block size to get * - * @return The block size of the hash + * Returns: The block size of the hash */ size_t purple_hash_get_block_size(PurpleHash *hash);
--- a/libpurple/circularbuffer.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/circularbuffer.h Wed Jan 29 05:28:33 2014 +0530 @@ -65,11 +65,11 @@ * Creates a new circular buffer. This will not allocate any memory for the * actual buffer until data is appended to it. * - * @param growsize The amount that the buffer should grow the first time data + * @growsize: The amount that the buffer should grow the first time data * is appended and every time more space is needed. Pass in * "0" to use the default of 256 bytes. * - * @return The new PurpleCircularBuffer. + * Returns: The new PurpleCircularBuffer. */ PurpleCircularBuffer *purple_circular_buffer_new(gsize growsize); @@ -77,9 +77,9 @@ * Append data to the PurpleCircularBuffer. This will grow the internal * buffer to fit the added data, if needed. * - * @param buf The PurpleCircularBuffer to which to append the data - * @param src pointer to the data to copy into the buffer - * @param len number of bytes to copy into the buffer + * @buf: The PurpleCircularBuffer to which to append the data + * @src: pointer to the data to copy into the buffer + * @len: number of bytes to copy into the buffer */ void purple_circular_buffer_append(PurpleCircularBuffer *buf, gconstpointer src, gsize len); @@ -90,20 +90,20 @@ * subsequent call after calling purple_circular_buffer_mark_read() may indicate * more data is available to read. * - * @param buf the PurpleCircularBuffer for which to determine the maximum + * @buf: the PurpleCircularBuffer for which to determine the maximum * contiguous bytes that can be read. * - * @return the number of bytes that can be read from the PurpleCircularBuffer + * Returns: the number of bytes that can be read from the PurpleCircularBuffer */ gsize purple_circular_buffer_get_max_read(const PurpleCircularBuffer *buf); /** * Mark the number of bytes that have been read from the buffer. * - * @param buf The PurpleCircularBuffer to mark bytes read from - * @param len The number of bytes to mark as read + * @buf: The PurpleCircularBuffer to mark bytes read from + * @len: The number of bytes to mark as read * - * @return TRUE if we successfully marked the bytes as having been read, FALSE + * Returns: TRUE if we successfully marked the bytes as having been read, FALSE * otherwise. */ gboolean purple_circular_buffer_mark_read(PurpleCircularBuffer *buf, gsize len); @@ -112,8 +112,8 @@ * Increases the buffer size by a multiple of grow size, so that it can hold at * least 'len' bytes. * - * @param buffer The PurpleCircularBuffer to grow. - * @param len The number of bytes the buffer should be able to hold. + * @buffer: The PurpleCircularBuffer to grow. + * @len: The number of bytes the buffer should be able to hold. */ void purple_circular_buffer_grow(PurpleCircularBuffer *buffer, gsize len); @@ -121,18 +121,18 @@ * Returns the number of bytes by which the buffer grows when more space is * needed. * - * @param buffer The PurpleCircularBuffer from which to get grow size. + * @buffer: The PurpleCircularBuffer from which to get grow size. * - * @return The grow size of the buffer. + * Returns: The grow size of the buffer. */ gsize purple_circular_buffer_get_grow_size(const PurpleCircularBuffer *buffer); /** * Returns the number of bytes of this buffer that contain unread data. * - * @param buffer The PurpleCircularBuffer from which to get used count. + * @buffer: The PurpleCircularBuffer from which to get used count. * - * @return The number of bytes that contain unread data. + * Returns: The number of bytes that contain unread data. */ gsize purple_circular_buffer_get_used(const PurpleCircularBuffer *buffer); @@ -142,16 +142,16 @@ * contiguous bytes that can be read from this output. After reading the data, * call purple_circular_buffer_mark_read() to mark the retrieved data as read. * - * @param buffer The PurpleCircularBuffer from which to get the output pointer. + * @buffer: The PurpleCircularBuffer from which to get the output pointer. * - * @return The output pointer for the buffer. + * Returns: The output pointer for the buffer. */ const gchar *purple_circular_buffer_get_output(const PurpleCircularBuffer *buffer); /** * Resets the buffer contents. * - * @param buffer The PurpleCircularBuffer to reset. + * @buffer: The PurpleCircularBuffer to reset. */ void purple_circular_buffer_reset(PurpleCircularBuffer *buffer);
--- a/libpurple/cmds.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/cmds.h Wed Jan 29 05:28:33 2014 +0530 @@ -112,9 +112,9 @@ * The command will only happen if commands are enabled, * which is a UI pref. UIs don't have to support commands at all. * - * @param cmd The command. This should be a UTF-8 (or ASCII) string, with no spaces + * @cmd: The command. This should be a UTF-8 (or ASCII) string, with no spaces * or other white space. - * @param args A string of characters describing to libpurple how to parse this + * @args: A string of characters describing to libpurple how to parse this * command's arguments. If what the user types doesn't match this * pattern, libpurple will keep looking for another command, unless * the flag #PURPLE_CMD_FLAG_ALLOW_WRONG_ARGS is passed in @a f. @@ -139,21 +139,21 @@ * <tt>|</tt> (bitwise OR). You need to at least pass one of * #PURPLE_CMD_FLAG_IM or #PURPLE_CMD_FLAG_CHAT (you may pass both) in * order for the command to ever actually be called. - * @param protocol_id If the #PURPLE_CMD_FLAG_PROTOCOL_ONLY flag is set, this is the id + * @protocol_id: If the #PURPLE_CMD_FLAG_PROTOCOL_ONLY flag is set, this is the id * of the protocol to which the command applies (such as * <tt>"prpl-msn"</tt>). If the flag is not set, this parameter * is ignored; pass @c NULL (or a humourous string of your * choice!). - * @param func This is the function to call when someone enters this command. - * @param helpstr a whitespace sensitive, UTF-8, HTML string describing how to + * @func: This is the function to call when someone enters this command. + * @helpstr: a whitespace sensitive, UTF-8, HTML string describing how to * use the command. The preferred format of this string is the * command's name, followed by a space and any arguments it * accepts (if it takes any arguments, otherwise no space), * followed by a colon, two spaces, and a description of the * command in sentence form. Do not include a slash before the * command name. - * @param data User defined data to pass to the #PurpleCmdFunc @a f. - * @return A #PurpleCmdId, which is only used for calling + * @data: User defined data to pass to the #PurpleCmdFunc @a f. + * Returns: A #PurpleCmdId, which is only used for calling * #purple_cmd_unregister, or @a 0 on failure. */ PurpleCmdId purple_cmd_register(const gchar *cmd, const gchar *args, PurpleCmdPriority p, PurpleCmdFlag f, @@ -166,7 +166,7 @@ * or something else that might go away. Normally this is called when the plugin * unloads itself. * - * @param id The #PurpleCmdId to unregister, as returned by #purple_cmd_register. + * @id: The #PurpleCmdId to unregister, as returned by #purple_cmd_register. */ void purple_cmd_unregister(PurpleCmdId id); @@ -176,17 +176,17 @@ * Normally the UI calls this to perform a command. This might also be useful * if aliases are ever implemented. * - * @param conv The conversation the command was typed in. - * @param cmdline The command the user typed (including all arguments) as a single string. + * @conv: The conversation the command was typed in. + * @cmdline: The command the user typed (including all arguments) as a single string. * The caller doesn't have to do any parsing, except removing the command * prefix, which the core has no knowledge of. cmd should not contain any * formatting, and should be in plain text (no html entities). - * @param markup This is the same as cmd, but is the formatted version. It should be in + * @markup: This is the same as cmd, but is the formatted version. It should be in * HTML, with < > and &, at least, escaped to html entities, and should * include both the default formatting and any extra manual formatting. - * @param errormsg If the command failed errormsg is filled in with the appropriate error + * @errormsg: If the command failed errormsg is filled in with the appropriate error * message. It must be freed by the caller with g_free(). - * @return A #PurpleCmdStatus indicating if the command succeeded or failed. + * Returns: A #PurpleCmdStatus indicating if the command succeeded or failed. */ PurpleCmdStatus purple_cmd_do_command(PurpleConversation *conv, const gchar *cmdline, const gchar *markup, gchar **errormsg); @@ -200,8 +200,8 @@ * might unregister a command, as the <tt>const char *</tt>'s used get freed * then. * - * @param conv The conversation, or @c NULL. - * @return A @c GList of <tt>const char *</tt>, which must be freed with + * @conv: The conversation, or @c NULL. + * Returns: A @c GList of <tt>const char *</tt>, which must be freed with * <tt>g_list_free()</tt>. */ GList *purple_cmd_list(PurpleConversation *conv); @@ -212,17 +212,17 @@ * Returns the help strings for a given command in the form of a GList, * one node for each matching command. * - * @param conv The conversation, or @c NULL for no context. - * @param cmd The command. No wildcards accepted, but returns help for all + * @conv: The conversation, or @c NULL for no context. + * @cmd: The command. No wildcards accepted, but returns help for all * commands if @c NULL. - * @return A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string + * Returns: A <tt>GList</tt> of <tt>const char *</tt>s, which is the help string * for that command. */ GList *purple_cmd_help(PurpleConversation *conv, const gchar *cmd); /** * Get the handle for the commands API - * @return The handle + * Returns: The handle */ gpointer purple_cmds_get_handle(void);
--- a/libpurple/connection.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/connection.h Wed Jan 29 05:28:33 2014 +0530 @@ -219,9 +219,9 @@ * Called when an error causes a connection to be disconnected. * Called before #disconnected. * - * @param reason why the connection ended, if known, or + * @reason: why the connection ended, if known, or * #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not. - * @param text a localized message describing the disconnection + * @text: a localized message describing the disconnection * in more detail to the user. * @see #purple_connection_error */ @@ -279,57 +279,57 @@ * the core can call protocol's set_status, and it successfully changes * your status, then the account is online. * - * @param gc The connection. - * @param state The connection state. + * @gc: The connection. + * @state: The connection state. */ void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state); /** * Sets the connection flags. * - * @param gc The connection. - * @param flags The flags. + * @gc: The connection. + * @flags: The flags. */ void purple_connection_set_flags(PurpleConnection *gc, PurpleConnectionFlags flags); /** * Sets the connection's displayed name. * - * @param gc The connection. - * @param name The displayed name. + * @gc: The connection. + * @name: The displayed name. */ void purple_connection_set_display_name(PurpleConnection *gc, const char *name); /** * Sets the protocol data for a connection. * - * @param connection The PurpleConnection. - * @param proto_data The protocol data to set for the connection. + * @connection: The PurpleConnection. + * @proto_data: The protocol data to set for the connection. */ void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data); /** * Returns the connection state. * - * @param gc The connection. + * @gc: The connection. * - * @return The connection state. + * Returns: The connection state. */ PurpleConnectionState purple_connection_get_state(const PurpleConnection *gc); /** * Returns the connection flags. * - * @param gc The connection. + * @gc: The connection. * - * @return The connection flags. + * Returns: The connection flags. */ PurpleConnectionFlags purple_connection_get_flags(const PurpleConnection *gc); /** * Returns TRUE if the account is connected, otherwise returns FALSE. * - * @return TRUE if the account is connected, otherwise returns FALSE. + * Returns: TRUE if the account is connected, otherwise returns FALSE. */ #define PURPLE_CONNECTION_IS_CONNECTED(gc) \ (purple_connection_get_state(gc) == PURPLE_CONNECTION_CONNECTED) @@ -337,64 +337,64 @@ /** * Returns the connection's account. * - * @param gc The connection. + * @gc: The connection. * - * @return The connection's account. + * Returns: The connection's account. */ PurpleAccount *purple_connection_get_account(const PurpleConnection *gc); /** * Returns the protocol managing a connection. * - * @param gc The connection. + * @gc: The connection. * - * @return The protocol. + * Returns: The protocol. */ PurpleProtocol *purple_connection_get_protocol(const PurpleConnection *gc); /** * Returns the connection's password. * - * @param gc The connection. + * @gc: The connection. * - * @return The connection's password. + * Returns: The connection's password. */ const char *purple_connection_get_password(const PurpleConnection *gc); /** * Returns a list of active chat conversations on a connection. * - * @param gc The connection. + * @gc: The connection. * - * @return The active chats on the connection. + * Returns: The active chats on the connection. */ GSList *purple_connection_get_active_chats(const PurpleConnection *gc); /** * Returns the connection's displayed name. * - * @param gc The connection. + * @gc: The connection. * - * @return The connection's displayed name. + * Returns: The connection's displayed name. */ const char *purple_connection_get_display_name(const PurpleConnection *gc); /** * Gets the protocol data from a connection. * - * @param connection The PurpleConnection. + * @connection: The PurpleConnection. * - * @return The protocol data for the connection. + * Returns: The protocol data for the connection. */ void *purple_connection_get_protocol_data(const PurpleConnection *gc); /** * Updates the connection progress. * - * @param gc The connection. - * @param text Information on the current step. - * @param step The current step. - * @param count The total number of steps. + * @gc: The connection. + * @text: Information on the current step. + * @step: The current step. + * @count: The total number of steps. */ void purple_connection_update_progress(PurpleConnection *gc, const char *text, size_t step, size_t count); @@ -402,8 +402,8 @@ /** * Displays a connection-specific notice. * - * @param gc The connection. - * @param text The notice text. + * @gc: The connection. + * @text: The notice text. */ void purple_connection_notice(PurpleConnection *gc, const char *text); @@ -411,9 +411,9 @@ * Closes a connection with an error and a human-readable description of the * error. * - * @param gc the connection which is closing. - * @param reason why the connection is closing. - * @param description a localized description of the error (not @c NULL ). + * @gc: the connection which is closing. + * @reason: why the connection is closing. + * @description: a localized description of the error (not @c NULL ). */ void purple_connection_error(PurpleConnection *gc, @@ -424,9 +424,9 @@ * Returns the #PurpleConnectionErrorInfo instance of a connection if an * error exists. * - * @param gc The connection. + * @gc: The connection. * - * @return The #PurpleConnectionErrorInfo instance of the connection if an + * Returns: The #PurpleConnectionErrorInfo instance of the connection if an * error exists, @c NULL otherwise. */ PurpleConnectionErrorInfo * @@ -454,7 +454,7 @@ * <tt> purple_connection_error_is_fatal * (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)</tt> is @c TRUE. * - * @return @c TRUE if the account should not be automatically reconnected, and + * Returns: @c TRUE if the account should not be automatically reconnected, and * @c FALSE otherwise. */ gboolean @@ -464,7 +464,7 @@ * Indicate that a packet was received on the connection. * Set by the protocol to avoid sending unneeded keepalives. * - * @param gc The connection. + * @gc: The connection. */ void purple_connection_update_last_received(PurpleConnection *gc); @@ -484,21 +484,21 @@ * Returns a list of all active connections. This does not * include connections that are in the process of connecting. * - * @constreturn A list of all active connections. + * Returns: (TODO const): A list of all active connections. */ GList *purple_connections_get_all(void); /** * Returns a list of all connections in the process of connecting. * - * @constreturn A list of connecting connections. + * Returns: (TODO const): A list of connecting connections. */ GList *purple_connections_get_connecting(void); /** * Checks if gc is still a valid pointer to a gc. * - * @return @c TRUE if gc is valid. + * Returns: @c TRUE if gc is valid. * * @deprecated Do not use this. Instead, cancel your asynchronous request * when the PurpleConnection is destroyed. @@ -519,14 +519,14 @@ /** * Sets the UI operations structure to be used for connections. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_connections_set_ui_ops(PurpleConnectionUiOps *ops); /** * Returns the UI operations structure used for connections. * - * @return The UI operations structure in use. + * Returns: The UI operations structure in use. */ PurpleConnectionUiOps *purple_connections_get_ui_ops(void); @@ -550,7 +550,7 @@ /** * Returns the handle to the connections subsystem. * - * @return The connections subsystem handle. + * Returns: The connections subsystem handle. */ void *purple_connections_get_handle(void);
--- 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);
--- a/libpurple/conversations.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/conversations.h Wed Jan 29 05:28:33 2014 +0530 @@ -40,14 +40,14 @@ /** * Adds a conversation to the list of conversations. * - * @param conv The conversation. + * @conv: The conversation. */ void purple_conversations_add(PurpleConversation *conv); /** * Removes a conversation from the list of conversations. * - * @param conv The conversation. + * @conv: The conversation. */ void purple_conversations_remove(PurpleConversation *conv); @@ -56,9 +56,9 @@ * account. This function only updates the conversation cache. It is the * caller's responsibility to actually update the conversation. * - * @param conv The conversation. - * @param name The new name. If no change, use @c NULL. - * @param account The new account. If no change, use @c NULL. + * @conv: The conversation. + * @name: The new name. If no change, use @c NULL. + * @account: The new account. If no change, use @c NULL. */ void purple_conversations_update_cache(PurpleConversation *conv, const char *name, PurpleAccount *account); @@ -68,31 +68,31 @@ * * This list includes both IMs and chats. * - * @constreturn A GList of all conversations. + * Returns: (TODO const): A GList of all conversations. */ GList *purple_conversations_get_all(void); /** * Returns a list of all IMs. * - * @constreturn A GList of all IMs. + * Returns: (TODO const): A GList of all IMs. */ GList *purple_conversations_get_ims(void); /** * Returns a list of all chats. * - * @constreturn A GList of all chats. + * Returns: (TODO const): A GList of all chats. */ GList *purple_conversations_get_chats(void); /** * Finds a conversation of any type with the specified name and Purple account. * - * @param name The name of the conversation. - * @param account The account associated with the conversation. + * @name: The name of the conversation. + * @account: The account associated with the conversation. * - * @return The conversation if found, or @c NULL otherwise. + * Returns: The conversation if found, or @c NULL otherwise. */ PurpleConversation *purple_conversations_find_with_account(const char *name, const PurpleAccount *account); @@ -100,10 +100,10 @@ /** * Finds an IM with the specified name and Purple account. * - * @param name The name of the conversation. - * @param account The account associated with the conversation. + * @name: The name of the conversation. + * @account: The account associated with the conversation. * - * @return The conversation if found, or @c NULL otherwise. + * Returns: The conversation if found, or @c NULL otherwise. */ PurpleIMConversation *purple_conversations_find_im_with_account(const char *name, const PurpleAccount *account); @@ -111,10 +111,10 @@ /** * Finds a chat with the specified name and Purple account. * - * @param name The name of the conversation. - * @param account The account associated with the conversation. + * @name: The name of the conversation. + * @account: The account associated with the conversation. * - * @return The conversation if found, or @c NULL otherwise. + * Returns: The conversation if found, or @c NULL otherwise. */ PurpleChatConversation *purple_conversations_find_chat_with_account(const char *name, const PurpleAccount *account); @@ -122,31 +122,31 @@ /** * Finds a chat with the specified chat ID. * - * @param gc The purple_connection. - * @param id The chat ID. + * @gc: The purple_connection. + * @id: The chat ID. * - * @return The chat conversation. + * Returns: The chat conversation. */ PurpleChatConversation *purple_conversations_find_chat(const PurpleConnection *gc, int id); /** * Sets the default conversation UI operations structure. * - * @param ops The UI conversation operations structure. + * @ops: The UI conversation operations structure. */ void purple_conversations_set_ui_ops(PurpleConversationUiOps *ops); /** * Gets the default conversation UI operations structure. * - * @return The UI conversation operations structure. + * Returns: The UI conversation operations structure. */ PurpleConversationUiOps *purple_conversations_get_ui_ops(void); /** * Returns the conversation subsystem handle. * - * @return The conversation subsystem handle. + * Returns: The conversation subsystem handle. */ void *purple_conversations_get_handle(void);
--- a/libpurple/conversationtypes.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/conversationtypes.h Wed Jan 29 05:28:33 2014 +0530 @@ -174,11 +174,11 @@ /** * Creates a new IM conversation. * - * @param account The account opening the conversation window on the purple + * @account: The account opening the conversation window on the purple * user's end. - * @param name Name of the buddy. + * @name: Name of the buddy. * - * @return The new conversation. + * Returns: The new conversation. */ PurpleIMConversation *purple_im_conversation_new(PurpleAccount *account, const char *name); @@ -189,8 +189,8 @@ * This should only be called from within Purple. You probably want to * call purple_buddy_icon_set_data(). * - * @param im The IM. - * @param icon The buddy icon. + * @im: The IM. + * @icon: The buddy icon. * * @see purple_buddy_icon_set_data() */ @@ -199,34 +199,34 @@ /** * Returns the IM's buddy icon. * - * @param im The IM. + * @im: The IM. * - * @return The buddy icon. + * Returns: The buddy icon. */ PurpleBuddyIcon *purple_im_conversation_get_icon(const PurpleIMConversation *im); /** * Sets the IM's typing state. * - * @param im The IM. - * @param state The typing state. + * @im: The IM. + * @state: The typing state. */ void purple_im_conversation_set_typing_state(PurpleIMConversation *im, PurpleIMTypingState state); /** * Returns the IM's typing state. * - * @param im The IM. + * @im: The IM. * - * @return The IM's typing state. + * Returns: The IM's typing state. */ PurpleIMTypingState purple_im_conversation_get_typing_state(const PurpleIMConversation *im); /** * Starts the IM's typing timeout. * - * @param im The IM. - * @param timeout How long in seconds to wait before setting the typing state + * @im: The IM. + * @timeout: How long in seconds to wait before setting the typing state * to PURPLE_IM_NOT_TYPING. */ void purple_im_conversation_start_typing_timeout(PurpleIMConversation *im, int timeout); @@ -234,16 +234,16 @@ /** * Stops the IM's typing timeout. * - * @param im The IM. + * @im: The IM. */ void purple_im_conversation_stop_typing_timeout(PurpleIMConversation *im); /** * Returns the IM's typing timeout. * - * @param im The IM. + * @im: The IM. * - * @return The timeout. + * Returns: The timeout. */ guint purple_im_conversation_get_typing_timeout(const PurpleIMConversation *im); @@ -253,8 +253,8 @@ * typing after this quiet-period, then another PURPLE_IM_TYPING message * will be sent. * - * @param im The IM. - * @param val The number of seconds to wait before allowing another + * @im: The IM. + * @val: The number of seconds to wait before allowing another * PURPLE_IM_TYPING message to be sent to the user. Or 0 to * not send another PURPLE_IM_TYPING message. */ @@ -263,9 +263,9 @@ /** * Returns the time after which another PURPLE_IM_TYPING message should be sent. * - * @param im The IM. + * @im: The IM. * - * @return The time in seconds since the epoch. Or 0 if no additional + * Returns: The time in seconds since the epoch. Or 0 if no additional * PURPLE_IM_TYPING message should be sent. */ time_t purple_im_conversation_get_type_again(const PurpleIMConversation *im); @@ -273,30 +273,30 @@ /** * Starts the IM's type again timeout. * - * @param im The IM. + * @im: The IM. */ void purple_im_conversation_start_send_typed_timeout(PurpleIMConversation *im); /** * Stops the IM's type again timeout. * - * @param im The IM. + * @im: The IM. */ void purple_im_conversation_stop_send_typed_timeout(PurpleIMConversation *im); /** * Returns the IM's type again timeout interval. * - * @param im The IM. + * @im: The IM. * - * @return The type again timeout interval. + * Returns: The type again timeout interval. */ guint purple_im_conversation_get_send_typed_timeout(const PurpleIMConversation *im); /** * Updates the visual typing notification for an IM conversation. * - * @param im The IM. + * @im: The IM. */ void purple_im_conversation_update_typing(PurpleIMConversation *im); @@ -315,11 +315,11 @@ /** * Creates a new chat conversation. * - * @param account The account opening the conversation window on the purple + * @account: The account opening the conversation window on the purple * user's end. - * @param name The name of the conversation. + * @name: The name of the conversation. * - * @return The new conversation. + * Returns: The new conversation. */ PurpleChatConversation *purple_chat_conversation_new(PurpleAccount *account, const char *name); @@ -328,44 +328,44 @@ * Returns a list of users in the chat room. The members of the list * are PurpleChatUser objects. * - * @param chat The chat. + * @chat: The chat. * - * @constreturn The list of users. + * Returns: (TODO const): The list of users. */ GList *purple_chat_conversation_get_users(const PurpleChatConversation *chat); /** * Ignores a user in a chat room. * - * @param chat The chat. - * @param name The name of the user. + * @chat: The chat. + * @name: The name of the user. */ void purple_chat_conversation_ignore(PurpleChatConversation *chat, const char *name); /** * Unignores a user in a chat room. * - * @param chat The chat. - * @param name The name of the user. + * @chat: The chat. + * @name: The name of the user. */ void purple_chat_conversation_unignore(PurpleChatConversation *chat, const char *name); /** * Sets the list of ignored users in the chat room. * - * @param chat The chat. - * @param ignored The list of ignored users. + * @chat: The chat. + * @ignored: The list of ignored users. * - * @return The list passed. + * Returns: The list passed. */ GList *purple_chat_conversation_set_ignored(PurpleChatConversation *chat, GList *ignored); /** * Returns the list of ignored users in the chat room. * - * @param chat The chat. + * @chat: The chat. * - * @constreturn The list of ignored users. + * Returns: (TODO const): The list of ignored users. */ GList *purple_chat_conversation_get_ignored(const PurpleChatConversation *chat); @@ -377,10 +377,10 @@ * returned. The username passed to the function does not have to have this * formatting. * - * @param chat The chat. - * @param user The user to check in the ignore list. + * @chat: The chat. + * @user: The user to check in the ignore list. * - * @return The ignored user if found, complete with prefixes, or @c NULL + * Returns: The ignored user if found, complete with prefixes, or @c NULL * if not found. */ const char *purple_chat_conversation_get_ignored_user(const PurpleChatConversation *chat, @@ -389,10 +389,10 @@ /** * Returns @c TRUE if the specified user is ignored. * - * @param chat The chat. - * @param user The user. + * @chat: The chat. + * @user: The user. * - * @return @c TRUE if the user is in the ignore list; @c FALSE otherwise. + * Returns: @c TRUE if the user is in the ignore list; @c FALSE otherwise. */ gboolean purple_chat_conversation_is_ignored_user(const PurpleChatConversation *chat, const char *user); @@ -400,9 +400,9 @@ /** * Sets the chat room's topic. * - * @param chat The chat. - * @param who The user that set the topic. - * @param topic The topic. + * @chat: The chat. + * @who: The user that set the topic. + * @topic: The topic. */ void purple_chat_conversation_set_topic(PurpleChatConversation *chat, const char *who, const char *topic); @@ -410,46 +410,46 @@ /** * Returns the chat room's topic. * - * @param chat The chat. + * @chat: The chat. * - * @return The chat's topic. + * Returns: The chat's topic. */ const char *purple_chat_conversation_get_topic(const PurpleChatConversation *chat); /** * Returns who set the chat room's topic. * - * @param chat The chat. + * @chat: The chat. * - * @return Who set the topic. + * Returns: Who set the topic. */ const char *purple_chat_conversation_get_topic_who(const PurpleChatConversation *chat); /** * Sets the chat room's ID. * - * @param chat The chat. - * @param id The ID. + * @chat: The chat. + * @id: The ID. */ void purple_chat_conversation_set_id(PurpleChatConversation *chat, int id); /** * Returns the chat room's ID. * - * @param chat The chat. + * @chat: The chat. * - * @return The ID. + * Returns: The ID. */ int purple_chat_conversation_get_id(const PurpleChatConversation *chat); /** * Adds a user to a chat. * - * @param chat The chat. - * @param user The user to add. - * @param extra_msg An extra message to display with the join message. - * @param flags The users flags - * @param new_arrival Decides whether or not to show a join notice. + * @chat: The chat. + * @user: The user to add. + * @extra_msg: An extra message to display with the join message. + * @flags: The users flags + * @new_arrival: Decides whether or not to show a join notice. */ void purple_chat_conversation_add_user(PurpleChatConversation *chat, const char *user, const char *extra_msg, PurpleChatUserFlags flags, @@ -461,16 +461,16 @@ * The data is copied from @a users, @a extra_msgs, and @a flags, so it is up to * the caller to free this list after calling this function. * - * @param chat The chat. - * @param users The list of users to add. - * @param extra_msgs An extra message to display with the join message for each + * @chat: The chat. + * @users: The list of users to add. + * @extra_msgs: An extra message to display with the join message for each * user. This list may be shorter than @a 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 @c NULL and none of the users will have an * extra message. - * @param flags The list of flags for each user. - * @param new_arrivals Decides whether or not to show join notices. + * @flags: The list of flags for each user. + * @new_arrivals: Decides whether or not to show join notices. */ void purple_chat_conversation_add_users(PurpleChatConversation *chat, GList *users, GList *extra_msgs, GList *flags, gboolean new_arrivals); @@ -478,9 +478,9 @@ /** * Renames a user in a chat. * - * @param chat The chat. - * @param old_user The old username. - * @param new_user The new username. + * @chat: The chat. + * @old_user: The old username. + * @new_user: The new username. */ void purple_chat_conversation_rename_user(PurpleChatConversation *chat, const char *old_user, const char *new_user); @@ -490,9 +490,9 @@ * * It is up to the developer to free this list after calling this function. * - * @param chat The chat. - * @param user The user that is being removed. - * @param reason The optional reason given for the removal. Can be @c NULL. + * @chat: The chat. + * @user: The user that is being removed. + * @reason: The optional reason given for the removal. Can be @c NULL. */ void purple_chat_conversation_remove_user(PurpleChatConversation *chat, const char *user, const char *reason); @@ -500,9 +500,9 @@ /** * Removes a list of users from a chat, optionally with a single reason. * - * @param chat The chat. - * @param users The users that are being removed. - * @param reason The optional reason given for the removal. Can be @c NULL. + * @chat: The chat. + * @users: The users that are being removed. + * @reason: The optional reason given for the removal. Can be @c NULL. */ void purple_chat_conversation_remove_users(PurpleChatConversation *chat, GList *users, const char *reason); @@ -510,10 +510,10 @@ /** * Checks if a user is in a chat * - * @param chat The chat. - * @param user The user to look for. + * @chat: The chat. + * @user: The user to look for. * - * @return TRUE if the user is in the chat, FALSE if not + * Returns: TRUE if the user is in the chat, FALSE if not */ gboolean purple_chat_conversation_has_user(PurpleChatConversation *chat, const char *user); @@ -521,15 +521,15 @@ /** * Clears all users from a chat. * - * @param chat The chat. + * @chat: The chat. */ void purple_chat_conversation_clear_users(PurpleChatConversation *chat); /** * Sets your nickname (used for hilighting) for a chat. * - * @param chat The chat. - * @param nick The nick. + * @chat: The chat. + * @nick: The nick. */ void purple_chat_conversation_set_nick(PurpleChatConversation *chat, const char *nick); @@ -537,8 +537,8 @@ /** * Gets your nickname (used for hilighting) for a chat. * - * @param chat The chat. - * @return The nick. + * @chat: The chat. + * Returns: The nick. */ const char *purple_chat_conversation_get_nick(PurpleChatConversation *chat); @@ -546,15 +546,15 @@ * Lets the core know we left a chat, without destroying it. * Called from serv_got_chat_left(). * - * @param chat The chat. + * @chat: The chat. */ void purple_chat_conversation_leave(PurpleChatConversation *chat); /** * Find a chat user in a chat * - * @param chat The chat. - * @param name The name of the chat user to find. + * @chat: The chat. + * @name: The name of the chat user to find. */ PurpleChatUser *purple_chat_conversation_find_user(PurpleChatConversation *chat, const char *name); @@ -564,10 +564,10 @@ * The user will be prompted to enter the user's name or a message if one is * not given. * - * @param chat The chat. - * @param user The user to invite to the chat. - * @param message The message to send with the invitation. - * @param confirm Prompt before sending the invitation. The user is always + * @chat: The chat. + * @user: The user to invite to the chat. + * @message: The message to send with the invitation. + * @confirm: Prompt before sending the invitation. The user is always * prompted if either \a user or \a message is @c NULL. */ void purple_chat_conversation_invite_user(PurpleChatConversation *chat, @@ -577,9 +577,9 @@ * Returns true if we're no longer in this chat, * and just left the window open. * - * @param chat The chat. + * @chat: The chat. * - * @return @c TRUE if we left the chat already, @c FALSE if + * Returns: @c TRUE if we left the chat already, @c FALSE if * we're still there. */ gboolean purple_chat_conversation_has_left(PurpleChatConversation *chat); @@ -599,8 +599,8 @@ /** * Set the chat conversation associated with this chat user. * - * @param cb The chat user - * @param chat The chat conversation that the buddy belongs to. + * @cb: The chat user + * @chat: The chat conversation that the buddy belongs to. */ void purple_chat_user_set_chat(PurpleChatUser *cb, PurpleChatConversation *chat); @@ -608,21 +608,21 @@ /** * Get the chat conversation associated with this chat user. * - * @param cb The chat user. + * @cb: The chat user. * - * @return The chat conversation that the buddy belongs to. + * Returns: The chat conversation that the buddy belongs to. */ PurpleChatConversation *purple_chat_user_get_chat(const PurpleChatUser *cb); /** * Creates a new chat user * - * @param chat The chat that the buddy belongs to. - * @param name The name. - * @param alias The alias. - * @param flags The flags. + * @chat: The chat that the buddy belongs to. + * @name: The name. + * @alias: The alias. + * @flags: The flags. * - * @return The new chat user + * Returns: The new chat user */ PurpleChatUser *purple_chat_user_new(PurpleChatConversation *chat, const char *name, const char *alias, PurpleChatUserFlags flags); @@ -630,17 +630,17 @@ /** * Set the UI data associated with this chat user. * - * @param cb The chat user - * @param ui_data A pointer to associate with this chat user. + * @cb: The chat user + * @ui_data: A pointer to associate with this chat user. */ void purple_chat_user_set_ui_data(PurpleChatUser *cb, gpointer ui_data); /** * Get the UI data associated with this chat user. * - * @param cb The chat user. + * @cb: The chat user. * - * @return The UI data associated with this chat user. This is a + * Returns: 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. */ @@ -649,44 +649,44 @@ /** * Get the alias of a chat user * - * @param cb The chat user. + * @cb: The chat user. * - * @return The alias of the chat user. + * Returns: The alias of the chat user. */ const char *purple_chat_user_get_alias(const PurpleChatUser *cb); /** * Get the name of a chat user * - * @param cb The chat user. + * @cb: The chat user. * - * @return The name of the chat user. + * Returns: The name of the chat user. */ const char *purple_chat_user_get_name(const PurpleChatUser *cb); /** * Set the flags of a chat user. * - * @param cb The chat user. - * @param flags The new flags. + * @cb: The chat user. + * @flags: The new flags. */ void purple_chat_user_set_flags(PurpleChatUser *cb, PurpleChatUserFlags flags); /** * Get the flags of a chat user. * - * @param cb The chat user. + * @cb: The chat user. * - * @return The flags of the chat user. + * Returns: The flags of the chat user. */ PurpleChatUserFlags purple_chat_user_get_flags(const PurpleChatUser *cb); /** * Indicates if this chat user is on the buddy list. * - * @param cb The chat user. + * @cb: The chat user. * - * @return TRUE if the chat user is on the buddy list. + * Returns: TRUE if the chat user is on the buddy list. */ gboolean purple_chat_user_is_buddy(const PurpleChatUser *cb);
--- a/libpurple/core.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/core.h Wed Jan 29 05:28:33 2014 +0530 @@ -87,10 +87,10 @@ * * This will setup preferences for all the core subsystems. * - * @param ui The ID of the UI using the core. This should be a + * @ui: The ID of the UI using the core. This should be a * unique ID, registered with the purple team. * - * @return @c TRUE if successful, or @c FALSE otherwise. + * Returns: @c TRUE if successful, or @c FALSE otherwise. */ gboolean purple_core_init(const char *ui); @@ -124,7 +124,7 @@ /** * Returns the version of the core library. * - * @return The version of the core library. + * Returns: The version of the core library. */ const char *purple_core_get_version(void); @@ -132,7 +132,7 @@ * Returns the ID of the UI that is using the core, as passed to * purple_core_init(). * - * @return The ID of the UI that is currently using the core. + * Returns: The ID of the UI that is currently using the core. */ const char *purple_core_get_ui(void); @@ -146,14 +146,14 @@ /** * Sets the UI ops for the core. * - * @param ops A UI ops structure for the core. + * @ops: A UI ops structure for the core. */ void purple_core_set_ui_ops(PurpleCoreUiOps *ops); /** * Returns the UI ops for the core. * - * @return The core's UI ops structure. + * Returns: The core's UI ops structure. */ PurpleCoreUiOps *purple_core_get_ui_ops(void); @@ -163,7 +163,7 @@ * so whether that process is using the same configuration directory as this * process. * - * @return @c TRUE if this is the first instance of libpurple running; + * Returns: @c TRUE if this is the first instance of libpurple running; * @c FALSE if there is another instance running. */ gboolean purple_core_ensure_single_instance(void); @@ -193,7 +193,7 @@ * * </dl> * - * @return A GHashTable with strings for keys and values. This + * Returns: A GHashTable with strings for keys and values. This * hash table must not be freed and should not be modified. * */
--- a/libpurple/dbus-server.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/dbus-server.h Wed Jan 29 05:28:33 2014 +0530 @@ -121,8 +121,8 @@ /** Registers a typed pointer. - @param node The pointer to register. - @param type Type of that pointer. + @node: The pointer to register. + @type: Type of that pointer. */ void purple_dbus_register_pointer(gpointer node, PurpleDBusType *type); @@ -130,7 +130,7 @@ Unregisters a pointer previously registered with purple_dbus_register_pointer. - @param node The pointer to register. + @node: The pointer to register. */ void purple_dbus_unregister_pointer(gpointer node); @@ -139,10 +139,10 @@ /** Emits a dbus signal. - @param name The name of the signal ("bla-bla-blaa") - @param num_values The number of parameters. - @param types Array of GTypes representing the types of the parameters. - @param vargs A va_list containing the actual parameters. + @name: The name of the signal ("bla-bla-blaa") + @num_values: The number of parameters. + @types: Array of GTypes representing the types of the parameters. + @vargs: A va_list containing the actual parameters. */ void purple_dbus_signal_emit_purple(const char *name, int num_values, GType *types, va_list vargs); @@ -156,7 +156,7 @@ * PURPLE_DBUS_RETURN_FALSE_IF_DISABLED macro to short-circuit * initialization if Purple's D-BUS subsystem is not running. * - * @return If the D-BUS subsystem started with no problems then this + * Returns: If the D-BUS subsystem started with no problems then this * will return NULL and everything will be hunky dory. If * there was an error initializing the D-BUS subsystem then * this will return an error message explaining why. @@ -166,7 +166,7 @@ /** * Returns the dbus subsystem handle. * - * @return The dbus subsystem handle. + * Returns: The dbus subsystem handle. */ void *purple_dbus_get_handle(void);
--- a/libpurple/debug.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/debug.h Wed Jan 29 05:28:33 2014 +0530 @@ -68,9 +68,9 @@ /** * Outputs debug information. * - * @param level The debug level. - * @param category The category (or @c NULL). - * @param format The format string. + * @level: The debug level. + * @category: The category (or @c NULL). + * @format: The format string. */ void purple_debug(PurpleDebugLevel level, const char *category, const char *format, ...) G_GNUC_PRINTF(3, 4); @@ -81,8 +81,8 @@ * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_MISC as * the level. * - * @param category The category (or @c NULL). - * @param format The format string. + * @category: The category (or @c NULL). + * @format: The format string. * * @see purple_debug() */ @@ -94,8 +94,8 @@ * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_INFO as * the level. * - * @param category The category (or @c NULL). - * @param format The format string. + * @category: The category (or @c NULL). + * @format: The format string. * * @see purple_debug() */ @@ -107,8 +107,8 @@ * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_WARNING as * the level. * - * @param category The category (or @c NULL). - * @param format The format string. + * @category: The category (or @c NULL). + * @format: The format string. * * @see purple_debug() */ @@ -120,8 +120,8 @@ * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_ERROR as * the level. * - * @param category The category (or @c NULL). - * @param format The format string. + * @category: The category (or @c NULL). + * @format: The format string. * * @see purple_debug() */ @@ -133,8 +133,8 @@ * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_ERROR as * the level. * - * @param category The category (or @c NULL). - * @param format The format string. + * @category: The category (or @c NULL). + * @format: The format string. * * @see purple_debug() */ @@ -143,14 +143,14 @@ /** * Enable or disable printing debug output to the console. * - * @param enabled TRUE to enable debug output or FALSE to disable it. + * @enabled: TRUE to enable debug output or FALSE to disable it. */ void purple_debug_set_enabled(gboolean enabled); /** * Check if console debug output is enabled. * - * @return TRUE if debugging is enabled, FALSE if it is not. + * Returns: TRUE if debugging is enabled, FALSE if it is not. */ gboolean purple_debug_is_enabled(void); @@ -159,14 +159,14 @@ * by #purple_debug_init, but there are cases where this can be useful for * plugins. * - * @param verbose TRUE to enable verbose debugging or FALSE to disable it. + * @verbose: TRUE to enable verbose debugging or FALSE to disable it. */ void purple_debug_set_verbose(gboolean verbose); /** * Check if verbose logging is enabled. * - * @return TRUE if verbose debugging is enabled, FALSE if it is not. + * Returns: TRUE if verbose debugging is enabled, FALSE if it is not. */ gboolean purple_debug_is_verbose(void); @@ -175,7 +175,7 @@ * by #purple_debug_init, but there are cases where this can be useful for * plugins. * - * @param unsafe TRUE to enable debug logging of messages that could + * @unsafe: TRUE to enable debug logging of messages that could * potentially contain passwords and other sensitive information. * FALSE to disable it. */ @@ -184,7 +184,7 @@ /** * Check if unsafe debugging is enabled. Defaults to FALSE. * - * @return TRUE if the debug logging of all messages is enabled, FALSE + * Returns: TRUE if the debug logging of all messages is enabled, FALSE * if messages that could potentially contain passwords and other * sensitive information are not logged. */ @@ -193,7 +193,7 @@ /** * Enable or disable colored output for bash console. * - * @param colored TRUE to enable colored output, FALSE to disable it. + * @colored: TRUE to enable colored output, FALSE to disable it. */ void purple_debug_set_colored(gboolean colored); @@ -208,7 +208,7 @@ * Sets the UI operations structure to be used when outputting debug * information. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_debug_set_ui_ops(PurpleDebugUiOps *ops); @@ -216,7 +216,7 @@ * Returns the UI operations structure used when outputting debug * information. * - * @return The UI operations structure in use. + * Returns: The UI operations structure in use. */ PurpleDebugUiOps *purple_debug_get_ui_ops(void);
--- a/libpurple/desktopitem.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/desktopitem.h Wed Jan 29 05:28:33 2014 +0530 @@ -118,9 +118,9 @@ /** * This function loads 'filename' and turns it into a PurpleDesktopItem. * - * @param filename The filename or directory path to load the PurpleDesktopItem from + * @filename: The filename or directory path to load the PurpleDesktopItem from * - * @return The newly loaded item, or NULL on error. + * Returns: The newly loaded item, or NULL on error. */ PurpleDesktopItem *purple_desktop_item_new_from_file (const char *filename); @@ -131,9 +131,9 @@ * The type usually indicates how the desktop item should be handeled and * how the 'Exec' field should be handeled. * - * @param item A desktop item + * @item: A desktop item * - * @return The type of the specified 'item'. The returned memory + * Returns: The type of the specified 'item'. The returned memory * remains owned by the PurpleDesktopItem and should not be freed. */ PurpleDesktopItemType purple_desktop_item_get_entry_type (const PurpleDesktopItem *item); @@ -141,10 +141,10 @@ /** * Gets the value of an attribute of the item, as a string. * - * @param item A desktop item - * @param attr The attribute to look for + * @item: A desktop item + * @attr: The attribute to look for * - * @return The value of the specified item attribute. + * Returns: The value of the specified item attribute. */ const char *purple_desktop_item_get_string (const PurpleDesktopItem *item, const char *attr); @@ -153,9 +153,9 @@ * Creates a copy of a PurpleDesktopItem. The new copy has a refcount of 1. * Note: Section stack is NOT copied. * - * @param item The item to be copied + * @item: The item to be copied * - * @return The new copy + * Returns: The new copy */ PurpleDesktopItem *purple_desktop_item_copy (const PurpleDesktopItem *item); @@ -163,7 +163,7 @@ * Decreases the reference count of the specified item, and destroys * the item if there are no more references left. * - * @param item A desktop item + * @item: A desktop item */ void purple_desktop_item_unref (PurpleDesktopItem *item);
--- a/libpurple/dnsquery.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/dnsquery.h Wed Jan 29 05:28:33 2014 +0530 @@ -87,13 +87,13 @@ /** * Perform an asynchronous DNS query. * - * @param account The account that the query is being done for (or NULL) - * @param hostname The hostname to resolve. - * @param port A port number which is stored in the struct sockaddr. - * @param callback The callback function to call after resolving. - * @param data Extra data to pass to the callback function. + * @account: The account that the query is being done for (or NULL) + * @hostname: The hostname to resolve. + * @port: A port number which is stored in the struct sockaddr. + * @callback: The callback function to call after resolving. + * @data: Extra data to pass to the callback function. * - * @return NULL if there was an error, otherwise return a reference to + * Returns: NULL if there was an error, otherwise return a reference to * a data structure that can be used to cancel the pending * DNS query, if needed. * @@ -103,7 +103,7 @@ /** * Cancel a DNS query and destroy the associated data structure. * - * @param query_data The DNS query to cancel. This data structure + * @query_data: The DNS query to cancel. This data structure * is freed by this function. */ void purple_dnsquery_destroy(PurpleDnsQueryData *query_data); @@ -113,7 +113,7 @@ * resolve. The UI operations need only be set if the UI wants to * handle the resolve itself; otherwise, leave it as NULL. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_dnsquery_set_ui_ops(PurpleDnsQueryUiOps *ops); @@ -121,23 +121,23 @@ * Returns the UI operations structure to be used when doing a DNS * resolve. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleDnsQueryUiOps *purple_dnsquery_get_ui_ops(void); /** * Get the host associated with a PurpleDnsQueryData * - * @param query_data The DNS query - * @return The host. + * @query_data: The DNS query + * Returns: The host. */ char *purple_dnsquery_get_host(PurpleDnsQueryData *query_data); /** * Get the port associated with a PurpleDnsQueryData * - * @param query_data The DNS query - * @return The port. + * @query_data: The DNS query + * Returns: The port. */ unsigned short purple_dnsquery_get_port(PurpleDnsQueryData *query_data);
--- a/libpurple/dnssrv.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/dnssrv.h Wed Jan 29 05:28:33 2014 +0530 @@ -78,7 +78,7 @@ } PurpleSrvTxtQueryUiOps; /** - * @param resp An array of PurpleSrvResponse of size results. The array + * @resp: An array of PurpleSrvResponse of size results. The array * is sorted based on the order described in the DNS SRV RFC. * Users of this API should try each record in resp in order, * starting at the beginning. @@ -88,8 +88,8 @@ /** * Callback that returns the data retrieved from a DNS TXT lookup. * - * @param responses A GList of PurpleTxtResponse objects. - * @param data The extra data passed to purple_txt_resolve. + * @responses: A GList of PurpleTxtResponse objects. + * @data: The extra data passed to purple_txt_resolve. */ typedef void (*PurpleTxtCallback)(GList *responses, gpointer data); @@ -98,14 +98,14 @@ /** * Queries an SRV record. * - * @param account The account that the query is being done for (or NULL) - * @param protocol Name of the protocol (e.g. "sip") - * @param transport Name of the transport ("tcp" or "udp") - * @param domain Domain name to query (e.g. "blubb.com") - * @param cb A callback which will be called with the results - * @param extradata Extra data to be passed to the callback + * @account: The account that the query is being done for (or NULL) + * @protocol: Name of the protocol (e.g. "sip") + * @transport: Name of the transport ("tcp" or "udp") + * @domain: Domain name to query (e.g. "blubb.com") + * @cb: A callback which will be called with the results + * @extradata: Extra data to be passed to the callback * - * @return NULL if there was an error, otherwise return a reference to + * Returns: NULL if there was an error, otherwise return a reference to * a data structure that can be used to cancel the pending * DNS query, if needed. */ @@ -114,13 +114,13 @@ /** * Queries an TXT record. * - * @param account The account that the query is being done for (or NULL) - * @param owner Name of the protocol (e.g. "_xmppconnect") - * @param domain Domain name to query (e.g. "blubb.com") - * @param cb A callback which will be called with the results - * @param extradata Extra data to be passed to the callback + * @account: The account that the query is being done for (or NULL) + * @owner: Name of the protocol (e.g. "_xmppconnect") + * @domain: Domain name to query (e.g. "blubb.com") + * @cb: A callback which will be called with the results + * @extradata: Extra data to be passed to the callback * - * @return NULL if there was an error, otherwise return a reference to + * Returns: NULL if there was an error, otherwise return a reference to * a data structure that can be used to cancel the pending * DNS query, if needed. */ @@ -129,23 +129,23 @@ /** * Get the value of the current TXT record. * - * @param response The TXT response record + * @response: The TXT response record * - * @return The value of the current TXT record. + * Returns: The value of the current TXT record. */ const gchar *purple_txt_response_get_content(PurpleTxtResponse *response); /** * Destroy a TXT DNS response object. * - * @param response The PurpleTxtResponse to destroy. + * @response: The PurpleTxtResponse to destroy. */ void purple_txt_response_destroy(PurpleTxtResponse *response); /** * Cancel a SRV/TXT query and destroy the associated data structure. * - * @param query_data The SRV/TXT query to cancel. This data structure + * @query_data: The SRV/TXT query to cancel. This data structure * is freed by this function. */ void purple_srv_txt_query_destroy(PurpleSrvTxtQueryData *query_data); @@ -155,7 +155,7 @@ * resolve. The UI operations need only be set if the UI wants to * handle the resolve itself; otherwise, leave it as NULL. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_srv_txt_query_set_ui_ops(PurpleSrvTxtQueryUiOps *ops); @@ -163,23 +163,23 @@ * Returns the UI operations structure to be used when doing a SRV/TXT * resolve. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleSrvTxtQueryUiOps *purple_srv_txt_query_get_ui_ops(void); /** * Get the query from a PurpleSrvTxtQueryData * - * @param query_data The SRV/TXT query - * @return The query. + * @query_data: The SRV/TXT query + * Returns: The query. */ char *purple_srv_txt_query_get_query(PurpleSrvTxtQueryData *query_data); /** * Get the type from a PurpleSrvTxtQueryData (TXT or SRV) * - * @param query_data The query - * @return The query. + * @query_data: The query + * Returns: The query. */ int purple_srv_txt_query_get_type(PurpleSrvTxtQueryData *query_data);
--- a/libpurple/e2ee.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/e2ee.h Wed Jan 29 05:28:33 2014 +0530 @@ -48,9 +48,9 @@ * * State objects are global (shared between multiple conversations). * - * @param provider The E2EE provider that created this state. + * @provider: The E2EE provider that created this state. * - * @return New E2EE state. + * Returns: New E2EE state. */ PurpleE2eeState * purple_e2ee_state_new(PurpleE2eeProvider *provider); @@ -58,7 +58,7 @@ /** * Increment the reference count. * - * @param state The E2EE state. + * @state: The E2EE state. */ void purple_e2ee_state_ref(PurpleE2eeState *state); @@ -68,9 +68,9 @@ * * If the reference count reaches zero, the state will be freed. * - * @param state The E2EE state. + * @state: The E2EE state. * - * @return @a state or @c NULL if the reference count reached zero. + * Returns: @a state or @c NULL if the reference count reached zero. */ PurpleE2eeState * purple_e2ee_state_unref(PurpleE2eeState *state); @@ -78,9 +78,9 @@ /** * Gets the provider of specified E2EE state. * - * @param state The E2EE state. + * @state: The E2EE state. * - * @return The provider for this state. + * Returns: The provider for this state. */ PurpleE2eeProvider * purple_e2ee_state_get_provider(PurpleE2eeState *state); @@ -88,8 +88,8 @@ /** * Sets the name for the E2EE state. * - * @param state The E2EE state. - * @param name The localized name. + * @state: The E2EE state. + * @name: The localized name. */ void purple_e2ee_state_set_name(PurpleE2eeState *state, const gchar *name); @@ -97,9 +97,9 @@ /** * Gets the name of the E2EE state. * - * @param state The E2EE state. + * @state: The E2EE state. * - * @return The localized name. + * Returns: The localized name. */ const gchar * purple_e2ee_state_get_name(PurpleE2eeState *state); @@ -107,8 +107,8 @@ /** * Sets the icon for the E2EE state. * - * @param state The E2EE state. - * @param stock_icon The stock icon identifier. + * @state: The E2EE state. + * @stock_icon: The stock icon identifier. */ void purple_e2ee_state_set_stock_icon(PurpleE2eeState *state, @@ -117,9 +117,9 @@ /** * Gets the icon of the E2EE state. * - * @param state The E2EE state. + * @state: The E2EE state. * - * @return The stock icon identifier. + * Returns: The stock icon identifier. */ const gchar * purple_e2ee_state_get_stock_icon(PurpleE2eeState *state); @@ -135,7 +135,7 @@ /** * Creates new E2EE provider. * - * @return New E2EE provider. + * Returns: New E2EE provider. */ PurpleE2eeProvider * purple_e2ee_provider_new(void); @@ -145,7 +145,7 @@ * * The provider have to be unregistered prior. * - * @param provider The provider. + * @provider: The provider. */ void purple_e2ee_provider_free(PurpleE2eeProvider *provider); @@ -156,9 +156,9 @@ * Currently, there is no support for multiple E2EE providers - only the first * one is registered. * - * @param provider The E2EE provider. + * @provider: The E2EE provider. * - * @return @c TRUE, if the provider was successfully registered, + * Returns: @c TRUE, if the provider was successfully registered, * @c FALSE otherwise. */ gboolean @@ -167,7 +167,7 @@ /** * Unregisters the E2EE provider. * - * @param provider The E2EE provider. + * @provider: The E2EE provider. */ void purple_e2ee_provider_unregister(PurpleE2eeProvider *provider); @@ -175,7 +175,7 @@ /** * Gets main E2EE provider. * - * @return The main E2EE provider. + * Returns: The main E2EE provider. */ PurpleE2eeProvider * purple_e2ee_provider_get_main(void); @@ -183,8 +183,8 @@ /** * Sets the name for the E2EE provider. * - * @param provider The E2EE provider. - * @param name The localized name. + * @provider: The E2EE provider. + * @name: The localized name. */ void purple_e2ee_provider_set_name(PurpleE2eeProvider *provider, const gchar *name); @@ -192,9 +192,9 @@ /** * Gets the name of the E2EE provider. * - * @param provider The E2EE provider. + * @provider: The E2EE provider. * - * @return The localized name of specified E2EE provider. + * Returns: The localized name of specified E2EE provider. */ const gchar * purple_e2ee_provider_get_name(PurpleE2eeProvider *provider); @@ -207,8 +207,8 @@ * * Function should return the GList of PurpleMenuAction objects. * - * @param provider The E2EE provider. - * @param conv_menu_cb The callback. + * @provider: The E2EE provider. + * @conv_menu_cb: The callback. */ void purple_e2ee_provider_set_conv_menu_cb(PurpleE2eeProvider *provider, @@ -217,9 +217,9 @@ /** * Gets the conversation menu callback of the E2EE provider. * - * @param provider The E2EE provider. + * @provider: The E2EE provider. * - * @return The callback. + * Returns: The callback. */ PurpleE2eeConvMenuCallback purple_e2ee_provider_get_conv_menu_cb(PurpleE2eeProvider *provider);
--- a/libpurple/eventloop.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/eventloop.h Wed Jan 29 05:28:33 2014 +0530 @@ -67,13 +67,13 @@ * the libpurple thread. You should make sure to detect this situation * and to only call "function" from the libpurple thread. * - * @param interval the interval in <em>milliseconds</em> between calls + * @interval: the interval in <em>milliseconds</em> between calls * to @a function. - * @param data arbitrary data to be passed to @a function at each + * @data: arbitrary data to be passed to @a function at each * call. * @todo Who is responsible for freeing @a data? * - * @return a handle for the timeout, which can be passed to + * Returns: a handle for the timeout, which can be passed to * #timeout_remove. * * @see purple_timeout_add @@ -82,9 +82,9 @@ /** * Should remove a callback timer. Analogous to g_source_remove in glib. - * @param handle an identifier for a timeout, as returned by + * @handle: an identifier for a timeout, as returned by * #timeout_add. - * @return @c TRUE if the timeout identified by @a handle was + * Returns: @c TRUE if the timeout identified by @a handle was * found and removed. * @see purple_timeout_remove */ @@ -94,13 +94,13 @@ * Should add an input handler. Analogous to g_io_add_watch_full in * glib. * - * @param fd a file descriptor to watch for events - * @param cond a bitwise OR of events on @a fd for which @a func + * @fd: a file descriptor to watch for events + * @cond: a bitwise OR of events on @a fd for which @a func * should be called. - * @param func a callback to fire whenever a relevant event on @a + * @func: a callback to fire whenever a relevant event on @a * fd occurs. - * @param user_data arbitrary data to pass to @a fd. - * @return an identifier for this input handler, which can be + * @user_data: arbitrary data to pass to @a fd. + * Returns: an identifier for this input handler, which can be * passed to #input_remove. * * @see purple_input_add @@ -110,8 +110,8 @@ /** * Should remove an input handler. Analogous to g_source_remove in glib. - * @param handle an identifier, as returned by #input_add. - * @return @c TRUE if the input handler was found and removed. + * @handle: an identifier, as returned by #input_add. + * Returns: @c TRUE if the input handler was found and removed. * @see purple_input_remove */ gboolean (*input_remove)(guint handle); @@ -167,11 +167,11 @@ * If the timer is in a multiple of seconds, use purple_timeout_add_seconds() * instead as it allows UIs to group timers for power efficiency. * - * @param interval The time between calls of the function, in + * @interval: The time between calls of the function, in * milliseconds. - * @param function The function to call. - * @param data data to pass to @a function. - * @return A handle to the timer which can be passed to + * @function: The function to call. + * @data: data to pass to @a function. + * Returns: A handle to the timer which can be passed to * purple_timeout_remove() to remove the timer. */ guint purple_timeout_add(guint interval, GSourceFunc function, gpointer data); @@ -185,11 +185,11 @@ * This function allows UIs to group timers for better power efficiency. For * this reason, @a interval may be rounded by up to a second. * - * @param interval The time between calls of the function, in + * @interval: The time between calls of the function, in * seconds. - * @param function The function to call. - * @param data data to pass to @a function. - * @return A handle to the timer which can be passed to + * @function: The function to call. + * @data: data to pass to @a function. + * Returns: A handle to the timer which can be passed to * purple_timeout_remove() to remove the timer. */ guint purple_timeout_add_seconds(guint interval, GSourceFunc function, gpointer data); @@ -197,21 +197,21 @@ /** * Removes a timeout handler. * - * @param handle The handle, as returned by purple_timeout_add(). + * @handle: The handle, as returned by purple_timeout_add(). * - * @return @c TRUE if the handler was successfully removed. + * Returns: @c TRUE if the handler was successfully removed. */ gboolean purple_timeout_remove(guint handle); /** * Adds an input handler. * - * @param fd The input file descriptor. - * @param cond The condition type. - * @param func The callback function for data. - * @param user_data User-specified data. + * @fd: The input file descriptor. + * @cond: The condition type. + * @func: The callback function for data. + * @user_data: User-specified data. * - * @return The resulting handle (will be greater than 0). + * Returns: The resulting handle (will be greater than 0). * @see g_io_add_watch_full */ guint purple_input_add(int fd, PurpleInputCondition cond, @@ -220,7 +220,7 @@ /** * Removes an input handler. * - * @param handle The handle of the input handler. Note that this is the return + * @handle: The handle of the input handler. Note that this is the return * value from purple_input_add(), <i>not</i> the file descriptor. */ gboolean purple_input_remove(guint handle); @@ -232,11 +232,11 @@ * option name of SO_ERROR, and this is how the error is determined if the UI does not * implement the input_get_error UI op. * - * @param fd The input file descriptor. - * @param error A pointer to an @c int which on return will have the error, or + * @fd: The input file descriptor. + * @error: A pointer to an @c int which on return will have the error, or * @c 0 if no error. * - * @return @c 0 if there is no error; @c -1 if there is an error, in which case + * Returns: @c 0 if there is no error; @c -1 if there is an error, in which case * @a errno will be set. */ int @@ -253,9 +253,9 @@ * On Windows it's simulated by creating a pair of connected sockets, on other * systems pipe() is used. * - * @param pipefd Array used to return file descriptors for both ends of pipe. + * @pipefd: Array used to return file descriptors for both ends of pipe. * - * @return @c 0 on success, @c -1 on error. + * Returns: @c 0 on success, @c -1 on error. */ int purple_input_pipe(int pipefd[2]); @@ -271,14 +271,14 @@ /** * Sets the UI operations structure to be used for accounts. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_eventloop_set_ui_ops(PurpleEventLoopUiOps *ops); /** * Returns the UI operations structure used for accounts. * - * @return The UI operations structure in use. + * Returns: The UI operations structure in use. */ PurpleEventLoopUiOps *purple_eventloop_get_ui_ops(void);
--- a/libpurple/http.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/http.h Wed Jan 29 05:28:33 2014 +0530 @@ -84,12 +84,12 @@ * An callback for getting large request contents (ie. from file stored on * disk). * - * @param http_conn Connection, which requests data. - * @param buffer Buffer to store data to (with offset ignored). - * @param offset Position, from where to read data. - * @param length Length of data to read. - * @param user_data The user data passed with callback function. - * @param cb The function to call after storing data to buffer. + * @http_conn: Connection, which requests data. + * @buffer: Buffer to store data to (with offset ignored). + * @offset: Position, from where to read data. + * @length: Length of data to read. + * @user_data: The user data passed with callback function. + * @cb: The function to call after storing data to buffer. */ typedef void (*PurpleHttpContentReader)(PurpleHttpConnection *http_conn, gchar *buffer, size_t offset, size_t length, gpointer user_data, @@ -98,14 +98,14 @@ /** * An callback for writting large response contents. * - * @param http_conn Connection, which requests data. - * @param response Response at point got so far (may change later). - * @param buffer Buffer to read data from (with offset ignored). - * @param offset Position of data got (its value is offset + length of + * @http_conn: Connection, which requests data. + * @response: Response at point got so far (may change later). + * @buffer: Buffer to read data from (with offset ignored). + * @offset: Position of data got (its value is offset + length of * previous call), can be safely ignored. - * @param length Length of data read. - * @param user_data The user data passed with callback function. - * @return TRUE, if succeeded, FALSE otherwise. + * @length: Length of data read. + * @user_data: The user data passed with callback function. + * Returns: TRUE, if succeeded, FALSE otherwise. */ typedef gboolean (*PurpleHttpContentWriter)(PurpleHttpConnection *http_conn, PurpleHttpResponse *response, const gchar *buffer, size_t offset, @@ -114,12 +114,12 @@ /** * An callback for watching HTTP connection progress. * - * @param http_conn The HTTP Connection. - * @param reading_state FALSE, is we are sending the request, TRUE, when reading + * @http_conn: The HTTP Connection. + * @reading_state: FALSE, is we are sending the request, TRUE, when reading * the response. - * @param processed The amount of data already processed. - * @param total Total amount of data (in current state). - * @param user_data The user data passed with callback function. + * @processed: The amount of data already processed. + * @total: Total amount of data (in current state). + * @user_data: The user data passed with callback function. */ typedef void (*PurpleHttpProgressWatcher)(PurpleHttpConnection *http_conn, gboolean reading_state, int processed, int total, gpointer user_data); @@ -135,11 +135,11 @@ * Fetches the data from a URL with GET request, and passes it to a callback * function. * - * @param gc The connection for which the request is needed, or NULL. - * @param callback The callback function. - * @param user_data The user data to pass to the callback function. - * @param url The URL. - * @return The HTTP connection struct. + * @gc: The connection for which the request is needed, or NULL. + * @callback: The callback function. + * @user_data: The user data to pass to the callback function. + * @url: The URL. + * Returns: The HTTP connection struct. */ PurpleHttpConnection * purple_http_get(PurpleConnection *gc, PurpleHttpCallback callback, gpointer user_data, const gchar *url); @@ -148,11 +148,11 @@ * Constructs an URL and fetches the data from it with GET request, then passes * it to a callback function. * - * @param gc The connection for which the request is needed, or NULL. - * @param callback The callback function. - * @param user_data The user data to pass to the callback function. - * @param format The format string. - * @return The HTTP connection struct. + * @gc: The connection for which the request is needed, or NULL. + * @callback: The callback function. + * @user_data: The user data to pass to the callback function. + * @format: The format string. + * Returns: The HTTP connection struct. */ PurpleHttpConnection * purple_http_get_printf(PurpleConnection *gc, PurpleHttpCallback callback, gpointer user_data, @@ -163,11 +163,11 @@ * Provided request struct can be shared by multiple http requests but can not * be modified when any of these is running. * - * @param gc The connection for which the request is needed, or NULL. - * @param request The request. - * @param callback The callback function. - * @param user_data The user data to pass to the callback function. - * @return The HTTP connection struct. + * @gc: The connection for which the request is needed, or NULL. + * @request: The request. + * @callback: The callback function. + * @user_data: The user data to pass to the callback function. + * Returns: The HTTP connection struct. */ PurpleHttpConnection * purple_http_request(PurpleConnection *gc, PurpleHttpRequest *request, PurpleHttpCallback callback, @@ -181,30 +181,30 @@ /** * Cancel a pending HTTP request. * - * @param http_conn The data returned when you initiated the HTTP request. + * @http_conn: The data returned when you initiated the HTTP request. */ void purple_http_conn_cancel(PurpleHttpConnection *http_conn); /** * Cancels all HTTP connections associated with the specified handle. * - * @param gc The handle. + * @gc: The handle. */ void purple_http_conn_cancel_all(PurpleConnection *gc); /** * Checks, if provided HTTP request is running. * - * @param http_conn The HTTP connection (may be invalid pointer). - * @return TRUE, if provided connection is currently running. + * @http_conn: The HTTP connection (may be invalid pointer). + * Returns: TRUE, if provided connection is currently running. */ gboolean purple_http_conn_is_running(PurpleHttpConnection *http_conn); /** * Gets PurpleHttpRequest used for specified HTTP connection. * - * @param http_conn The HTTP connection. - * @return The PurpleHttpRequest object. + * @http_conn: The HTTP connection. + * Returns: The PurpleHttpRequest object. */ PurpleHttpRequest * purple_http_conn_get_request( PurpleHttpConnection *http_conn); @@ -212,8 +212,8 @@ /** * Gets cookie jar used within connection. * - * @param http_conn The HTTP connection. - * @return The cookie jar. + * @http_conn: The HTTP connection. + * Returns: The cookie jar. */ PurpleHttpCookieJar * purple_http_conn_get_cookie_jar( PurpleHttpConnection *http_conn); @@ -221,8 +221,8 @@ /** * Gets PurpleConnection tied with specified HTTP connection. * - * @param http_conn The HTTP connection. - * @return The PurpleConnection object. + * @http_conn: The HTTP connection. + * Returns: The PurpleConnection object. */ PurpleConnection * purple_http_conn_get_purple_connection( PurpleHttpConnection *http_conn); @@ -231,10 +231,10 @@ * Sets the watcher, called after writing or reading data to/from HTTP stream. * May be used for updating transfer progress gauge. * - * @param http_conn The HTTP connection. - * @param watcher The watcher. - * @param user_data The user data to pass to the callback function. - * @param interval_threshold Minimum interval (in microseconds) of calls to + * @http_conn: The HTTP connection. + * @watcher: The watcher. + * @user_data: The user data to pass to the callback function. + * @interval_threshold: Minimum interval (in microseconds) of calls to * watcher, or -1 for default. */ void purple_http_conn_set_progress_watcher(PurpleHttpConnection *http_conn, @@ -254,8 +254,8 @@ * * The returned data must be freed with purple_http_url_free. * - * @param url The URL to parse. - * @return The parsed url or NULL, if the URL is invalid. + * @url: The URL to parse. + * Returns: The parsed url or NULL, if the URL is invalid. */ PurpleHttpURL * purple_http_url_parse(const char *url); @@ -263,7 +263,7 @@ /** * Frees the parsed URL struct. * - * @param parsed_url The parsed URL struct, or NULL. + * @parsed_url: The parsed URL struct, or NULL. */ void purple_http_url_free(PurpleHttpURL *parsed_url); @@ -274,8 +274,8 @@ * Example: "https://example.com/path/to/file.html" + "subdir/other-file.html" = * "https://example.com/path/to/subdir/another-file.html" * - * @param base_url The base URL. The result is stored here. - * @param relative_url The relative URL. + * @base_url: The base URL. The result is stored here. + * @relative_url: The relative URL. */ void purple_http_url_relative(PurpleHttpURL *base_url, PurpleHttpURL *relative_url); @@ -286,8 +286,8 @@ * * The result must be g_free'd. * - * @param parsed_url The URL struct. - * @return The printable form of the URL. + * @parsed_url: The URL struct. + * Returns: The printable form of the URL. */ gchar * purple_http_url_print(PurpleHttpURL *parsed_url); @@ -295,8 +295,8 @@ /** * Gets the protocol part of URL. * - * @param parsed_url The URL struct. - * @return The protocol. + * @parsed_url: The URL struct. + * Returns: The protocol. */ const gchar * purple_http_url_get_protocol(const PurpleHttpURL *parsed_url); @@ -304,8 +304,8 @@ /** * Gets the username part of URL. * - * @param parsed_url The URL struct. - * @return The username. + * @parsed_url: The URL struct. + * Returns: The username. */ const gchar * purple_http_url_get_username(const PurpleHttpURL *parsed_url); @@ -313,8 +313,8 @@ /** * Gets the password part of URL. * - * @param parsed_url The URL struct. - * @return The password. + * @parsed_url: The URL struct. + * Returns: The password. */ const gchar * purple_http_url_get_password(const PurpleHttpURL *parsed_url); @@ -322,8 +322,8 @@ /** * Gets the hostname part of URL. * - * @param parsed_url The URL struct. - * @return The hostname. + * @parsed_url: The URL struct. + * Returns: The hostname. */ const gchar * purple_http_url_get_host(const PurpleHttpURL *parsed_url); @@ -331,8 +331,8 @@ /** * Gets the port part of URL. * - * @param parsed_url The URL struct. - * @return The port number. + * @parsed_url: The URL struct. + * Returns: The port number. */ int purple_http_url_get_port(const PurpleHttpURL *parsed_url); @@ -340,8 +340,8 @@ /** * Gets the path part of URL. * - * @param parsed_url The URL struct. - * @return The path. + * @parsed_url: The URL struct. + * Returns: The path. */ const gchar * purple_http_url_get_path(const PurpleHttpURL *parsed_url); @@ -349,8 +349,8 @@ /** * Gets the fragment part of URL. * - * @param parsed_url The URL struct. - * @return The fragment. + * @parsed_url: The URL struct. + * Returns: The fragment. */ const gchar * purple_http_url_get_fragment(const PurpleHttpURL *parsed_url); @@ -366,14 +366,14 @@ /** * Creates new cookie jar, * - * @return empty cookie jar. + * Returns: empty cookie jar. */ PurpleHttpCookieJar * purple_http_cookie_jar_new(void); /** * Increment the reference count. * - * @param cookie_jar The cookie jar. + * @cookie_jar: The cookie jar. */ void purple_http_cookie_jar_ref(PurpleHttpCookieJar *cookie_jar); @@ -382,8 +382,8 @@ * * If the reference count reaches zero, the cookie jar will be freed. * - * @param cookie_jar The cookie jar. - * @return @a cookie_jar or @c NULL if the reference count reached zero. + * @cookie_jar: The cookie jar. + * Returns: @a cookie_jar or @c NULL if the reference count reached zero. */ PurpleHttpCookieJar * purple_http_cookie_jar_unref( PurpleHttpCookieJar *cookie_jar); @@ -391,9 +391,9 @@ /** * Sets the cookie. * - * @param cookie_jar The cookie jar. - * @param name Cookie name. - * @param value Cookie contents. + * @cookie_jar: The cookie jar. + * @name: Cookie name. + * @value: Cookie contents. */ void purple_http_cookie_jar_set(PurpleHttpCookieJar *cookie_jar, const gchar *name, const gchar *value); @@ -401,9 +401,9 @@ /** * Gets the cookie. * - * @param cookie_jar The cookie jar. - * @param name Cookie name. - * @return Cookie contents, or NULL, if cookie doesn't exists. + * @cookie_jar: The cookie jar. + * @name: Cookie name. + * Returns: Cookie contents, or NULL, if cookie doesn't exists. */ const gchar * purple_http_cookie_jar_get(PurpleHttpCookieJar *cookie_jar, const gchar *name); @@ -411,8 +411,8 @@ /** * Checks, if the cookie jar contains any cookies. * - * @param cookie_jar The cookie jar. - * @return TRUE, if cookie jar contains any cookie, FALSE otherwise. + * @cookie_jar: The cookie jar. + * Returns: TRUE, if cookie jar contains any cookie, FALSE otherwise. */ gboolean purple_http_cookie_jar_is_empty(PurpleHttpCookieJar *cookie_jar); @@ -427,16 +427,16 @@ /** * Creates the new instance of HTTP request configuration. * - * @param url The URL to request for, or NULL to leave empty (to be set with + * @url: The URL to request for, or NULL to leave empty (to be set with * purple_http_request_set_url). - * @return The new instance of HTTP request struct. + * Returns: The new instance of HTTP request struct. */ PurpleHttpRequest * purple_http_request_new(const gchar *url); /** * Increment the reference count. * - * @param request The request. + * @request: The request. */ void purple_http_request_ref(PurpleHttpRequest *request); @@ -445,24 +445,24 @@ * * If the reference count reaches zero, the http request struct will be freed. * - * @param request The request. - * @return @a request or @c NULL if the reference count reached zero. + * @request: The request. + * Returns: @a request or @c NULL if the reference count reached zero. */ PurpleHttpRequest * purple_http_request_unref(PurpleHttpRequest *request); /** * Sets URL for HTTP request. * - * @param request The request. - * @param url The url. + * @request: The request. + * @url: The url. */ void purple_http_request_set_url(PurpleHttpRequest *request, const gchar *url); /** * Constructs and sets an URL for HTTP request. * - * @param request The request. - * @param format The format string. + * @request: The request. + * @format: The format string. */ void purple_http_request_set_url_printf(PurpleHttpRequest *request, const gchar *format, ...) G_GNUC_PRINTF(2, 3); @@ -470,16 +470,16 @@ /** * Gets URL set for the HTTP request. * - * @param request The request. - * @return URL set for this request. + * @request: The request. + * Returns: URL set for this request. */ const gchar * purple_http_request_get_url(PurpleHttpRequest *request); /** * Sets custom HTTP method used for the request. * - * @param request The request. - * @param method The method, or NULL for default. + * @request: The request. + * @method: The method, or NULL for default. */ void purple_http_request_set_method(PurpleHttpRequest *request, const gchar *method); @@ -487,8 +487,8 @@ /** * Gets HTTP method set for the request. * - * @param request The request. - * @return The method. + * @request: The request. + * Returns: The method. */ const gchar * purple_http_request_get_method(PurpleHttpRequest *request); @@ -497,8 +497,8 @@ * * It increases pool's reference count. * - * @param request The request. - * @param pool The new KeepAlive pool, or NULL to reset. + * @request: The request. + * @pool: The new KeepAlive pool, or NULL to reset. */ void purple_http_request_set_keepalive_pool(PurpleHttpRequest *request, @@ -509,8 +509,8 @@ * * It doesn't affect pool's reference count. * - * @param request The request. - * @return The KeepAlive pool, used for the request. + * @request: The request. + * Returns: The KeepAlive pool, used for the request. */ PurpleHttpKeepalivePool * purple_http_request_get_keepalive_pool(PurpleHttpRequest *request); @@ -518,9 +518,9 @@ /** * Sets contents of HTTP request (for example, POST data). * - * @param request The request. - * @param contents The contents. - * @param length The length of contents (-1 if it's a NULL-terminated string) + * @request: The request. + * @contents: The contents. + * @length: The length of contents (-1 if it's a NULL-terminated string) */ void purple_http_request_set_contents(PurpleHttpRequest *request, const gchar *contents, int length); @@ -529,10 +529,10 @@ * Sets contents reader for HTTP request, used mainly for possible large * uploads. * - * @param request The request. - * @param reader The reader callback. - * @param contents_size The size of all contents. - * @param user_data The user data to pass to the callback function. + * @request: The request. + * @reader: The reader callback. + * @contents_size: The size of all contents. + * @user_data: The user data to pass to the callback function. */ void purple_http_request_set_contents_reader(PurpleHttpRequest *request, PurpleHttpContentReader reader, int contents_length, gpointer user_data); @@ -540,9 +540,9 @@ /** * Set contents writer for HTTP response. * - * @param request The request. - * @param reader The writer callback, or NULL to remove existing. - * @param user_data The user data to pass to the callback function. + * @request: The request. + * @reader: The writer callback, or NULL to remove existing. + * @user_data: The user data to pass to the callback function. */ void purple_http_request_set_response_writer(PurpleHttpRequest *request, PurpleHttpContentWriter writer, gpointer user_data); @@ -550,8 +550,8 @@ /** * Set maximum amount of time, that request is allowed to run. * - * @param request The request. - * @param timeout Time (in seconds) after that timeout will be cancelled, + * @request: The request. + * @timeout: Time (in seconds) after that timeout will be cancelled, * -1 for infinite time. */ void purple_http_request_set_timeout(PurpleHttpRequest *request, int timeout); @@ -559,16 +559,16 @@ /** * Get maximum amount of time, that request is allowed to run. * - * @param request The request. - * @return Timeout currently set (-1 for infinite). + * @request: The request. + * Returns: Timeout currently set (-1 for infinite). */ int purple_http_request_get_timeout(PurpleHttpRequest *request); /** * Sets maximum amount of redirects. * - * @param request The request. - * @param max_redirects Maximum amount of redirects, or -1 for unlimited. + * @request: The request. + * @max_redirects: Maximum amount of redirects, or -1 for unlimited. */ void purple_http_request_set_max_redirects(PurpleHttpRequest *request, int max_redirects); @@ -576,16 +576,16 @@ /** * Gets maximum amount of redirects. * - * @param request The request. - * @return Current maximum amount of redirects (-1 for unlimited). + * @request: The request. + * Returns: Current maximum amount of redirects (-1 for unlimited). */ int purple_http_request_get_max_redirects(PurpleHttpRequest *request); /** * Sets cookie jar used for the request. * - * @param request The request. - * @param cookie_jar The cookie jar. + * @request: The request. + * @cookie_jar: The cookie jar. */ void purple_http_request_set_cookie_jar(PurpleHttpRequest *request, PurpleHttpCookieJar *cookie_jar); @@ -593,8 +593,8 @@ /** * Gets cookie jar used for the request. * - * @param request The request. - * @return The cookie jar. + * @request: The request. + * Returns: The cookie jar. */ PurpleHttpCookieJar * purple_http_request_get_cookie_jar( PurpleHttpRequest *request); @@ -602,8 +602,8 @@ /** * Sets HTTP version to use. * - * @param request The request. - * @param http11 TRUE for HTTP/1.1, FALSE for HTTP/1.0. + * @request: The request. + * @http11: TRUE for HTTP/1.1, FALSE for HTTP/1.0. */ void purple_http_request_set_http11(PurpleHttpRequest *request, gboolean http11); @@ -611,8 +611,8 @@ /** * Gets used HTTP version. * - * @param request The request. - * @return TRUE, if we use HTTP/1.1, FALSE for HTTP/1.0. + * @request: The request. + * Returns: TRUE, if we use HTTP/1.1, FALSE for HTTP/1.0. */ gboolean purple_http_request_is_http11(PurpleHttpRequest *request); @@ -621,8 +621,8 @@ * * Headers length doesn't count here. * - * @param request The request. - * @param max_len Maximum length of response to read (-1 for the maximum + * @request: The request. + * @max_len: Maximum length of response to read (-1 for the maximum * supported amount). */ void purple_http_request_set_max_len(PurpleHttpRequest *request, int max_len); @@ -630,17 +630,17 @@ /** * Gets maximum length of response content to read. * - * @param request The request. - * @return Maximum length of response to read, or -1 if unlimited. + * @request: The request. + * Returns: Maximum length of response to read, or -1 if unlimited. */ int purple_http_request_get_max_len(PurpleHttpRequest *request); /** * Sets (replaces, if exists) specified HTTP request header with provided value. * - * @param request The request. - * @param key A header to be set. - * @param value A value to set, or NULL to remove specified header. + * @request: The request. + * @key: A header to be set. + * @value: A value to set, or NULL to remove specified header. * * @see purple_http_request_header_add */ @@ -650,9 +650,9 @@ /** * Constructs and sets (replaces, if exists) specified HTTP request header. * - * @param request The request. - * @param key A header to be set. - * @param format The format string. + * @request: The request. + * @key: A header to be set. + * @format: The format string. */ void purple_http_request_header_set_printf(PurpleHttpRequest *request, const gchar *key, const gchar *format, ...) G_GNUC_PRINTF(3, 4); @@ -660,8 +660,8 @@ /** * Adds (without replacing, if exists) an HTTP request header. * - * @param key A header to be set. - * @param value A value to set. + * @key: A header to be set. + * @value: A value to set. * * @see purple_http_request_header_set */ @@ -685,7 +685,7 @@ /** * Increment the reference count. * - * @param pool The HTTP Keep-Alive pool. + * @pool: The HTTP Keep-Alive pool. */ void purple_http_keepalive_pool_ref(PurpleHttpKeepalivePool *pool); @@ -696,8 +696,8 @@ * If the reference count reaches zero, the pool will be freed and all * connections will be closed. * - * @param pool The HTTP Keep-Alive pool. - * @return @a pool or @c NULL if the reference count reached zero. + * @pool: The HTTP Keep-Alive pool. + * Returns: @a pool or @c NULL if the reference count reached zero. */ PurpleHttpKeepalivePool * purple_http_keepalive_pool_unref(PurpleHttpKeepalivePool *pool); @@ -706,8 +706,8 @@ * Sets maximum allowed number of connections to specific host-triple (is_ssl + * hostname + port). * - * @param pool The HTTP Keep-Alive pool. - * @param limit The new limit, 0 for unlimited. + * @pool: The HTTP Keep-Alive pool. + * @limit: The new limit, 0 for unlimited. */ void purple_http_keepalive_pool_set_limit_per_host(PurpleHttpKeepalivePool *pool, @@ -717,8 +717,8 @@ * Gets maximum allowed number of connections to specific host-triple (is_ssl + * hostname + port). * - * @param pool The HTTP Keep-Alive pool. - * @return The limit. + * @pool: The HTTP Keep-Alive pool. + * Returns: The limit. */ guint purple_http_keepalive_pool_get_limit_per_host(PurpleHttpKeepalivePool *pool); @@ -752,32 +752,32 @@ /** * Checks, if HTTP request was performed successfully. * - * @param response The response. - * @return TRUE, if request was performed successfully. + * @response: The response. + * Returns: TRUE, if request was performed successfully. */ gboolean purple_http_response_is_successful(PurpleHttpResponse *response); /** * Gets HTTP response code. * - * @param response The response. - * @return HTTP response code. + * @response: The response. + * Returns: HTTP response code. */ int purple_http_response_get_code(PurpleHttpResponse *response); /** * Gets error description. * - * @param response The response. - * @return Localized error description or NULL, if there was no error. + * @response: The response. + * Returns: Localized error description or NULL, if there was no error. */ const gchar * purple_http_response_get_error(PurpleHttpResponse *response); /** * Gets HTTP response data length. * - * @param response The response. - * @return Data length; + * @response: The response. + * Returns: Data length; */ gsize purple_http_response_get_data_len(PurpleHttpResponse *response); @@ -786,17 +786,17 @@ * * Response data is not written, if writer callback was set for request. * - * @param response The response. - * @param len Return address for the size of the data. Can be NULL. - * @return The data. + * @response: The response. + * @len: Return address for the size of the data. Can be NULL. + * Returns: The data. */ const gchar * purple_http_response_get_data(PurpleHttpResponse *response, size_t *len); /** * Gets all headers got with response. * - * @param response The response. - * @return GList of PurpleKeyValuePair, which keys are header field + * @response: The response. + * Returns: GList of PurpleKeyValuePair, which keys are header field * names (gchar*) and values are its contents (gchar*). */ const GList * purple_http_response_get_all_headers(PurpleHttpResponse *response); @@ -804,9 +804,9 @@ /** * Gets all headers with specified name got with response. * - * @param response The response. - * @param name The name of header field. - * @return GList of header field records contents (gchar*). + * @response: The response. + * @name: The name of header field. + * Returns: GList of header field records contents (gchar*). */ const GList * purple_http_response_get_headers_by_name( PurpleHttpResponse *response, const gchar *name); @@ -817,9 +817,9 @@ * To get all headers with the same name, use * purple_http_response_get_headers_by_name instead. * - * @param response The response. - * @param name The name of header field. - * @return Header field contents or NULL, if there is no such one. + * @response: The response. + * @name: The name of header field. + * Returns: Header field contents or NULL, if there is no such one. */ const gchar * purple_http_response_get_header(PurpleHttpResponse *response, const gchar *name);
--- a/libpurple/idle.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/idle.h Wed Jan 29 05:28:33 2014 +0530 @@ -73,14 +73,14 @@ /** * Sets the UI operations structure to be used for idle reporting. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_idle_set_ui_ops(PurpleIdleUiOps *ops); /** * Returns the UI operations structure used for idle reporting. * - * @return The UI operations structure in use. + * Returns: The UI operations structure in use. */ PurpleIdleUiOps *purple_idle_get_ui_ops(void);
--- a/libpurple/imgstore.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/imgstore.h Wed Jan 29 05:28:33 2014 +0530 @@ -59,11 +59,11 @@ * The caller owns a reference to this image and must dereference it with * purple_imgstore_unref() for it to be freed. * - * @param data Pointer to the image data, which the imgstore will take + * @data: Pointer to the image data, which the imgstore will take * ownership of and free as appropriate. If you want a * copy of the data, make it before calling this function. - * @param size Image data's size. - * @param filename Filename associated with image. This is for your + * @size: Image data's size. + * @filename: Filename associated with image. This is for your * convenience. It could be the full path to the * image or, more commonly, the filename of the image * without any directory information. It can also be @@ -72,7 +72,7 @@ * disk, make sure the filename is appropriately escaped. * You may wish to use purple_escape_filename(). * - * @return The image, or NULL if the image could not be created (because of + * Returns: The image, or NULL if the image could not be created (because of * empty data or size). */ PurpleStoredImage * @@ -93,9 +93,9 @@ * The caller owns a reference to this image and must dereference it with * purple_imgstore_unref() for it to be freed. * - * @param path The path to the image. + * @path: The path to the image. * - * @return The image, or NULL if the image could not be created (because of + * Returns: The image, or NULL if the image could not be created (because of * empty data or size). */ PurpleStoredImage * @@ -109,11 +109,11 @@ * purple_imgstore_unref() or purple_imgstore_unref_by_id() for it to be * freed. * - * @param data Pointer to the image data, which the imgstore will take + * @data: Pointer to the image data, which the imgstore will take * ownership of and free as appropriate. If you want a * copy of the data, make it before calling this function. - * @param size Image data's size. - * @param filename Filename associated with image. This is for your + * @size: Image data's size. + * @filename: Filename associated with image. This is for your * convenience. It could be the full path to the * image or, more commonly, the filename of the image * without any directory information. It can also be @@ -122,7 +122,7 @@ * disk, make sure the filename is appropriately escaped. * You may wish to use purple_escape_filename() * - * @return ID for the image. This is a unique number that can be used + * Returns: ID for the image. This is a unique number that can be used * within libpurple to reference the image. 0 is returned if the * image could not be created (because of empty data or size). */ @@ -132,18 +132,18 @@ * Retrieve an image from the store. The caller does not own a * reference to the image. * - * @param id The ID for the image. + * @id: The ID for the image. * - * @return A pointer to the requested image, or NULL if it was not found. + * Returns: A pointer to the requested image, or NULL if it was not found. */ PurpleStoredImage *purple_imgstore_find_by_id(int id); /** * Retrieves a pointer to the image's data. * - * @param img The Image. + * @img: The Image. * - * @return A pointer to the data, which must not + * Returns: A pointer to the data, which must not * be freed or modified. */ gconstpointer purple_imgstore_get_data(PurpleStoredImage *img); @@ -151,9 +151,9 @@ /** * Retrieves the length of the image's data. * - * @param img The Image. + * @img: The Image. * - * @return The size of the data that the pointer returned by + * Returns: The size of the data that the pointer returned by * purple_imgstore_get_data points to. */ size_t purple_imgstore_get_size(PurpleStoredImage *img); @@ -164,9 +164,9 @@ * appropriately escaped when you created the PurpleStoredImage. You may * wish to use purple_escape_filename(). * - * @param img The image. + * @img: The image. * - * @return A pointer to the filename, which must not + * Returns: A pointer to the filename, which must not * be freed or modified. */ const char *purple_imgstore_get_filename(const PurpleStoredImage *img); @@ -175,9 +175,9 @@ * Looks at the magic numbers of the image data (the first few bytes) * and returns an extension corresponding to the image's file type. * - * @param img The image. + * @img: The image. * - * @return The image's extension (for example "png") or "icon" + * Returns: The image's extension (for example "png") or "icon" * if unknown. */ const char *purple_imgstore_get_extension(PurpleStoredImage *img); @@ -185,9 +185,9 @@ /** * Increment the reference count. * - * @param img The image. + * @img: The image. * - * @return @a img + * Returns: @a img */ PurpleStoredImage * purple_imgstore_ref(PurpleStoredImage *img); @@ -197,9 +197,9 @@ * * If the reference count reaches zero, the image will be freed. * - * @param img The image. + * @img: The image. * - * @return @a img or @c NULL if the reference count reached zero. + * Returns: @a img or @c NULL if the reference count reached zero. */ PurpleStoredImage * purple_imgstore_unref(PurpleStoredImage *img); @@ -211,7 +211,7 @@ * purple_imgstore_ref(), so if you have a PurpleStoredImage, it'll * be more efficient to call purple_imgstore_ref() directly. * - * @param id The ID for the image. + * @id: The ID for the image. */ void purple_imgstore_ref_by_id(int id); @@ -222,14 +222,14 @@ * purple_imgstore_unref(), so if you have a PurpleStoredImage, it'll * be more efficient to call purple_imgstore_unref() directly. * - * @param id The ID for the image. + * @id: The ID for the image. */ void purple_imgstore_unref_by_id(int id); /** * Returns the image store subsystem handle. * - * @return The subsystem handle. + * Returns: The subsystem handle. */ void *purple_imgstore_get_handle(void);
--- a/libpurple/internal.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/internal.h Wed Jan 29 05:28:33 2014 +0530 @@ -161,8 +161,8 @@ /** * Sets an error for an account. * - * @param account The account to set the error for. - * @param new_err The #PurpleConnectionErrorInfo instance representing the + * @account: The account to set the error for. + * @new_err: The #PurpleConnectionErrorInfo instance representing the * error. */ void _purple_account_set_current_error(PurpleAccount *account, @@ -171,17 +171,17 @@ /** * Get an XML description of an account. * - * @param account The account - * @return The XML description of the account. + * @account: The account + * Returns: The XML description of the account. */ PurpleXmlNode *_purple_account_to_xmlnode(PurpleAccount *account); /** * Returns the last child of a particular node. * - * @param node The node whose last child is to be retrieved. + * @node: The node whose last child is to be retrieved. * - * @return The last child of the node. + * Returns: The last child of the node. */ PurpleBlistNode *_purple_blist_get_last_child(PurpleBlistNode *node); @@ -207,10 +207,10 @@ * in account.c. If you're trying to sign on an account, use that * function instead. * - * @param account The account the connection should be connecting to. - * @param regist Whether we are registering a new account or just + * @account: The account the connection should be connecting to. + * @regist: Whether we are registering a new account or just * trying to do a normal signon. - * @param password The password to use. + * @password: The password to use. */ void _purple_connection_new(PurpleAccount *account, gboolean regist, const char *password); @@ -221,10 +221,10 @@ * @note This function should only be called by purple_account_unregister() * in account.c. * - * @param account The account to unregister - * @param password The password to use. - * @param cb Optional callback to be called when unregistration is complete - * @param user_data user data to pass to the callback + * @account: The account to unregister + * @password: The password to use. + * @cb: Optional callback to be called when unregistration is complete + * @user_data: user data to pass to the callback */ void _purple_connection_new_unregister(PurpleAccount *account, const char *password, PurpleAccountUnregistrationCb cb, void *user_data); @@ -234,7 +234,7 @@ * @note This function should only be called by purple_account_set_enabled() * in account.c. * - * @param gc The connection to check + * @gc: The connection to check */ gboolean _purple_connection_wants_to_die(const PurpleConnection *gc); @@ -244,8 +244,8 @@ * @note This function should only be called by serv_got_joined_chat() * in server.c. * - * @param gc The connection - * @param chat The chat conversation to add + * @gc: The connection + * @chat: The chat conversation to add */ void _purple_connection_add_active_chat(PurpleConnection *gc, PurpleChatConversation *chat); @@ -255,8 +255,8 @@ * @note This function should only be called by serv_got_chat_left() * in server.c. * - * @param gc The connection - * @param chat The chat conversation to remove + * @gc: The connection + * @chat: The chat conversation to remove */ void _purple_connection_remove_active_chat(PurpleConnection *gc, PurpleChatConversation *chat);
--- a/libpurple/keyring.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/keyring.h Wed Jan 29 05:28:33 2014 +0530 @@ -61,10 +61,10 @@ * * If there was a problem, the password will be NULL, and the error set. * - * @param account The account. - * @param password The password. - * @param error Error that may have occurred. - * @param data Data passed to the callback. + * @account: The account. + * @password: The password. + * @error: Error that may have occurred. + * @data: Data passed to the callback. */ typedef void (*PurpleKeyringReadCallback)(PurpleAccount *account, const gchar *password, GError *error, gpointer data); @@ -74,9 +74,9 @@ * * If there was a problem, the error will be set. * - * @param account The account. - * @param error Error that may have occurred. - * @param data Data passed to the callback. + * @account: The account. + * @error: Error that may have occurred. + * @data: Data passed to the callback. */ typedef void (*PurpleKeyringSaveCallback)(PurpleAccount *account, GError *error, gpointer data); @@ -84,16 +84,16 @@ /** * Callback for once the master password for a keyring has been changed. * - * @param error Error that has occurred. - * @param data Data passed to the callback. + * @error: Error that has occurred. + * @data: Data passed to the callback. */ typedef void (*PurpleKeyringChangeMasterCallback)(GError *error, gpointer data); /** * Callback for when we change the keyring. * - * @param error An error that might have occurred. - * @param data A pointer to user supplied data. + * @error: An error that might have occurred. + * @data: A pointer to user supplied data. */ typedef void (*PurpleKeyringSetInUseCallback)(GError *error, gpointer data); @@ -107,9 +107,9 @@ /** * Read the password for an account. * - * @param account The account. - * @param cb A callback for once the password is found. - * @param data Data to be passed to the callback. + * @account: The account. + * @cb: A callback for once the password is found. + * @data: Data to be passed to the callback. */ typedef void (*PurpleKeyringRead)(PurpleAccount *account, PurpleKeyringReadCallback cb, gpointer data); @@ -117,11 +117,11 @@ /** * Store a password in the keyring. * - * @param account The account. - * @param password The password to be stored. If the password is NULL, this + * @account: The account. + * @password: The password to be stored. If the password is NULL, this * means that the keyring should forget about that password. - * @param cb A callback for once the password is saved. - * @param data Data to be passed to the callback. + * @cb: A callback for once the password is saved. + * @data: Data to be passed to the callback. */ typedef void (*PurpleKeyringSave)(PurpleAccount *account, const gchar *password, PurpleKeyringSaveCallback cb, gpointer data); @@ -147,11 +147,11 @@ * This is not async because it is not meant to prompt for a master password and * decrypt passwords. * - * @param account The account. - * @param mode A keyring specific option that was stored. Can be NULL. - * @param data Data that was stored. Can be NULL. + * @account: The account. + * @mode: A keyring specific option that was stored. Can be NULL. + * @data: Data that was stored. Can be NULL. * - * @return TRUE on success, FALSE on failure. + * Returns: TRUE on success, FALSE on failure. */ typedef gboolean (*PurpleKeyringImportPassword)(PurpleAccount *account, const gchar *mode, const gchar *data, GError **error); @@ -159,15 +159,15 @@ /** * Export serialized (and maybe encrypted) password. * - * @param account The account. - * @param mode An option field that can be used by the plugin. This is + * @account: The account. + * @mode: An option field that can be used by the plugin. This is * expected to be a static string. - * @param data The data to be stored in the XML node. This string will be + * @data: The data to be stored in the XML node. This string will be * freed using destroy() once not needed anymore. - * @param error Will be set if a problem occured. - * @param destroy A function to be called, if non NULL, to free data. + * @error: Will be set if a problem occured. + * @destroy: A function to be called, if non NULL, to free data. * - * @return TRUE on success, FALSE on failure. + * Returns: TRUE on success, FALSE on failure. */ typedef gboolean (*PurpleKeyringExportPassword)(PurpleAccount *account, const gchar **mode, gchar **data, GError **error, @@ -176,7 +176,7 @@ /** * Read keyring settings. * - * @return New copy of current settings (must be free'd with + * Returns: New copy of current settings (must be free'd with * purple_request_fields_destroy). */ typedef PurpleRequestFields * (*PurpleKeyringReadSettings)(void); @@ -184,10 +184,10 @@ /** * Applies modified keyring settings. * - * @param notify_handle A handle that can be passed to purple_notify_message. - * @param fields Modified settings (originally taken from + * @notify_handle: A handle that can be passed to purple_notify_message. + * @fields: Modified settings (originally taken from * PurpleKeyringReadSettings). - * @return TRUE, if succeeded, FALSE otherwise. + * Returns: TRUE, if succeeded, FALSE otherwise. */ typedef gboolean (*PurpleKeyringApplySettings)(void *notify_handle, PurpleRequestFields *fields); @@ -204,9 +204,9 @@ /** * Find a keyring by an id. * - * @param id The id for the keyring. + * @id: The id for the keyring. * - * @return The keyring, or NULL if not found. + * Returns: The keyring, or NULL if not found. */ PurpleKeyring * purple_keyring_find_keyring_by_id(const gchar *id); @@ -225,11 +225,11 @@ * the callback. If it succeeds, it will remove all passwords from the old safe * and close that safe. * - * @param newkeyring The new keyring to use. - * @param force FALSE if the change can be cancelled. If this is TRUE and + * @newkeyring: The new keyring to use. + * @force: FALSE if the change can be cancelled. If this is TRUE and * an error occurs, data might be lost. - * @param cb A callback for once the change is complete. - * @param data Data to be passed to the callback. + * @cb: A callback for once the change is complete. + * @data: Data to be passed to the callback. */ void purple_keyring_set_inuse(PurpleKeyring *newkeyring, gboolean force, @@ -238,7 +238,7 @@ /** * Register a keyring plugin. * - * @param keyring The keyring to register. + * @keyring: The keyring to register. */ void purple_keyring_register(PurpleKeyring *keyring); @@ -249,7 +249,7 @@ * In case the keyring is in use, passwords will be moved to a fallback safe, * and the keyring to unregister will be properly closed. * - * @param keyring The keyring to unregister. + * @keyring: The keyring to unregister. */ void purple_keyring_unregister(PurpleKeyring *keyring); @@ -258,7 +258,7 @@ * Returns a GList containing the IDs and names of the registered * keyrings. * - * @return The list of IDs and names. + * Returns: The list of IDs and names. */ GList * purple_keyring_get_options(void); @@ -275,12 +275,12 @@ * * It's used by account.c while reading a password from xml. * - * @param account The account. - * @param keyring_id The plugin ID that was stored in the xml file. Can be NULL. - * @param mode A keyring specific option that was stored. Can be NULL. - * @param data Data that was stored, can be NULL. + * @account: The account. + * @keyring_id: The plugin ID that was stored in the xml file. Can be NULL. + * @mode: A keyring specific option that was stored. Can be NULL. + * @data: Data that was stored, can be NULL. * - * @return TRUE if the input was accepted, FALSE otherwise. + * Returns: TRUE if the input was accepted, FALSE otherwise. */ gboolean purple_keyring_import_password(PurpleAccount *account, const gchar *keyring_id, @@ -291,18 +291,18 @@ * * It's used by account.c while syncing accounts to xml. * - * @param account The account for which we want the info. - * @param keyring_id The plugin id to be stored in the XML node. This will be + * @account: The account for which we want the info. + * @keyring_id: The plugin id to be stored in the XML node. This will be * NULL or a string that can be considered static. - * @param mode An option field that can be used by the plugin. This will + * @mode: An option field that can be used by the plugin. This will * be NULL or a string that can be considered static. - * @param data The data to be stored in the XML node. This string must be + * @data: The data to be stored in the XML node. This string must be * freed using destroy() once not needed anymore if it is not * NULL. - * @param error Will be set if a problem occured. - * @param destroy A function to be called, if non NULL, to free data. + * @error: Will be set if a problem occured. + * @destroy: A function to be called, if non NULL, to free data. * - * @return TRUE if the info was exported successfully, FALSE otherwise. + * Returns: TRUE if the info was exported successfully, FALSE otherwise. */ gboolean purple_keyring_export_password(PurpleAccount *account, const gchar **keyring_id, @@ -312,9 +312,9 @@ /** * Read a password from the current keyring. * - * @param account The account. - * @param cb A callback for once the password is read. - * @param data Data passed to the callback. + * @account: The account. + * @cb: A callback for once the password is read. + * @data: Data passed to the callback. */ void purple_keyring_get_password(PurpleAccount *account, @@ -323,10 +323,10 @@ /** * Save a password to the current keyring. * - * @param account The account. - * @param password The password to save. - * @param cb A callback for once the password is saved. - * @param data Data to be passed to the callback. + * @account: The account. + * @password: The password to save. + * @cb: A callback for once the password is saved. + * @data: Data to be passed to the callback. */ void purple_keyring_set_password(PurpleAccount *account, const gchar *password, @@ -335,7 +335,7 @@ /** * Reads settings from current keyring. * - * @return New copy of current settings (must be free'd with + * Returns: New copy of current settings (must be free'd with * purple_request_fields_destroy). */ PurpleRequestFields * @@ -344,10 +344,10 @@ /** * Applies modified settings to current keyring. * - * @param notify_handle A handle that can be passed to purple_notify_message. - * @param fields Modified settings (originally taken from + * @notify_handle: A handle that can be passed to purple_notify_message. + * @fields: Modified settings (originally taken from * PurpleKeyringReadSettings). - * @return TRUE, if succeeded, FALSE otherwise. + * Returns: TRUE, if succeeded, FALSE otherwise. */ gboolean purple_keyring_apply_settings(void *notify_handle, PurpleRequestFields *fields); @@ -373,7 +373,7 @@ /** * Frees all data allocated with purple_keyring_new. * - * @param keyring Keyring wrapper struct. + * @keyring: Keyring wrapper struct. */ void purple_keyring_free(PurpleKeyring *keyring); @@ -381,8 +381,8 @@ /** * Gets friendly user name. * - * @param keyring The keyring. - * @return Friendly user name. + * @keyring: The keyring. + * Returns: Friendly user name. */ const gchar * purple_keyring_get_name(const PurpleKeyring *keyring); @@ -390,8 +390,8 @@ /** * Gets keyring ID. * - * @param keyring The keyring. - * @return Keyring ID. + * @keyring: The keyring. + * Returns: Keyring ID. */ const gchar * purple_keyring_get_id(const PurpleKeyring *keyring); @@ -425,8 +425,8 @@ * * This field is required. * - * @param keyring The keyring. - * @param name Friendly user name. + * @keyring: The keyring. + * @name: Friendly user name. */ void purple_keyring_set_name(PurpleKeyring *keyring, const gchar *name); @@ -436,8 +436,8 @@ * * This field is required. * - * @param keyring The keyring. - * @param name Keyring ID. + * @keyring: The keyring. + * @name: Keyring ID. */ void purple_keyring_set_id(PurpleKeyring *keyring, const gchar *id); @@ -447,8 +447,8 @@ * * This field is required. * - * @param keyring The keyring. - * @param read_cb Read password method. + * @keyring: The keyring. + * @read_cb: Read password method. */ void purple_keyring_set_read_password(PurpleKeyring *keyring, @@ -459,8 +459,8 @@ * * This field is required. * - * @param keyring The keyring. - * @param save_cb Save password method. + * @keyring: The keyring. + * @save_cb: Save password method. */ void purple_keyring_set_save_password(PurpleKeyring *keyring, @@ -500,7 +500,7 @@ /** * Gets keyring subsystem error domain. * - * @return keyring subsystem error domain. + * Returns: keyring subsystem error domain. */ GQuark purple_keyring_error_domain(void); @@ -543,7 +543,7 @@ /** * Returns the keyring subsystem handle. * - * @return The keyring subsystem handle. + * Returns: The keyring subsystem handle. */ void * purple_keyring_get_handle(void);
--- a/libpurple/log.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/log.h Wed Jan 29 05:28:33 2014 +0530 @@ -200,15 +200,15 @@ /** * Creates a new log * - * @param type The type of log this is. - * @param name The name of this conversation (buddy name, chat name, + * @type: The type of log this is. + * @name: The name of this conversation (buddy name, chat name, * etc.) - * @param account The account the conversation is occurring on - * @param conv The conversation being logged - * @param time The time this conversation started - * @param tm The time this conversation started, with timezone data, + * @account: The account the conversation is occurring on + * @conv: The conversation being logged + * @time: The time this conversation started + * @tm: The time this conversation started, with timezone data, * if available and if struct tm has the BSD timezone fields. - * @return The new log + * Returns: The new log */ PurpleLog *purple_log_new(PurpleLogType type, const char *name, PurpleAccount *account, PurpleConversation *conv, time_t time, const struct tm *tm); @@ -216,19 +216,19 @@ /** * Frees a log * - * @param log The log to destroy + * @log: The log to destroy */ void purple_log_free(PurpleLog *log); /** * Writes to a log file. Assumes you have checked preferences already. * - * @param log The log to write to - * @param type The type of message being logged - * @param from Whom this message is coming from, or @c NULL for + * @log: The log to write to + * @type: The type of message being logged + * @from: Whom this message is coming from, or @c NULL for * system messages - * @param time A timestamp in UNIX time - * @param message The message to log + * @time: A timestamp in UNIX time + * @message: The message to log */ void purple_log_write(PurpleLog *log, PurpleMessageFlags type, @@ -239,20 +239,20 @@ /** * Reads from a log * - * @param log The log to read from - * @param flags The returned logging flags. + * @log: The log to read from + * @flags: The returned logging flags. * - * @return The contents of this log in Purple Markup. + * Returns: The contents of this log in Purple Markup. */ char *purple_log_read(PurpleLog *log, PurpleLogReadFlags *flags); /** * Returns a list of all available logs * - * @param type The type of the log - * @param name The name of the log - * @param account The account - * @return A sorted list of PurpleLogs + * @type: The type of the log + * @name: The name of the log + * @account: The account + * Returns: A sorted list of PurpleLogs */ GList *purple_log_get_logs(PurpleLogType type, const char *name, PurpleAccount *account); @@ -270,33 +270,33 @@ * destroyed. If a PurpleLogSet is removed from the GHashTable, it * must be freed with purple_log_set_free(). * - * @return A GHashTable of all available unique PurpleLogSets + * Returns: A GHashTable of all available unique PurpleLogSets */ GHashTable *purple_log_get_log_sets(void); /** * Returns a list of all available system logs * - * @param account The account - * @return A sorted list of PurpleLogs + * @account: The account + * Returns: A sorted list of PurpleLogs */ GList *purple_log_get_system_logs(PurpleAccount *account); /** * Returns the size of a log * - * @param log The log - * @return The size of the log, in bytes + * @log: The log + * Returns: The size of the log, in bytes */ int purple_log_get_size(PurpleLog *log); /** * Returns the size, in bytes, of all available logs in this conversation * - * @param type The type of the log - * @param name The name of the log - * @param account The account - * @return The size in bytes + * @type: The type of the log + * @name: The name of the log + * @account: The account + * Returns: The size in bytes */ int purple_log_get_total_size(PurpleLogType type, const char *name, PurpleAccount *account); @@ -304,10 +304,10 @@ * Returns the activity score of a log, based on total size in bytes, * which is then decayed based on age * - * @param type The type of the log - * @param name The name of the log - * @param account The account - * @return The activity score + * @type: The type of the log + * @name: The name of the log + * @account: The account + * Returns: The activity score */ int purple_log_get_activity_score(PurpleLogType type, const char *name, PurpleAccount *account); @@ -318,16 +318,16 @@ * log, unless something changes between the two calls. A return value of @c TRUE, * however, does not guarantee the log can be deleted. * - * @param log The log - * @return A boolean indicating if the log is deletable + * @log: The log + * Returns: A boolean indicating if the log is deletable */ gboolean purple_log_is_deletable(PurpleLog *log); /** * Deletes a log * - * @param log The log - * @return A boolean indicating success or failure + * @log: The log + * Returns: A boolean indicating success or failure */ gboolean purple_log_delete(PurpleLog *log); @@ -336,10 +336,10 @@ * and username. This would be where Purple stores logs created by * the built-in text or HTML loggers. * - * @param type The type of the log. - * @param name The name of the log. - * @param account The account. - * @return The default logger directory for Purple. + * @type: The type of the log. + * @name: The name of the log. + * @account: The account. + * Returns: The default logger directory for Purple. */ char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account); @@ -348,7 +348,7 @@ * * @param y A PurpleLog * @param z Another PurpleLog - * @return A value as specified by GCompareFunc + * Returns: A value as specified by GCompareFunc */ gint purple_log_compare(gconstpointer y, gconstpointer z); @@ -357,14 +357,14 @@ * * @param y A PurpleLogSet * @param z Another PurpleLogSet - * @return A value as specified by GCompareFunc + * Returns: A value as specified by GCompareFunc */ gint purple_log_set_compare(gconstpointer y, gconstpointer z); /** * Frees a log set * - * @param set The log set to destroy + * @set: The log set to destroy */ void purple_log_set_free(PurpleLogSet *set); @@ -388,8 +388,8 @@ * It should only be passed to purple_log_logger_new() and never * called directly. * - * @param log The log to write to. - * @param ext The file extension to give to this log file. + * @log: The log to write to. + * @ext: The file extension to give to this log file. */ void purple_log_common_writer(PurpleLog *log, const char *ext); @@ -402,13 +402,13 @@ * It should only be passed to purple_log_logger_new() and never * called directly. * - * @param type The type of the logs being listed. - * @param name The name of the log. - * @param account The account of the log. - * @param ext The file extension this log format uses. - * @param logger A reference to the logger struct for this log. + * @type: The type of the logs being listed. + * @name: The name of the log. + * @account: The account of the log. + * @ext: The file extension this log format uses. + * @logger: A reference to the logger struct for this log. * - * @return A sorted GList of PurpleLogs matching the parameters. + * Returns: A sorted GList of PurpleLogs matching the parameters. */ GList *purple_log_common_lister(PurpleLogType type, const char *name, PurpleAccount *account, const char *ext, @@ -424,13 +424,13 @@ * It should only be passed to purple_log_logger_new() and never * called directly. * - * @param type The type of the logs being sized. - * @param name The name of the logs to size + * @type: The type of the logs being sized. + * @name: The name of the logs to size * (e.g. the username or chat name). - * @param account The account of the log. - * @param ext The file extension this log format uses. + * @account: The account of the log. + * @ext: The file extension this log format uses. * - * @return The size of all the logs with the specified extension + * Returns: The size of all the logs with the specified extension * for the specified user. */ int purple_log_common_total_sizer(PurpleLogType type, const char *name, @@ -445,9 +445,9 @@ * It should only be passed to purple_log_logger_new() and never * called directly. * - * @param log The PurpleLog to size. + * @log: The PurpleLog to size. * - * @return An integer indicating the size of the log in bytes. + * Returns: An integer indicating the size of the log in bytes. */ int purple_log_common_sizer(PurpleLog *log); @@ -460,9 +460,9 @@ * It should only be passed to purple_log_logger_new() and never * called directly. * - * @param log The PurpleLog to delete. + * @log: The PurpleLog to delete. * - * @return A boolean indicating success or failure. + * Returns: A boolean indicating success or failure. */ gboolean purple_log_common_deleter(PurpleLog *log); @@ -475,9 +475,9 @@ * It should only be passed to purple_log_logger_new() and never * called directly. * - * @param log The PurpleLog to check. + * @log: The PurpleLog to check. * - * @return A boolean indicating if the log is deletable. + * Returns: A boolean indicating if the log is deletable. */ gboolean purple_log_common_is_deletable(PurpleLog *log); @@ -491,9 +491,9 @@ /** * Creates a new logger * - * @param id The logger's id. - * @param name The logger's name. - * @param functions The number of functions being passed. The following + * @id: The logger's id. + * @name: The logger's name. + * @functions: The number of functions being passed. The following * functions are currently available (in order): @c create, * @c write, @c finalize, @c list, @c read, @c size, * @c total_size, @c list_syslog, @c get_log_sets, @@ -506,21 +506,21 @@ * pass @c create, @c NULL (a placeholder for @c write), * and @c finalize (for a total of 3 functions). * - * @return The new logger + * Returns: The new logger */ PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...); /** * Frees a logger * - * @param logger The logger to free + * @logger: The logger to free */ void purple_log_logger_free(PurpleLogLogger *logger); /** * Adds a new logger * - * @param logger The new logger to add + * @logger: The new logger to add */ void purple_log_logger_add (PurpleLogLogger *logger); @@ -528,7 +528,7 @@ * * Removes a logger * - * @param logger The logger to remove + * @logger: The logger to remove */ void purple_log_logger_remove (PurpleLogLogger *logger); @@ -536,7 +536,7 @@ * * Sets the current logger * - * @param logger The logger to set + * @logger: The logger to set */ void purple_log_logger_set (PurpleLogLogger *logger); @@ -544,7 +544,7 @@ * * Returns the current logger * - * @return logger The current logger + * Returns: logger The current logger */ PurpleLogLogger *purple_log_logger_get (void); @@ -552,7 +552,7 @@ * Returns a GList containing the IDs and names of the registered * loggers. * - * @return The list of IDs and names. + * Returns: The list of IDs and names. */ GList *purple_log_logger_get_options(void); @@ -569,7 +569,7 @@ /** * Returns the log subsystem handle. * - * @return The log subsystem handle. + * Returns: The log subsystem handle. */ void *purple_log_get_handle(void);
--- a/libpurple/media-gst.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media-gst.h Wed Jan 29 05:28:33 2014 +0530 @@ -76,35 +76,35 @@ /** * Gets the element type's GType. * - * @return The element type's GType. + * Returns: The element type's GType. */ GType purple_media_element_type_get_type(void); /** * Gets the element info's GType. * - * @return The element info's GType. + * Returns: The element info's GType. */ GType purple_media_element_info_get_type(void); /** * Gets the source from a session * - * @param media The media object the session is in. - * @param sess_id The session id of the session to get the source from. + * @media: The media object the session is in. + * @sess_id: The session id of the session to get the source from. * - * @return The source retrieved. + * Returns: The source retrieved. */ GstElement *purple_media_get_src(PurpleMedia *media, const gchar *sess_id); /** * Gets the tee from a given session/stream. * - * @param media The instance to get the tee from. - * @param session_id The id of the session to get the tee from. - * @param participant Optionally, the participant of the stream to get the tee from. + * @media: The instance to get the tee from. + * @session_id: The id of the session to get the tee from. + * @participant: Optionally, the participant of the stream to get the tee from. * - * @return The GstTee element from the chosen session/stream. + * Returns: The GstTee element from the chosen session/stream. */ GstElement *purple_media_get_tee(PurpleMedia *media, const gchar *session_id, const gchar *participant); @@ -113,20 +113,20 @@ /** * Gets the pipeline from the media manager. * - * @param manager The media manager to get the pipeline from. + * @manager: The media manager to get the pipeline from. * - * @return The pipeline. + * Returns: The pipeline. */ GstElement *purple_media_manager_get_pipeline(PurpleMediaManager *manager); /** * Returns a GStreamer source or sink for audio or video. * - * @param manager The media manager to use to obtain the source/sink. - * @param type The type of source/sink to get. - * @param media The media call this element is requested for. - * @param session_id The id of the session this element is requested for or NULL. - * @param participant The remote user this element is requested for or NULL. + * @manager: The media manager to use to obtain the source/sink. + * @type: The type of source/sink to get. + * @media: The media call this element is requested for. + * @session_id: The id of the session this element is requested for or NULL. + * @participant: The remote user this element is requested for or NULL. */ GstElement *purple_media_manager_get_element(PurpleMediaManager *manager, PurpleMediaSessionType type, PurpleMedia *media, @@ -149,8 +149,8 @@ * Useful to force negotiation of smaller picture resolution more suitable for * use with particular codec and communication protocol without rescaling. * - * @param manager The media manager to set the media formats. - * @param caps Set of allowed media formats. + * @manager: The media manager to set the media formats. + * @caps: Set of allowed media formats. */ void purple_media_manager_set_video_caps(PurpleMediaManager *manager, GstCaps *caps); @@ -158,9 +158,9 @@ /** * Returns current set of media formats limiting the output from video source. * - * @param manager The media manager to get the media formats from. + * @manager: The media manager to get the media formats from. * - * @return @c GstCaps limiting the video source's formats. + * Returns: @c GstCaps limiting the video source's formats. */ GstCaps *purple_media_manager_get_video_caps(PurpleMediaManager *manager);
--- a/libpurple/media.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media.h Wed Jan 29 05:28:33 2014 +0530 @@ -81,60 +81,60 @@ /** * Gets the media class's GType * - * @return The media class's GType. + * Returns: The media class's GType. */ GType purple_media_get_type(void); /** * Gets a list of session IDs. * - * @param media The media session from which to retrieve session IDs. + * @media: The media session from which to retrieve session IDs. * - * @return GList of session IDs. The caller must free the list. + * Returns: GList of session IDs. The caller must free the list. */ GList *purple_media_get_session_ids(PurpleMedia *media); /** * Gets the PurpleAccount this media session is on. * - * @param media The media session to retrieve the account from. + * @media: The media session to retrieve the account from. * - * @return The account retrieved. + * Returns: The account retrieved. */ PurpleAccount *purple_media_get_account(PurpleMedia *media); /** * Gets the protocol data from the media session. * - * @param media The media session to retrieve the protocol data from. + * @media: The media session to retrieve the protocol data from. * - * @return The protocol data retrieved. + * Returns: The protocol data retrieved. */ gpointer purple_media_get_protocol_data(PurpleMedia *media); /** * Sets the protocol data on the media session. * - * @param media The media session to set the protocol data on. - * @param protocol_data The data to set on the media session. + * @media: The media session to set the protocol data on. + * @protocol_data: The data to set on the media session. */ void purple_media_set_protocol_data(PurpleMedia *media, gpointer protocol_data); /** * Signals an error in the media session. * - * @param media The media object to set the state on. - * @param error The format of the error message to send in the signal. - * @param ... The arguments to plug into the format. + * @media: The media object to set the state on. + * @error: The format of the error message to send in the signal. + * @...: The arguments to plug into the format. */ void purple_media_error(PurpleMedia *media, const gchar *error, ...); /** * Ends all streams that match the given parameters * - * @param media The media object with which to end streams. - * @param session_id The session to end streams on. - * @param participant The participant to end streams with. + * @media: The media object with which to end streams. + * @session_id: The session to end streams on. + * @participant: The participant to end streams with. */ void purple_media_end(PurpleMedia *media, const gchar *session_id, const gchar *participant); @@ -142,11 +142,11 @@ /** * Signals different information about the given stream. * - * @param media The media instance to containing the stream to signal. - * @param type The type of info being signaled. - * @param session_id The id of the session of the stream being signaled. - * @param participant The participant of the stream being signaled. - * @param local TRUE if the info originated locally, FALSE if on the remote end. + * @media: The media instance to containing the stream to signal. + * @type: The type of info being signaled. + * @session_id: The id of the session of the stream being signaled. + * @participant: The participant of the stream being signaled. + * @local: TRUE if the info originated locally, FALSE if on the remote end. */ void purple_media_stream_info(PurpleMedia *media, PurpleMediaInfoType type, const gchar *session_id, const gchar *participant, @@ -164,9 +164,9 @@ * - "sdes-note" : The NOTE to put in SDES messages * - "sdes-phone" : The PHONE to put in SDES messages * - * @param media The media object to set the parameters on. - * @param num_params The number of parameters to pass - * @param params Array of @c GParameter to pass + * @media: The media object to set the parameters on. + * @num_params: The number of parameters to pass + * @params: Array of @c GParameter to pass */ void purple_media_set_params(PurpleMedia *media, guint num_params, GParameter *params); @@ -176,19 +176,19 @@ * * The list is owned by the @c PurpleMedia internals and should NOT be freed. * - * @param media The media object + * @media: The media object * - * @return NULL-terminated array of names of supported parameters. + * Returns: NULL-terminated array of names of supported parameters. */ const gchar **purple_media_get_available_params(PurpleMedia *media); /** * Checks if given optional parameter is supported by the media backend. * - * @param media The media object - * @param param name of parameter + * @media: The media object + * @param: name of parameter * - * @return @c TRUE if backend recognizes the parameter, @c FALSE otherwise. + * Returns: @c TRUE if backend recognizes the parameter, @c FALSE otherwise. */ gboolean purple_media_param_is_supported(PurpleMedia *media, const gchar *param); @@ -198,16 +198,16 @@ * It only adds a stream to one audio session or video session as * the @c sess_id must be unique between sessions. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to add the stream to. - * @param who The name of the remote user to add the stream for. - * @param type The type of stream to create. - * @param initiator Whether or not the local user initiated the stream. - * @param transmitter The transmitter to use for the stream. - * @param num_params The number of parameters to pass to Farsight. - * @param params The parameters to pass to Farsight. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to add the stream to. + * @who: The name of the remote user to add the stream for. + * @type: The type of stream to create. + * @initiator: Whether or not the local user initiated the stream. + * @transmitter: The transmitter to use for the stream. + * @num_params: The number of parameters to pass to Farsight. + * @params: The parameters to pass to Farsight. * - * @return @c TRUE The stream was added successfully, @c FALSE otherwise. + * Returns: @c TRUE The stream was added successfully, @c FALSE otherwise. */ gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id, const gchar *who, PurpleMediaSessionType type, @@ -217,39 +217,39 @@ /** * Gets the session type from a session * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to get the type from. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to get the type from. * - * @return The retreived session type. + * Returns: The retreived session type. */ PurpleMediaSessionType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id); /** * Gets the PurpleMediaManager this media session is a part of. * - * @param media The media object to get the manager instance from. + * @media: The media object to get the manager instance from. * - * @return The PurpleMediaManager instance retrieved. + * Returns: The PurpleMediaManager instance retrieved. */ struct _PurpleMediaManager *purple_media_get_manager(PurpleMedia *media); /** * Gets the codecs from a session. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to get the codecs from. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to get the codecs from. * - * @return The retreieved codecs. + * Returns: The retreieved codecs. */ GList *purple_media_get_codecs(PurpleMedia *media, const gchar *sess_id); /** * Adds remote candidates to the stream. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session find the stream in. - * @param participant The name of the remote user to add the candidates for. - * @param remote_candidates The remote candidates to add. + * @media: The media object to find the session in. + * @sess_id: The session id of the session find the stream in. + * @participant: The name of the remote user to add the candidates for. + * @remote_candidates: The remote candidates to add. */ void purple_media_add_remote_candidates(PurpleMedia *media, const gchar *sess_id, @@ -259,9 +259,9 @@ /** * Gets the local candidates from a stream. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to find the stream in. - * @param participant The name of the remote user to get the candidates from. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to find the stream in. + * @participant: The name of the remote user to get the candidates from. */ GList *purple_media_get_local_candidates(PurpleMedia *media, const gchar *sess_id, @@ -270,12 +270,12 @@ /** * Gets the active local candidates for the stream. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to find the stream in. - * @param participant The name of the remote user to get the active candidate + * @media: The media object to find the session in. + * @sess_id: The session id of the session to find the stream in. + * @participant: The name of the remote user to get the active candidate * from. * - * @return The active candidates retrieved. + * Returns: The active candidates retrieved. */ GList *purple_media_get_active_local_candidates(PurpleMedia *media, const gchar *sess_id, const gchar *participant); @@ -283,12 +283,12 @@ /** * Gets the active remote candidates for the stream. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to find the stream in. - * @param participant The name of the remote user to get the remote candidate + * @media: The media object to find the session in. + * @sess_id: The session id of the session to find the stream in. + * @participant: The name of the remote user to get the remote candidate * from. * - * @return The remote candidates retrieved. + * Returns: The remote candidates retrieved. */ GList *purple_media_get_active_remote_candidates(PurpleMedia *media, const gchar *sess_id, const gchar *participant); @@ -296,12 +296,12 @@ /** * Sets remote candidates from the stream. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session find the stream in. - * @param participant The name of the remote user to set the candidates from. - * @param codecs The list of remote codecs to set. + * @media: The media object to find the session in. + * @sess_id: The session id of the session find the stream in. + * @participant: The name of the remote user to set the candidates from. + * @codecs: The list of remote codecs to set. * - * @return @c TRUE The codecs were set successfully, or @c FALSE otherwise. + * Returns: @c TRUE The codecs were set successfully, or @c FALSE otherwise. */ gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id, const gchar *participant, GList *codecs); @@ -309,11 +309,11 @@ /** * Returns whether or not the candidates for set of streams are prepared * - * @param media The media object to find the remote user in. - * @param session_id The session id of the session to check. - * @param participant The remote user to check for. + * @media: The media object to find the remote user in. + * @session_id: The session id of the session to check. + * @participant: The remote user to check for. * - * @return @c TRUE All streams for the given session_id/participant combination have candidates prepared, @c FALSE otherwise. + * Returns: @c TRUE All streams for the given session_id/participant combination have candidates prepared, @c FALSE otherwise. */ gboolean purple_media_candidates_prepared(PurpleMedia *media, const gchar *session_id, const gchar *participant); @@ -321,32 +321,32 @@ /** * Sets the send codec for the a session. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to set the codec for. - * @param codec The codec to set the session to stream. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to set the codec for. + * @codec: The codec to set the session to stream. * - * @return @c TRUE The codec was successfully changed, or @c FALSE otherwise. + * Returns: @c TRUE The codec was successfully changed, or @c FALSE otherwise. */ gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, PurpleMediaCodec *codec); /** * Gets whether a session's codecs are ready to be used. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to check. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to check. * - * @return @c TRUE The codecs are ready, or @c FALSE otherwise. + * Returns: @c TRUE The codecs are ready, or @c FALSE otherwise. */ gboolean purple_media_codecs_ready(PurpleMedia *media, const gchar *sess_id); /** * Gets whether the local user is the conference/session/stream's initiator. * - * @param media The media instance to find the session in. - * @param sess_id The session id of the session to check. - * @param participant The participant of the stream to check. + * @media: The media instance to find the session in. + * @sess_id: The session id of the session to check. + * @participant: The participant of the stream to check. * - * @return TRUE if the local user is the stream's initator, else FALSE. + * Returns: TRUE if the local user is the stream's initator, else FALSE. */ gboolean purple_media_is_initiator(PurpleMedia *media, const gchar *sess_id, const gchar *participant); @@ -354,11 +354,11 @@ /** * Gets whether a streams selected have been accepted. * - * @param media The media object to find the session in. - * @param sess_id The session id of the session to check. - * @param participant The participant to check. + * @media: The media object to find the session in. + * @sess_id: The session id of the session to check. + * @participant: The participant to check. * - * @return @c TRUE The selected streams have been accepted, or @c FALSE otherwise. + * Returns: @c TRUE The selected streams have been accepted, or @c FALSE otherwise. */ gboolean purple_media_accepted(PurpleMedia *media, const gchar *sess_id, const gchar *participant); @@ -366,19 +366,19 @@ /** * Sets the input volume of all the selected sessions. * - * @param media The media object the sessions are in. - * @param session_id The session to select (if any). - * @param level The level to set the volume to. + * @media: The media object the sessions are in. + * @session_id: The session to select (if any). + * @level: The level to set the volume to. */ void purple_media_set_input_volume(PurpleMedia *media, const gchar *session_id, double level); /** * Sets the output volume of all the selected streams. * - * @param media The media object the streams are in. - * @param session_id The session to limit the streams to (if any). - * @param participant The participant to limit the streams to (if any). - * @param level The level to set the volume to. + * @media: The media object the streams are in. + * @session_id: The session to limit the streams to (if any). + * @participant: The participant to limit the streams to (if any). + * @level: The level to set the volume to. */ void purple_media_set_output_volume(PurpleMedia *media, const gchar *session_id, const gchar *participant, double level); @@ -386,12 +386,12 @@ /** * Sets a video output window for the given session/stream. * - * @param media The media instance to set the output window on. - * @param session_id The session to set the output window on. - * @param participant Optionally, the participant to set the output window on. - * @param window_id The window id use for embedding the video in. + * @media: The media instance to set the output window on. + * @session_id: The session to set the output window on. + * @participant: Optionally, the participant to set the output window on. + * @window_id: The window id use for embedding the video in. * - * @return An id to reference the output window. + * Returns: An id to reference the output window. */ gulong purple_media_set_output_window(PurpleMedia *media, const gchar *session_id, const gchar *participant, @@ -400,7 +400,7 @@ /** * Removes all output windows from a given media session. * - * @param media The instance to remove all output windows from. + * @media: The instance to remove all output windows from. */ void purple_media_remove_output_windows(PurpleMedia *media);
--- a/libpurple/media/backend-fs2.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media/backend-fs2.h Wed Jan 29 05:28:33 2014 +0530 @@ -49,7 +49,7 @@ /** * Gets the type of the Farsight 2 media backend object. * - * @return The Farsight 2 media backend's GType + * Returns: The Farsight 2 media backend's GType */ GType purple_media_backend_fs2_get_type(void);
--- a/libpurple/media/backend-iface.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media/backend-iface.h Wed Jan 29 05:28:33 2014 +0530 @@ -76,23 +76,23 @@ /** * Gets the media backend's GType. * - * @return The media backend's GType. + * Returns: The media backend's GType. */ GType purple_media_backend_get_type(void); /** * Creates and adds a stream to the media backend. * - * @param self The backend to add the stream to. - * @param sess_id The session id of the stream to add. - * @param who The remote participant of the stream to add. - * @param type The media type and direction of the stream to add. - * @param initiator True if the local user initiated the stream. - * @param transmitter The string id of the tranmsitter to use. - * @param num_params The number of parameters in the param parameter. - * @param params The additional parameters to pass when creating the stream. + * @self: The backend to add the stream to. + * @sess_id: The session id of the stream to add. + * @who: The remote participant of the stream to add. + * @type: The media type and direction of the stream to add. + * @initiator: True if the local user initiated the stream. + * @transmitter: The string id of the tranmsitter to use. + * @num_params: The number of parameters in the param parameter. + * @params: The additional parameters to pass when creating the stream. * - * @return True if the stream was successfully created, othewise False. + * Returns: True if the stream was successfully created, othewise False. */ gboolean purple_media_backend_add_stream(PurpleMediaBackend *self, const gchar *sess_id, const gchar *who, @@ -103,10 +103,10 @@ /** * Add remote candidates to a stream. * - * @param self The backend the stream is in. - * @param sess_id The session id associated with the stream. - * @param participant The participant associated with the stream. - * @param remote_candidates The list of remote candidates to add. + * @self: The backend the stream is in. + * @sess_id: The session id associated with the stream. + * @participant: The participant associated with the stream. + * @remote_candidates: The list of remote candidates to add. */ void purple_media_backend_add_remote_candidates(PurpleMediaBackend *self, const gchar *sess_id, const gchar *participant, @@ -118,10 +118,10 @@ * A codec is ready if all of the attributes and additional * parameters have been collected. * - * @param self The media backend the session is in. - * @param sess_id The session id of the session to check. + * @self: The media backend the session is in. + * @sess_id: The session id of the session to check. * - * @return True if the codecs are ready, otherwise False. + * Returns: True if the codecs are ready, otherwise False. */ gboolean purple_media_backend_codecs_ready(PurpleMediaBackend *self, const gchar *sess_id); @@ -132,10 +132,10 @@ * The intersection list consists of all codecs that are compatible * between the local and remote software. * - * @param self The media backend the session is in. - * @param sess_id The session id of the session to use. + * @self: The media backend the session is in. + * @sess_id: The session id of the session to use. * - * @return The codec intersection list. + * Returns: The codec intersection list. */ GList *purple_media_backend_get_codecs(PurpleMediaBackend *self, const gchar *sess_id); @@ -143,11 +143,11 @@ /** * Gets the list of local candidates for a stream. * - * @param self The media backend the stream is in. - * @param sess_id The session id associated with the stream. - * @param particilant The participant associated with the stream. + * @self: The media backend the stream is in. + * @sess_id: The session id associated with the stream. + * @particilant: The participant associated with the stream. * - * @return The list of local candidates. + * Returns: The list of local candidates. */ GList *purple_media_backend_get_local_candidates(PurpleMediaBackend *self, const gchar *sess_id, const gchar *participant); @@ -155,12 +155,12 @@ /** * Sets the remote codecs on a stream. * - * @param self The media backend the stream is in. - * @param sess_id The session id the stream is associated with. - * @param participant The participant the stream is associated with. - * @param codecs The list of remote codecs to set. + * @self: The media backend the stream is in. + * @sess_id: The session id the stream is associated with. + * @participant: The participant the stream is associated with. + * @codecs: The list of remote codecs to set. * - * @return True if the remote codecs were set successfully, otherwise False. + * Returns: True if the remote codecs were set successfully, otherwise False. */ gboolean purple_media_backend_set_remote_codecs(PurpleMediaBackend *self, const gchar *sess_id, const gchar *participant, @@ -169,11 +169,11 @@ /** * Sets which codec format to send media content in for a session. * - * @param self The media backend the session is in. - * @param sess_id The session id of the session to set the codec for. - * @param codec The codec to set. + * @self: The media backend the session is in. + * @sess_id: The session id of the session to set the codec for. + * @codec: The codec to set. * - * @return True if set successfully, otherwise False. + * Returns: True if set successfully, otherwise False. */ gboolean purple_media_backend_set_send_codec(PurpleMediaBackend *self, const gchar *sess_id, PurpleMediaCodec *codec); @@ -181,9 +181,9 @@ /** * Sets various optional parameters of the media backend. * - * @param self The media backend to set the parameters on. - * @param num_params The number of parameters to pass to backend - * @param params Array of @c GParameter to pass to backend + * @self: The media backend to set the parameters on. + * @num_params: The number of parameters to pass to backend + * @params: Array of @c GParameter to pass to backend */ void purple_media_backend_set_params(PurpleMediaBackend *self, guint num_params, GParameter *params); @@ -193,9 +193,9 @@ * * The list should NOT be freed. * - * @param self The media backend + * @self: The media backend * - * @return NULL-terminated array of names of supported parameters. + * Returns: NULL-terminated array of names of supported parameters. */ const gchar **purple_media_backend_get_available_params(PurpleMediaBackend *self);
--- a/libpurple/media/candidate.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media/candidate.h Wed Jan 29 05:28:33 2014 +0530 @@ -46,21 +46,21 @@ /** * Gets the type of the media candidate structure. * - * @return The media canditate's GType + * Returns: The media canditate's GType */ GType purple_media_candidate_get_type(void); /** * Creates a PurpleMediaCandidate instance. * - * @param foundation The foundation of the candidate. - * @param component_id The component this candidate is for. - * @param type The type of candidate. - * @param proto The protocol this component is for. - * @param ip The IP address of this component. - * @param port The network port. + * @foundation: The foundation of the candidate. + * @component_id: The component this candidate is for. + * @type: The type of candidate. + * @proto: The protocol this component is for. + * @ip: The IP address of this component. + * @port: The network port. * - * @return The newly created PurpleMediaCandidate instance. + * Returns: The newly created PurpleMediaCandidate instance. */ PurpleMediaCandidate *purple_media_candidate_new( const gchar *foundation, guint component_id, @@ -71,9 +71,9 @@ /** * Copies a PurpleMediaCandidate. * - * @param candidate The candidate to copy. + * @candidate: The candidate to copy. * - * @return The copy of the PurpleMediaCandidate. + * Returns: The copy of the PurpleMediaCandidate. */ PurpleMediaCandidate *purple_media_candidate_copy( PurpleMediaCandidate *candidate); @@ -81,52 +81,52 @@ /** * Copies a GList of PurpleMediaCandidate and its contents. * - * @param candidates The list of candidates to be copied. + * @candidates: The list of candidates to be copied. * - * @return The copy of the GList. + * Returns: The copy of the GList. */ GList *purple_media_candidate_list_copy(GList *candidates); /** * Frees a GList of PurpleMediaCandidate and its contents. * - * @param candidates The list of candidates to be freed. + * @candidates: The list of candidates to be freed. */ void purple_media_candidate_list_free(GList *candidates); /** * Gets the foundation (identifier) from the candidate. * - * @param candidate The candidate to get the foundation from. + * @candidate: The candidate to get the foundation from. * - * @return The foundation. + * Returns: The foundation. */ gchar *purple_media_candidate_get_foundation(PurpleMediaCandidate *candidate); /** * Gets the component id (rtp or rtcp) * - * @param candidate The candidate to get the compnent id from. + * @candidate: The candidate to get the compnent id from. * - * @return The component id. + * Returns: The component id. */ guint purple_media_candidate_get_component_id(PurpleMediaCandidate *candidate); /** * Gets the IP address. * - * @param candidate The candidate to get the IP address from. + * @candidate: The candidate to get the IP address from. * - * @return The IP address. + * Returns: The IP address. */ gchar *purple_media_candidate_get_ip(PurpleMediaCandidate *candidate); /** * Gets the port. * - * @param candidate The candidate to get the port from. + * @candidate: The candidate to get the port from. * - * @return The port. + * Returns: The port. */ guint16 purple_media_candidate_get_port(PurpleMediaCandidate *candidate); @@ -135,9 +135,9 @@ * * This can be NULL. * - * @param candidate The candidate to get the base IP address from. + * @candidate: The candidate to get the base IP address from. * - * @return The base IP address. + * Returns: The base IP address. */ gchar *purple_media_candidate_get_base_ip(PurpleMediaCandidate *candidate); @@ -146,18 +146,18 @@ * * Invalid if the base IP is NULL. * - * @param candidate The candidate to get the base port. + * @candidate: The candidate to get the base port. * - * @return The base port. + * Returns: The base port. */ guint16 purple_media_candidate_get_base_port(PurpleMediaCandidate *candidate); /** * Gets the protocol (TCP or UDP). * - * @param candidate The candidate to get the protocol from. + * @candidate: The candidate to get the protocol from. * - * @return The protocol. + * Returns: The protocol. */ PurpleMediaNetworkProtocol purple_media_candidate_get_protocol( PurpleMediaCandidate *candidate); @@ -165,18 +165,18 @@ /** * Gets the priority. * - * @param candidate The candidate to get the priority from. + * @candidate: The candidate to get the priority from. * - * @return The priority. + * Returns: The priority. */ guint32 purple_media_candidate_get_priority(PurpleMediaCandidate *candidate); /** * Gets the candidate type. * - * @param candidate The candidate to get the candidate type from. + * @candidate: The candidate to get the candidate type from. * - * @return The candidate type. + * Returns: The candidate type. */ PurpleMediaCandidateType purple_media_candidate_get_candidate_type( PurpleMediaCandidate *candidate); @@ -186,9 +186,9 @@ * * This can be NULL. It depends on the transmission type. * - * @param The candidate to get the username from. + * @The: candidate to get the username from. * - * @return The username. + * Returns: The username. */ gchar *purple_media_candidate_get_username(PurpleMediaCandidate *candidate); @@ -197,18 +197,18 @@ * * This can be NULL. It depends on the transmission type. * - * @param The candidate to get the password from. + * @The: candidate to get the password from. * - * @return The password. + * Returns: The password. */ gchar *purple_media_candidate_get_password(PurpleMediaCandidate *candidate); /** * Gets the TTL. * - * @param The candidate to get the TTL from. + * @The: candidate to get the TTL from. * - * @return The TTL. + * Returns: The TTL. */ guint purple_media_candidate_get_ttl(PurpleMediaCandidate *candidate);
--- a/libpurple/media/codec.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media/codec.h Wed Jan 29 05:28:33 2014 +0530 @@ -49,19 +49,19 @@ /** * Gets the type of the media codec structure. * - * @return The media codec's GType + * Returns: The media codec's GType */ GType purple_media_codec_get_type(void); /** * Creates a new PurpleMediaCodec instance. * - * @param id Codec identifier. - * @param encoding_name Name of the media type this encodes. - * @param media_type PurpleMediaSessionType of this codec. - * @param clock_rate The clock rate this codec encodes at, if applicable. + * @id: Codec identifier. + * @encoding_name: Name of the media type this encodes. + * @media_type: PurpleMediaSessionType of this codec. + * @clock_rate: The clock rate this codec encodes at, if applicable. * - * @return The newly created PurpleMediaCodec. + * Returns: The newly created PurpleMediaCodec. */ PurpleMediaCodec *purple_media_codec_new(int id, const char *encoding_name, PurpleMediaSessionType media_type, guint clock_rate); @@ -69,36 +69,36 @@ /** * Gets the codec id. * - * @param The codec to get the id from. + * @The: codec to get the id from. * - * @return The codec id. + * Returns: The codec id. */ guint purple_media_codec_get_id(PurpleMediaCodec *codec); /** * Gets the encoding name. * - * @param The codec to get the encoding name from. + * @The: codec to get the encoding name from. * - * @return The encoding name. + * Returns: The encoding name. */ gchar *purple_media_codec_get_encoding_name(PurpleMediaCodec *codec); /** * Gets the clock rate. * - * @param The codec to get the clock rate from. + * @The: codec to get the clock rate from. * - * @return The clock rate. + * Returns: The clock rate. */ guint purple_media_codec_get_clock_rate(PurpleMediaCodec *codec); /** * Gets the number of channels. * - * @param The codec to get the number of channels from. + * @The: codec to get the number of channels from. * - * @return The number of channels. + * Returns: The number of channels. */ guint purple_media_codec_get_channels(PurpleMediaCodec *codec); @@ -107,9 +107,9 @@ * * The list consists of PurpleKeyValuePair's. * - * @param The codec to get the optional parameters from. + * @The: codec to get the optional parameters from. * - * @return The list of optional parameters. The list is owned by the codec and + * Returns: The list of optional parameters. The list is owned by the codec and * should not be freed. */ GList *purple_media_codec_get_optional_parameters(PurpleMediaCodec *codec); @@ -117,9 +117,9 @@ /** * Adds an optional parameter to the codec. * - * @param codec The codec to add the parameter to. - * @param name The name of the parameter to add. - * @param value The value of the parameter to add. + * @codec: The codec to add the parameter to. + * @name: The name of the parameter to add. + * @value: The value of the parameter to add. */ void purple_media_codec_add_optional_parameter(PurpleMediaCodec *codec, const gchar *name, const gchar *value); @@ -127,8 +127,8 @@ /** * Removes an optional parameter from the codec. * - * @param codec The codec to remove the parameter from. - * @param param A pointer to the parameter to remove. + * @codec: The codec to remove the parameter from. + * @param: A pointer to the parameter to remove. */ void purple_media_codec_remove_optional_parameter(PurpleMediaCodec *codec, PurpleKeyValuePair *param); @@ -136,11 +136,11 @@ /** * Gets an optional parameter based on the values given. * - * @param codec The codec to find the parameter in. - * @param name The name of the parameter to search for. - * @param value The value to search for or NULL. + * @codec: The codec to find the parameter in. + * @name: The name of the parameter to search for. + * @value: The value to search for or NULL. * - * @return The value found or NULL. + * Returns: The value found or NULL. */ PurpleKeyValuePair *purple_media_codec_get_optional_parameter( PurpleMediaCodec *codec, const gchar *name, @@ -149,34 +149,34 @@ /** * Copies a PurpleMediaCodec object. * - * @param codec The codec to copy. + * @codec: The codec to copy. * - * @return The copy of the codec. + * Returns: The copy of the codec. */ PurpleMediaCodec *purple_media_codec_copy(PurpleMediaCodec *codec); /** * Copies a GList of PurpleMediaCodec and its contents. * - * @param codecs The list of codecs to be copied. + * @codecs: The list of codecs to be copied. * - * @return The copy of the GList. + * Returns: The copy of the GList. */ GList *purple_media_codec_list_copy(GList *codecs); /** * Frees a GList of PurpleMediaCodec and its contents. * - * @param codecs The list of codecs to be freed. + * @codecs: The list of codecs to be freed. */ void purple_media_codec_list_free(GList *codecs); /** * Creates a string representation of the codec. * - * @param codec The codec to create the string of. + * @codec: The codec to create the string of. * - * @return The new string representation. + * Returns: The new string representation. */ gchar *purple_media_codec_to_string(const PurpleMediaCodec *codec);
--- a/libpurple/media/enum-types.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/media/enum-types.h Wed Jan 29 05:28:33 2014 +0530 @@ -106,42 +106,42 @@ /** * Gets the media candidate type's GType * - * @return The media candidate type's GType. + * Returns: The media candidate type's GType. */ GType purple_media_candidate_type_get_type(void); /** * Gets the type of the media caps flags * - * @return The media caps flags' GType + * Returns: The media caps flags' GType */ GType purple_media_caps_get_type(void); /** * Gets the type of the info type enum * - * @return The info type enum's GType + * Returns: The info type enum's GType */ GType purple_media_info_type_get_type(void); /** * Gets the media network protocol's GType * - * @return The media network protocol's GType. + * Returns: The media network protocol's GType. */ GType purple_media_network_protocol_get_type(void); /** * Gets the media session type's GType * - * @return The media session type's GType. + * Returns: The media session type's GType. */ GType purple_media_session_type_get_type(void); /** * Gets the type of the state-changed enum * - * @return The state-changed enum's GType + * Returns: The state-changed enum's GType */ GType purple_media_state_changed_get_type(void);
--- a/libpurple/mediamanager.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/mediamanager.h Wed Jan 29 05:28:33 2014 +0530 @@ -78,27 +78,27 @@ /** * Gets the media manager's GType. * - * @return The media manager's GType. + * Returns: The media manager's GType. */ GType purple_media_manager_get_type(void); /** * Gets the "global" media manager object. It's created if it doesn't already exist. * - * @return The "global" instance of the media manager object. + * Returns: The "global" instance of the media manager object. */ PurpleMediaManager *purple_media_manager_get(void); /** * Creates a media session. * - * @param manager The media manager to create the session under. - * @param account The account to create the session on. - * @param conference_type The conference type to feed into Farsight2. - * @param remote_user The remote user to initiate the session with. - * @param initiator TRUE if the local user is the initiator of this media call, FALSE otherwise. + * @manager: The media manager to create the session under. + * @account: The account to create the session on. + * @conference_type: The conference type to feed into Farsight2. + * @remote_user: The remote user to initiate the session with. + * @initiator: TRUE if the local user is the initiator of this media call, FALSE otherwise. * - * @return A newly created media session. + * Returns: A newly created media session. */ PurpleMedia *purple_media_manager_create_media(PurpleMediaManager *manager, PurpleAccount *account, @@ -109,19 +109,19 @@ /** * Gets all of the media sessions. * - * @param manager The media manager to get all of the sessions from. + * @manager: The media manager to get all of the sessions from. * - * @return A list of all the media sessions. + * Returns: A list of all the media sessions. */ GList *purple_media_manager_get_media(PurpleMediaManager *manager); /** * Gets all of the media sessions for a given account. * - * @param manager The media manager to get the sessions from. - * @param account The account the sessions are on. + * @manager: The media manager to get the sessions from. + * @account: The account the sessions are on. * - * @return A list of the media sessions on the given account. + * Returns: A list of the media sessions on the given account. */ GList *purple_media_manager_get_media_by_account( PurpleMediaManager *manager, PurpleAccount *account); @@ -129,8 +129,8 @@ /** * Removes a media session from the media manager. * - * @param manager The media manager to remove the media session from. - * @param media The media session to remove. + * @manager: The media manager to remove the media session from. + * @media: The media session to remove. */ void purple_media_manager_remove_media(PurpleMediaManager *manager, @@ -141,12 +141,12 @@ * * This shouldn't be called outside of mediamanager.c and media.c * - * @param manager Manager the output windows are registered with. - * @param media Media session the output windows are registered for. - * @param session_id The session the output windows are registered with. - * @param participant The participant the output windows are registered with. + * @manager: Manager the output windows are registered with. + * @media: Media session the output windows are registered for. + * @session_id: The session the output windows are registered with. + * @participant: The participant the output windows are registered with. * - * @return TRUE if it succeeded, FALSE if it failed. + * Returns: TRUE if it succeeded, FALSE if it failed. */ gboolean purple_media_manager_create_output_window( PurpleMediaManager *manager, PurpleMedia *media, @@ -155,13 +155,13 @@ /** * Registers a video output window to be created for a given stream. * - * @param manager The manager to register the output window with. - * @param media The media instance to find the stream in. - * @param session_id The session the stream is associated with. - * @param participant The participant the stream is associated with. - * @param window_id The window ID to embed the video in. + * @manager: The manager to register the output window with. + * @media: The media instance to find the stream in. + * @session_id: The session the stream is associated with. + * @participant: The participant the stream is associated with. + * @window_id: The window ID to embed the video in. * - * @return A unique ID to the registered output window, 0 if it failed. + * Returns: A unique ID to the registered output window, 0 if it failed. */ gulong purple_media_manager_set_output_window(PurpleMediaManager *manager, PurpleMedia *media, const gchar *session_id, @@ -170,10 +170,10 @@ /** * Remove a previously registerd output window. * - * @param manager The manager the output window was registered with. - * @param output_window_id The ID of the output window. + * @manager: The manager the output window was registered with. + * @output_window_id: The ID of the output window. * - * @return TRUE if it found the output window and was successful, else FALSE. + * Returns: TRUE if it found the output window and was successful, else FALSE. */ gboolean purple_media_manager_remove_output_window( PurpleMediaManager *manager, gulong output_window_id); @@ -181,10 +181,10 @@ /** * Remove all output windows for a given conference/session/participant/stream. * - * @param manager The manager the output windows were registered with. - * @param media The media instance the output windows were registered for. - * @param session_id The session the output windows were registered for. - * @param participant The participant the output windows were registered for. + * @manager: The manager the output windows were registered with. + * @media: The media instance the output windows were registered for. + * @session_id: The session the output windows were registered for. + * @participant: The participant the output windows were registered for. */ void purple_media_manager_remove_output_windows( PurpleMediaManager *manager, PurpleMedia *media, @@ -193,8 +193,8 @@ /** * Sets which media caps the UI supports. * - * @param manager The manager to set the caps on. - * @param caps The caps to set. + * @manager: The manager to set the caps on. + * @caps: The caps to set. */ void purple_media_manager_set_ui_caps(PurpleMediaManager *manager, PurpleMediaCaps caps); @@ -202,17 +202,17 @@ /** * Gets which media caps the UI supports. * - * @param manager The manager to get caps from. + * @manager: The manager to get caps from. * - * @return caps The caps retrieved. + * Returns: caps The caps retrieved. */ PurpleMediaCaps purple_media_manager_get_ui_caps(PurpleMediaManager *manager); /** * Sets which media backend type media objects will use. * - * @param manager The manager to set the caps on. - * @param backend_type The media backend type to use. + * @manager: The manager to set the caps on. + * @backend_type: The media backend type to use. */ void purple_media_manager_set_backend_type(PurpleMediaManager *manager, GType backend_type); @@ -220,9 +220,9 @@ /** * Gets which media backend type media objects will use. * - * @param manager The manager to get the media backend type from. + * @manager: The manager to get the media backend type from. * - * @return The type of media backend type media objects will use. + * Returns: The type of media backend type media objects will use. */ GType purple_media_manager_get_backend_type(PurpleMediaManager *manager);
--- a/libpurple/mime.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/mime.h Wed Jan 29 05:28:33 2014 +0530 @@ -54,26 +54,26 @@ /** * Frees memory used in a MIME document and all of its parts and fields * - * @param doc The MIME document to free. + * @doc: The MIME document to free. */ void purple_mime_document_free(PurpleMimeDocument *doc); /** * Parse a MIME document from a NUL-terminated string. * - * @param buf The NULL-terminated string containing the MIME-encoded data. + * @buf: The NULL-terminated string containing the MIME-encoded data. * - * @returns A MIME document. + * Returns:s A MIME document. */ PurpleMimeDocument *purple_mime_document_parse(const char *buf); /** * Parse a MIME document from a string * - * @param buf The string containing the MIME-encoded data. - * @param len Length of buf. + * @buf: The string containing the MIME-encoded data. + * @len: Length of buf. * - * @returns A MIME document. + * Returns:s A MIME document. */ PurpleMimeDocument *purple_mime_document_parsen(const char *buf, gsize len); @@ -85,9 +85,9 @@ /** * The list of fields in the header of a document * - * @param doc The MIME document. + * @doc: The MIME document. * - * @constreturn A list of strings indicating the fields (but not the values + * Returns: (TODO const): A list of strings indicating the fields (but not the values * of the fields) in the header of doc. */ GList *purple_mime_document_get_fields(PurpleMimeDocument *doc); @@ -95,10 +95,10 @@ /** * Get the value of a specific field in the header of a document. * - * @param doc The MIME document. - * @param field Case-insensitive field name. + * @doc: The MIME document. + * @field: Case-insensitive field name. * - * @returns Value associated with the indicated header field, or + * Returns:s Value associated with the indicated header field, or * NULL if the field doesn't exist. */ const char *purple_mime_document_get_field(PurpleMimeDocument *doc, @@ -108,9 +108,9 @@ * Set or replace the value of a specific field in the header of a * document. * - * @param doc The MIME document. - * @param field Case-insensitive field name. - * @param value Value to associate with the indicated header field, + * @doc: The MIME document. + * @field: Case-insensitive field name. + * @value: Value to associate with the indicated header field, * of NULL to remove the field. */ void purple_mime_document_set_field(PurpleMimeDocument *doc, @@ -120,16 +120,16 @@ /** * The list of parts in a multipart document. * - * @param doc The MIME document. + * @doc: The MIME document. * - * @constreturn List of PurpleMimePart contained within doc. + * Returns: (TODO const): List of PurpleMimePart contained within doc. */ GList *purple_mime_document_get_parts(PurpleMimeDocument *doc); /** * Create and insert a new part into a MIME document. * - * @param doc The new part's parent MIME document. + * @doc: The new part's parent MIME document. */ PurpleMimePart *purple_mime_part_new(PurpleMimeDocument *doc); @@ -137,9 +137,9 @@ /** * The list of fields in the header of a document part. * - * @param part The MIME document part. + * @part: The MIME document part. * - * @constreturn List of strings indicating the fields (but not the values + * Returns: (TODO const): List of strings indicating the fields (but not the values * of the fields) in the header of part. */ GList *purple_mime_part_get_fields(PurpleMimePart *part); @@ -148,10 +148,10 @@ /** * Get the value of a specific field in the header of a document part. * - * @param part The MIME document part. - * @param field Case-insensitive name of the header field. + * @part: The MIME document part. + * @field: Case-insensitive name of the header field. * - * @returns Value of the specified header field, or NULL if the + * Returns:s Value of the specified header field, or NULL if the * field doesn't exist. */ const char *purple_mime_part_get_field(PurpleMimePart *part, @@ -168,9 +168,9 @@ * Set or replace the value of a specific field in the header of a * document. * - * @param part The part of the MIME document. - * @param field Case-insensitive field name - * @param value Value to associate with the indicated header field, + * @part: The part of the MIME document. + * @field: Case-insensitive field name + * @value: Value to associate with the indicated header field, * of NULL to remove the field. */ void purple_mime_part_set_field(PurpleMimePart *part, @@ -180,9 +180,9 @@ /** * Get the (possibly encoded) data portion of a MIME document part. * - * @param part The MIME document part. + * @part: The MIME document part. * - * @returns NULL-terminated data found in the document part + * Returns:s NULL-terminated data found in the document part */ const char *purple_mime_part_get_data(PurpleMimePart *part); @@ -192,9 +192,9 @@ * specified encoding method is not supported, this function will * return NULL. * - * @param part The MIME documemt part. - * @param data Buffer for the data. - * @param len The length of the buffer. + * @part: The MIME documemt part. + * @data: Buffer for the data. + * @len: The length of the buffer. */ void purple_mime_part_get_data_decoded(PurpleMimePart *part, guchar **data, gsize *len); @@ -202,8 +202,8 @@ /** * Get the length of the data portion of a MIME document part. * - * @param part The MIME document part. - * @returns Length of the data in the document part. + * @part: The MIME document part. + * Returns:s Length of the data in the document part. */ gsize purple_mime_part_get_length(PurpleMimePart *part);
--- a/libpurple/nat-pmp.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/nat-pmp.h Wed Jan 29 05:28:33 2014 +0530 @@ -56,13 +56,13 @@ /** * Remove the NAT-PMP mapping for a specified type on a specified port * - * @param type The PurplePmpType - * @param privateport The private port on which we are listening locally - * @param publicport The public port on which we are expecting a response - * @param lifetime The lifetime of the mapping. It is recommended that this + * @type: The PurplePmpType + * @privateport: The private port on which we are listening locally + * @publicport: The public port on which we are expecting a response + * @lifetime: The lifetime of the mapping. It is recommended that this * be PURPLE_PMP_LIFETIME. * - * @returns TRUE if successful; FALSE if unsuccessful + * Returns:s TRUE if successful; FALSE if unsuccessful */ gboolean purple_pmp_create_map(PurplePmpType type, unsigned short privateport, unsigned short publicport, int lifetime); @@ -70,10 +70,10 @@ /** * Remove the NAT-PMP mapping for a specified type on a specified port * - * @param type The PurplePmpType - * @param privateport The private port on which the mapping was previously made + * @type: The PurplePmpType + * @privateport: The private port on which the mapping was previously made * - * @returns TRUE if successful; FALSE if unsuccessful + * Returns:s TRUE if successful; FALSE if unsuccessful */ gboolean purple_pmp_destroy_map(PurplePmpType type, unsigned short privateport);
--- a/libpurple/network.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/network.h Wed Jan 29 05:28:33 2014 +0530 @@ -45,7 +45,7 @@ * (file transfer, direct IM, etc.) and should therefore be * publicly accessible. * - * @param ip The local IP address. + * @ip: The local IP address. */ void purple_network_set_public_ip(const char *ip); @@ -55,7 +55,7 @@ * This returns the value set via purple_network_set_public_ip(). * You probably want to use purple_network_get_my_ip() instead. * - * @return The local IP address set in preferences. + * Returns: The local IP address set in preferences. */ const char *purple_network_get_public_ip(void); @@ -68,8 +68,8 @@ * function is called twice, it may be important to make a copy * of the returned string. * - * @param fd The fd to use to help figure out the IP, or else -1. - * @return The local IP address. + * @fd: The fd to use to help figure out the IP, or else -1. + * Returns: The local IP address. */ const char *purple_network_get_local_system_ip(int fd); @@ -79,7 +79,7 @@ * @note The caller must free this list. If libpurple was built with * support for it, this function also enumerates IPv6 addresses. * - * @return A list of local IP addresses. + * Returns: A list of local IP addresses. */ GList *purple_network_get_all_local_system_ips(void); @@ -97,8 +97,8 @@ * function is called twice, it may be important to make a copy * of the returned string. * - * @param fd The fd to use to help figure out the IP, or -1. - * @return The local IP address to be used. + * @fd: The fd to use to help figure out the IP, or -1. + * Returns: The local IP address to be used. */ const char *purple_network_get_my_ip(int fd); @@ -119,24 +119,24 @@ * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped * addresses, a mapping is done). * - * @param port The port number to bind to. Must be greater than 0. - * @param socket_family The protocol family of the socket. This should be + * @port: The port number to bind to. Must be greater than 0. + * @socket_family: The protocol family of the socket. This should be * AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets * may or may not be able to accept IPv4 connections * based on the system configuration (use * purple_socket_speaks_ipv4 to check). If an IPv6 * socket doesn't accept V4-mapped addresses, you will * need a second listener to support both v4 and v6. - * @param socket_type The type of socket to open for listening. + * @socket_type: The type of socket to open for listening. * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP. - * @param map_external Should the open port be mapped externally using + * @map_external: Should the open port be mapped externally using * NAT-PNP or UPnP? (default should be TRUE) - * @param cb The callback to be invoked when the port to listen on is available. + * @cb: The callback to be invoked when the port to listen on is available. * The file descriptor of the listening socket will be specified in * this callback, or -1 if no socket could be established. - * @param cb_data extra data to be returned when cb is called + * @cb_data: extra data to be returned when cb is called * - * @return A pointer to a data structure that can be used to cancel + * Returns: A pointer to a data structure that can be used to cancel * the pending listener, or NULL if unable to obtain a local * socket to listen on. */ @@ -162,28 +162,28 @@ * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped * addresses, a mapping is done). * - * @param start The port number to bind to, or 0 to pick a random port. + * @start: The port number to bind to, or 0 to pick a random port. * Users are allowed to override this arg in prefs. - * @param end The highest possible port in the range of ports to listen on, + * @end: The highest possible port in the range of ports to listen on, * or 0 to pick a random port. Users are allowed to override this * arg in prefs. - * @param socket_family The protocol family of the socket. This should be + * @socket_family: The protocol family of the socket. This should be * AF_INET for IPv4 or AF_INET6 for IPv6. IPv6 sockets * may or may not be able to accept IPv4 connections * based on the system configuration (use * purple_socket_speaks_ipv4 to check). If an IPv6 * socket doesn't accept V4-mapped addresses, you will * need a second listener to support both v4 and v6. - * @param socket_type The type of socket to open for listening. + * @socket_type: The type of socket to open for listening. * This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP. - * @param map_external Should the open port be mapped externally using + * @map_external: Should the open port be mapped externally using * NAT-PNP or UPnP? (default should be TRUE) - * @param cb The callback to be invoked when the port to listen on is available. + * @cb: The callback to be invoked when the port to listen on is available. * The file descriptor of the listening socket will be specified in * this callback, or -1 if no socket could be established. - * @param cb_data extra data to be returned when cb is called + * @cb_data: extra data to be returned when cb is called * - * @return A pointer to a data structure that can be used to cancel + * Returns: A pointer to a data structure that can be used to cancel * the pending listener, or NULL if unable to obtain a local * socket to listen on. */ @@ -197,7 +197,7 @@ * by passing in the return value from either purple_network_listen() * or purple_network_listen_range(). * - * @param listen_data This listener attempt will be cancelled and + * @listen_data: This listener attempt will be cancelled and * the struct will be freed. */ void purple_network_listen_cancel(PurpleNetworkListenData *listen_data); @@ -205,17 +205,17 @@ /** * Gets a port number from a file descriptor. * - * @param fd The file descriptor. This should be a tcp socket. The current + * @fd: The file descriptor. This should be a tcp socket. The current * implementation probably dies on anything but IPv4. Perhaps this * possible bug will inspire new and valuable contributors to Purple. - * @return The port number, in host byte order. + * Returns: The port number, in host byte order. */ unsigned short purple_network_get_port_from_fd(int fd); /** * Detects if there is an available network connection. * - * @return TRUE if the network is available + * Returns: TRUE if the network is available */ gboolean purple_network_is_available(void); @@ -231,7 +231,7 @@ /** * Get the handle for the network system * - * @return the handle to the network system + * Returns: the handle to the network system */ void *purple_network_get_handle(void); @@ -239,14 +239,14 @@ * Update the STUN server IP given the host name * Will result in a DNS query being executed asynchronous * - * @param stun_server The host name of the STUN server to set + * @stun_server: The host name of the STUN server to set */ void purple_network_set_stun_server(const gchar *stun_server); /** * Get the IP address of the STUN server as a string representation * - * @return the IP address + * Returns: the IP address */ const gchar *purple_network_get_stun_ip(void); @@ -254,21 +254,21 @@ * Update the TURN server IP given the host name * Will result in a DNS query being executed asynchronous * - * @param turn_server The host name of the TURN server to set + * @turn_server: The host name of the TURN server to set */ void purple_network_set_turn_server(const gchar *turn_server); /** * Get the IP address of the TURN server as a string representation * - * @return the IP address + * Returns: the IP address */ const gchar *purple_network_get_turn_ip(void); /** * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket * - * @param fd Socket to remove the port mapping for + * @fd: Socket to remove the port mapping for */ void purple_network_remove_port_mapping(gint fd); @@ -282,10 +282,10 @@ * * In general, a buffer of about 512 bytes is the appropriate size to use. * - * @param in The hostname to be converted. - * @param out The output buffer where an allocated string will be returned. + * @in: The hostname to be converted. + * @out: The output buffer where an allocated string will be returned. * The caller is responsible for freeing this. - * @returns 0 on success, -1 if the out is NULL, or an error code + * Returns:s 0 on success, -1 if the out is NULL, or an error code * that currently corresponds to the Idna_rc enum in libidn. */ int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out);
--- a/libpurple/notify.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/notify.h Wed Jan 29 05:28:33 2014 +0530 @@ -119,8 +119,8 @@ * Callback for a button in a search result. * * @param c the PurpleConnection passed to purple_notify_searchresults - * @param row the contents of the selected row - * @param user_data User defined data. + * @row: the contents of the selected row + * @user_data: User defined data. */ typedef void (*PurpleNotifySearchResultsCallback)(PurpleConnection *c, GList *row, gpointer user_data); @@ -194,18 +194,18 @@ * a window with a list of all found buddies, where you are given the * option of adding buddies to your buddy list. * - * @param gc The PurpleConnection handle associated with the information. - * @param title The title of the message. If this is NULL, the title + * @gc: The PurpleConnection handle associated with the information. + * @title: The title of the message. If this is NULL, the title * will be "Search Results." - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param results The PurpleNotifySearchResults instance. - * @param cb The callback to call when the user closes + * @primary: The main point of the message. + * @secondary: The secondary information. + * @results: The PurpleNotifySearchResults instance. + * @cb: The callback to call when the user closes * the notification. - * @param user_data The data to pass to the close callback and any other + * @user_data: The data to pass to the close callback and any other * callback associated with a button. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_notify_searchresults(PurpleConnection *gc, const char *title, const char *primary, const char *secondary, @@ -215,16 +215,16 @@ /** * Frees a PurpleNotifySearchResults object. * - * @param results The PurpleNotifySearchResults to free. + * @results: The PurpleNotifySearchResults to free. */ void purple_notify_searchresults_free(PurpleNotifySearchResults *results); /** * Replace old rows with the new. Reuse an existing window. * - * @param gc The PurpleConnection structure. - * @param results The PurpleNotifySearchResults structure. - * @param data Data returned by the purple_notify_searchresults(). + * @gc: The PurpleConnection structure. + * @results: The PurpleNotifySearchResults structure. + * @data: Data returned by the purple_notify_searchresults(). */ void purple_notify_searchresults_new_rows(PurpleConnection *gc, PurpleNotifySearchResults *results, @@ -234,10 +234,10 @@ /** * Adds a stock button that will be displayed in the search results dialog. * - * @param results The search results object. - * @param type Type of the button. (TODO: Only one button of a given type + * @results: The search results object. + * @type: Type of the button. (TODO: Only one button of a given type * can be displayed.) - * @param cb Function that will be called on the click event. + * @cb: Function that will be called on the click event. */ void purple_notify_searchresults_button_add(PurpleNotifySearchResults *results, PurpleNotifySearchButtonType type, @@ -248,9 +248,9 @@ * Adds a plain labelled button that will be displayed in the search results * dialog. * - * @param results The search results object - * @param label The label to display - * @param cb Function that will be called on the click event + * @results: The search results object + * @label: The label to display + * @cb: Function that will be called on the click event */ void purple_notify_searchresults_button_add_labeled(PurpleNotifySearchResults *results, const char *label, @@ -260,7 +260,7 @@ /** * Returns a newly created search results object. * - * @return The new search results object. + * Returns: The new search results object. */ PurpleNotifySearchResults *purple_notify_searchresults_new(void); @@ -268,43 +268,43 @@ * Returns a newly created search result column object. The column defaults * to being visible. * - * @param title Title of the column. NOTE: Title will get g_strdup()ed. + * @title: Title of the column. NOTE: Title will get g_strdup()ed. * - * @return The new search column object. + * Returns: The new search column object. */ PurpleNotifySearchColumn *purple_notify_searchresults_column_new(const char *title); /** * Returns the title of the column * - * @param column The search column object. + * @column: The search column object. * - * @return The title of the column + * Returns: The title of the column */ const char *purple_notify_searchresult_column_get_title(const PurpleNotifySearchColumn *column); /** * Sets whether or not a search result column is visible. * - * @param column The search column object. - * @param visible TRUE if visible, or FALSE if not. + * @column: The search column object. + * @visible: TRUE if visible, or FALSE if not. */ void purple_notify_searchresult_column_set_visible(PurpleNotifySearchColumn *column, gboolean visible); /** * Returns whether or not a search result column is visible. * - * @param column The search column object. + * @column: The search column object. * - * @return TRUE if the search result column is visible. FALSE otherwise. + * Returns: TRUE if the search result column is visible. FALSE otherwise. */ gboolean purple_notify_searchresult_column_is_visible(const PurpleNotifySearchColumn *column); /** * Adds a new column to the search result object. * - * @param results The result object to which the column will be added. - * @param column The column that will be added to the result object. + * @results: The result object to which the column will be added. + * @column: The column that will be added to the result object. */ void purple_notify_searchresults_column_add(PurpleNotifySearchResults *results, PurpleNotifySearchColumn *column); @@ -312,8 +312,8 @@ /** * Adds a new row of the results to the search results object. * - * @param results The search results object. - * @param row The row of the results. + * @results: The search results object. + * @row: The row of the results. */ void purple_notify_searchresults_row_add(PurpleNotifySearchResults *results, GList *row); @@ -328,18 +328,18 @@ /** * Displays a notification message to the user. * - * @param handle The plugin or connection handle. - * @param type The notification type. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param cpar The #PurpleRequestCommonParameters associated with this + * @handle: The plugin or connection handle. + * @type: The notification type. + * @title: The title of the message. + * @primary: The main point of the message. + * @secondary: The secondary information. + * @cpar: The #PurpleRequestCommonParameters associated with this * request, or @c NULL if none is. - * @param cb The callback to call when the user closes + * @cb: The callback to call when the user closes * the notification. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_notify_message(void *handle, PurpleNotifyMsgType type, const char *title, const char *primary, const char *secondary, @@ -349,16 +349,16 @@ /** * Displays a single email notification to the user. * - * @param handle The plugin or connection handle. - * @param subject The subject of the email. - * @param from The from address. - * @param to The destination address. - * @param url The URL where the message can be read. - * @param cb The callback to call when the user closes + * @handle: The plugin or connection handle. + * @subject: The subject of the email. + * @from: The from address. + * @to: The destination address. + * @url: The URL where the message can be read. + * @cb: The callback to call when the user closes * the notification. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_notify_email(void *handle, const char *subject, const char *from, const char *to, @@ -368,21 +368,21 @@ /** * Displays a notification for multiple emails to the user. * - * @param handle The plugin or connection handle. - * @param count The number of emails. '0' can be used to signify that + * @handle: The plugin or connection handle. + * @count: The number of emails. '0' can be used to signify that * the user has no unread emails and the UI should remove * the mail notification. - * @param detailed @c TRUE if there is information for each email in the + * @detailed: @c TRUE if there is information for each email in the * arrays. - * @param subjects The array of subjects. - * @param froms The array of from addresses. - * @param tos The array of destination addresses. - * @param urls The URLs where the messages can be read. - * @param cb The callback to call when the user closes + * @subjects: The array of subjects. + * @froms: The array of from addresses. + * @tos: The array of destination addresses. + * @urls: The URLs where the messages can be read. + * @cb: The callback to call when the user closes * the notification. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_notify_emails(void *handle, size_t count, gboolean detailed, const char **subjects, const char **froms, @@ -395,16 +395,16 @@ * The text is essentially a stripped-down format of HTML, the same that * IMs may send. * - * @param handle The plugin or connection handle. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param text The formatted text. - * @param cb The callback to call when the user closes + * @handle: The plugin or connection handle. + * @title: The title of the message. + * @primary: The main point of the message. + * @secondary: The secondary information. + * @text: The formatted text. + * @cb: The callback to call when the user closes * the notification. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_notify_formatted(void *handle, const char *title, const char *primary, const char *secondary, @@ -417,13 +417,13 @@ * The text is essentially a stripped-down format of HTML, the same that * IMs may send. * - * @param gc The PurpleConnection handle associated with the information. - * @param who The username associated with the information. - * @param user_info The PurpleNotifyUserInfo which contains the information - * @param cb The callback to call when the user closes the notification. - * @param user_data The data to pass to the callback. + * @gc: The PurpleConnection handle associated with the information. + * @who: The username associated with the information. + * @user_info: The PurpleNotifyUserInfo which contains the information + * @cb: The callback to call when the user closes the notification. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_notify_userinfo(PurpleConnection *gc, const char *who, PurpleNotifyUserInfo *user_info, PurpleNotifyCloseCallback cb, @@ -438,14 +438,14 @@ * Create a new PurpleNotifyUserInfo which is suitable for passing to * purple_notify_userinfo() * - * @return A new PurpleNotifyUserInfo, which the caller must destroy when done + * Returns: A new PurpleNotifyUserInfo, which the caller must destroy when done */ PurpleNotifyUserInfo *purple_notify_user_info_new(void); /** * Destroy a PurpleNotifyUserInfo * - * @param user_info The PurpleNotifyUserInfo + * @user_info: The PurpleNotifyUserInfo */ void purple_notify_user_info_destroy(PurpleNotifyUserInfo *user_info); @@ -462,9 +462,9 @@ * To remove a PurpleNotifyUserInfoEntry, use * purple_notify_user_info_remove_entry(). Do not use the GQueue directly. * - * @param user_info The PurpleNotifyUserInfo + * @user_info: The PurpleNotifyUserInfo * - * @constreturn A GQueue of PurpleNotifyUserInfoEntry objects. + * Returns: (TODO const): A GQueue of PurpleNotifyUserInfoEntry objects. */ GQueue *purple_notify_user_info_get_entries(PurpleNotifyUserInfo *user_info); @@ -472,8 +472,8 @@ * Create a textual representation of a PurpleNotifyUserInfo, separating * entries with newline * - * @param user_info The PurpleNotifyUserInfo - * @param newline The separation character + * @user_info: The PurpleNotifyUserInfo + * @newline: The separation character */ char *purple_notify_user_info_get_text_with_newline(PurpleNotifyUserInfo *user_info, const char *newline); @@ -481,12 +481,12 @@ * Add a label/value pair to a PurpleNotifyUserInfo object. * PurpleNotifyUserInfo keeps track of the order in which pairs are added. * - * @param user_info The PurpleNotifyUserInfo - * @param label A label, which for example might be displayed by a + * @user_info: The PurpleNotifyUserInfo + * @label: A label, which for example might be displayed by a * UI with a colon after it ("Status:"). Do not include * a colon. If NULL, value will be displayed without a * label. - * @param value The value, which might be displayed by a UI after + * @value: The value, which might be displayed by a UI after * the label. This should be valid HTML. If you want * to insert plaintext then use * purple_notify_user_info_add_pair_plaintext(), instead. @@ -518,8 +518,8 @@ * Remove a PurpleNotifyUserInfoEntry from a PurpleNotifyUserInfo object * without freeing the entry. * - * @param user_info The PurpleNotifyUserInfo - * @param user_info_entry The PurpleNotifyUserInfoEntry + * @user_info: The PurpleNotifyUserInfo + * @user_info_entry: The PurpleNotifyUserInfoEntry */ void purple_notify_user_info_remove_entry(PurpleNotifyUserInfo *user_info, PurpleNotifyUserInfoEntry *user_info_entry); @@ -534,10 +534,10 @@ * purple_notify_user_info_prepend_pair_plaintext() are convenience * methods for creating entries and adding them to a PurpleNotifyUserInfo. * - * @param label A label, which for example might be displayed by a UI + * @label: A label, which for example might be displayed by a UI * with a colon after it ("Status:"). Do not include a * colon. If NULL, value will be displayed without a label. - * @param value The value, which might be displayed by a UI after the + * @value: The value, which might be displayed by a UI after the * label. If NULL, label will still be displayed; the UI * should then treat label as independent and not include a * colon if it would otherwise. @@ -549,21 +549,21 @@ /** * Destroy a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry + * @user_info_entry: The PurpleNotifyUserInfoEntry */ void purple_notify_user_info_entry_destroy(PurpleNotifyUserInfoEntry *user_info_entry); /** * Add a section break. A UI might display this as a horizontal line. * - * @param user_info The PurpleNotifyUserInfo + * @user_info: The PurpleNotifyUserInfo */ void purple_notify_user_info_add_section_break(PurpleNotifyUserInfo *user_info); /** * Prepend a section break. A UI might display this as a horizontal line. * - * @param user_info The PurpleNotifyUserInfo + * @user_info: The PurpleNotifyUserInfo */ void purple_notify_user_info_prepend_section_break(PurpleNotifyUserInfo *user_info); @@ -571,8 +571,8 @@ * Add a section header. A UI might display this in a different font * from other text. * - * @param user_info The PurpleNotifyUserInfo - * @param label The name of the section + * @user_info: The PurpleNotifyUserInfo + * @label: The name of the section */ void purple_notify_user_info_add_section_header(PurpleNotifyUserInfo *user_info, const char *label); @@ -580,8 +580,8 @@ * Prepend a section header. A UI might display this in a different font * from other text. * - * @param user_info The PurpleNotifyUserInfo - * @param label The name of the section + * @user_info: The PurpleNotifyUserInfo + * @label: The name of the section */ void purple_notify_user_info_prepend_section_header(PurpleNotifyUserInfo *user_info, const char *label); @@ -594,24 +594,24 @@ /** * Get the label for a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry + * @user_info_entry: The PurpleNotifyUserInfoEntry * - * @return The label + * Returns: The label */ const gchar *purple_notify_user_info_entry_get_label(PurpleNotifyUserInfoEntry *user_info_entry); /** * Set the label for a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry - * @param label The label + * @user_info_entry: The PurpleNotifyUserInfoEntry + * @label: The label */ void purple_notify_user_info_entry_set_label(PurpleNotifyUserInfoEntry *user_info_entry, const char *label); /** * Get the value for a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry + * @user_info_entry: The PurpleNotifyUserInfoEntry * * @result The value */ @@ -620,8 +620,8 @@ /** * Set the value for a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry - * @param value The value + * @user_info_entry: The PurpleNotifyUserInfoEntry + * @value: The value */ void purple_notify_user_info_entry_set_value(PurpleNotifyUserInfoEntry *user_info_entry, const char *value); @@ -629,17 +629,17 @@ /** * Get the type of a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry + * @user_info_entry: The PurpleNotifyUserInfoEntry * - * @return The PurpleNotifyUserInfoEntryType + * Returns: The PurpleNotifyUserInfoEntryType */ PurpleNotifyUserInfoEntryType purple_notify_user_info_entry_get_type(PurpleNotifyUserInfoEntry *user_info_entry); /** * Set the type of a PurpleNotifyUserInfoEntry * - * @param user_info_entry The PurpleNotifyUserInfoEntry - * @param type The PurpleNotifyUserInfoEntryType + * @user_info_entry: The PurpleNotifyUserInfoEntry + * @type: The PurpleNotifyUserInfoEntryType */ void purple_notify_user_info_entry_set_type(PurpleNotifyUserInfoEntry *user_info_entry, PurpleNotifyUserInfoEntryType type); @@ -647,10 +647,10 @@ /** * Opens a URI or somehow presents it to the user. * - * @param handle The plugin or connection handle. - * @param uri The URI to display or go to. + * @handle: The plugin or connection handle. + * @uri: The URI to display or go to. * - * @return A UI-specific handle, if any. This may only be presented if + * Returns: A UI-specific handle, if any. This may only be presented if * the UI code displays a dialog instead of a webpage, or something * similar. */ @@ -659,11 +659,11 @@ /** * Checks, if passed UI handle is valid. * - * @param ui_handle The UI handle. - * @param type The pointer to variable, where request type may be stored + * @ui_handle: The UI handle. + * @type: The pointer to variable, where request type may be stored * (may be @c NULL). * - * @return TRUE, if handle is valid, FALSE otherwise. + * Returns: TRUE, if handle is valid, FALSE otherwise. */ gboolean purple_notify_is_valid_ui_handle(void *ui_handle, PurpleNotifyType *type); @@ -674,15 +674,15 @@ * This should be used only by the UI operation functions and part of the * core. * - * @param type The notification type. - * @param ui_handle The notification UI handle. + * @type: The notification type. + * @ui_handle: The notification UI handle. */ void purple_notify_close(PurpleNotifyType type, void *ui_handle); /** * Closes all notifications registered with the specified handle. * - * @param handle The handle. + * @handle: The handle. */ void purple_notify_close_with_handle(void *handle); @@ -718,7 +718,7 @@ * Sets the UI operations structure to be used when displaying a * notification. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_notify_set_ui_ops(PurpleNotifyUiOps *ops); @@ -726,7 +726,7 @@ * Returns the UI operations structure to be used when displaying a * notification. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleNotifyUiOps *purple_notify_get_ui_ops(void); @@ -740,7 +740,7 @@ /** * Returns the notify subsystem handle. * - * @return The notify subsystem handle. + * Returns: The notify subsystem handle. */ void *purple_notify_get_handle(void);
--- a/libpurple/ntlm.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/ntlm.h Wed Jan 29 05:28:33 2014 +0530 @@ -32,9 +32,9 @@ /** * Generates the base64 encoded type 1 message needed for NTLM authentication * - * @param hostname Your hostname - * @param domain The domain to authenticate to - * @return base64 encoded string to send to the server. This should + * @hostname: Your hostname + * @domain: The domain to authenticate to + * Returns: base64 encoded string to send to the server. This should * be g_free'd by the caller. */ gchar *purple_ntlm_gen_type1(const gchar *hostname, const gchar *domain); @@ -42,10 +42,10 @@ /** * Parses the ntlm type 2 message * - * @param type2 String containing the base64 encoded type2 message - * @param flags If not @c NULL, this will store the flags for the message + * @type2: String containing the base64 encoded type2 message + * @flags: If not @c NULL, this will store the flags for the message * - * @return The nonce for use in message type3. This is a statically + * Returns: The nonce for use in message type3. This is a statically * allocated 8 byte binary string. */ guint8 *purple_ntlm_parse_type2(const gchar *type2, guint32 *flags); @@ -53,13 +53,13 @@ /** * Generates a type3 message * - * @param username The username - * @param passw The password - * @param hostname The hostname - * @param domain The domain to authenticate against - * @param nonce The nonce returned by purple_ntlm_parse_type2 - * @param flags Pointer to the flags returned by purple_ntlm_parse_type2 - * @return A base64 encoded type3 message. This should be g_free'd by + * @username: The username + * @passw: The password + * @hostname: The hostname + * @domain: The domain to authenticate against + * @nonce: The nonce returned by purple_ntlm_parse_type2 + * @flags: Pointer to the flags returned by purple_ntlm_parse_type2 + * Returns: A base64 encoded type3 message. This should be g_free'd by * the caller. */ gchar *purple_ntlm_gen_type3(const gchar *username, const gchar *passw, const gchar *hostname, const gchar *domain, const guint8 *nonce, guint32 *flags);
--- a/libpurple/pluginpref.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/pluginpref.h Wed Jan 29 05:28:33 2014 +0530 @@ -60,184 +60,184 @@ /** * Create a new plugin preference frame * - * @return a new PurplePluginPrefFrame + * Returns: a new PurplePluginPrefFrame */ PurplePluginPrefFrame *purple_plugin_pref_frame_new(void); /** * Destroy a plugin preference frame * - * @param frame The plugin frame to destroy + * @frame: The plugin frame to destroy */ void purple_plugin_pref_frame_destroy(PurplePluginPrefFrame *frame); /** * Adds a plugin preference to a plugin preference frame * - * @param frame The plugin frame to add the preference to - * @param pref The preference to add to the frame + * @frame: The plugin frame to add the preference to + * @pref: The preference to add to the frame */ void purple_plugin_pref_frame_add(PurplePluginPrefFrame *frame, PurplePluginPref *pref); /** * Get the plugin preferences from a plugin preference frame * - * @param frame The plugin frame to get the plugin preferences from - * @constreturn a GList of plugin preferences + * @frame: The plugin frame to get the plugin preferences from + * Returns: (TODO const): a GList of plugin preferences */ GList *purple_plugin_pref_frame_get_prefs(PurplePluginPrefFrame *frame); /** * Create a new plugin preference * - * @return a new PurplePluginPref + * Returns: a new PurplePluginPref */ PurplePluginPref *purple_plugin_pref_new(void); /** * Create a new plugin preference with name * - * @param name The name of the pref - * @return a new PurplePluginPref + * @name: The name of the pref + * Returns: a new PurplePluginPref */ PurplePluginPref *purple_plugin_pref_new_with_name(const char *name); /** * Create a new plugin preference with label * - * @param label The label to be displayed - * @return a new PurplePluginPref + * @label: The label to be displayed + * Returns: a new PurplePluginPref */ PurplePluginPref *purple_plugin_pref_new_with_label(const char *label); /** * Create a new plugin preference with name and label * - * @param name The name of the pref - * @param label The label to be displayed - * @return a new PurplePluginPref + * @name: The name of the pref + * @label: The label to be displayed + * Returns: a new PurplePluginPref */ PurplePluginPref *purple_plugin_pref_new_with_name_and_label(const char *name, const char *label); /** * Destroy a plugin preference * - * @param pref The preference to destroy + * @pref: The preference to destroy */ void purple_plugin_pref_destroy(PurplePluginPref *pref); /** * Set a plugin pref name * - * @param pref The plugin pref - * @param name The name of the pref + * @pref: The plugin pref + * @name: The name of the pref */ void purple_plugin_pref_set_name(PurplePluginPref *pref, const char *name); /** * Get a plugin pref name * - * @param pref The plugin pref - * @return The name of the pref + * @pref: The plugin pref + * Returns: The name of the pref */ const char *purple_plugin_pref_get_name(PurplePluginPref *pref); /** * Set a plugin pref label * - * @param pref The plugin pref - * @param label The label for the plugin pref + * @pref: The plugin pref + * @label: The label for the plugin pref */ void purple_plugin_pref_set_label(PurplePluginPref *pref, const char *label); /** * Get a plugin pref label * - * @param pref The plugin pref - * @return The label for the plugin pref + * @pref: The plugin pref + * Returns: The label for the plugin pref */ const char *purple_plugin_pref_get_label(PurplePluginPref *pref); /** * Set the bounds for an integer pref * - * @param pref The plugin pref - * @param min The min value - * @param max The max value + * @pref: The plugin pref + * @min: The min value + * @max: The max value */ void purple_plugin_pref_set_bounds(PurplePluginPref *pref, int min, int max); /** * Get the bounds for an integer pref * - * @param pref The plugin pref - * @param min The min value - * @param max The max value + * @pref: The plugin pref + * @min: The min value + * @max: The max value */ void purple_plugin_pref_get_bounds(PurplePluginPref *pref, int *min, int *max); /** * Set the type of a plugin pref * - * @param pref The plugin pref - * @param type The type + * @pref: The plugin pref + * @type: The type */ void purple_plugin_pref_set_type(PurplePluginPref *pref, PurplePluginPrefType type); /** * Get the type of a plugin pref * - * @param pref The plugin pref - * @return The type + * @pref: The plugin pref + * Returns: The type */ PurplePluginPrefType purple_plugin_pref_get_type(PurplePluginPref *pref); /** * Set the choices for a choices plugin pref * - * @param pref The plugin pref - * @param label The label for the choice - * @param choice A gpointer of the choice + * @pref: The plugin pref + * @label: The label for the choice + * @choice: A gpointer of the choice */ void purple_plugin_pref_add_choice(PurplePluginPref *pref, const char *label, gpointer choice); /** * Get the choices for a choices plugin pref * - * @param pref The plugin pref - * @constreturn GList of the choices + * @pref: The plugin pref + * Returns: (TODO const): GList of the choices */ GList *purple_plugin_pref_get_choices(PurplePluginPref *pref); /** * Set the max length for a string plugin pref * - * @param pref The plugin pref - * @param max_length The max length of the string + * @pref: The plugin pref + * @max_length: The max length of the string */ void purple_plugin_pref_set_max_length(PurplePluginPref *pref, unsigned int max_length); /** * Get the max length for a string plugin pref * - * @param pref The plugin pref - * @return the max length + * @pref: The plugin pref + * Returns: the max length */ unsigned int purple_plugin_pref_get_max_length(PurplePluginPref *pref); /** * Sets the masking of a string plugin pref * - * @param pref The plugin pref - * @param mask The value to set + * @pref: The plugin pref + * @mask: The value to set */ void purple_plugin_pref_set_masked(PurplePluginPref *pref, gboolean mask); /** * Gets the masking of a string plugin pref * - * @param pref The plugin pref - * @return The masking + * @pref: The plugin pref + * Returns: The masking */ gboolean purple_plugin_pref_get_masked(PurplePluginPref *pref); @@ -245,16 +245,16 @@ * Sets the format type for a formattable-string plugin pref. You need to set the * pref type to PURPLE_PLUGIN_PREF_STRING_FORMAT first before setting the format. * - * @param pref The plugin pref - * @param format The format of the string + * @pref: The plugin pref + * @format: The format of the string */ void purple_plugin_pref_set_format_type(PurplePluginPref *pref, PurpleStringFormatType format); /** * Gets the format type of the formattable-string plugin pref. * - * @param pref The plugin pref - * @return The format of the pref + * @pref: The plugin pref + * Returns: The format of the pref */ PurpleStringFormatType purple_plugin_pref_get_format_type(PurplePluginPref *pref);
--- a/libpurple/plugins.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/plugins.h Wed Jan 29 05:28:33 2014 +0530 @@ -231,9 +231,9 @@ * The type will be registered statically if used in a static protocol or if * plugins support is disabled. * - * @param TN The name of the new type, in Camel case. - * @param t_n The name of the new type, in lowercase, words separated by '_'. - * @param T_P The #GType of the parent type. + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, words separated by '_'. + * @T_P: The #GType of the parent type. */ #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL) #define PURPLE_DEFINE_TYPE(TN, t_n, T_P) \ @@ -249,11 +249,11 @@ * A more general version of PURPLE_DEFINE_TYPE() which allows you to * specify #GTypeFlags and custom code. * - * @param TN The name of the new type, in Camel case. - * @param t_n The name of the new type, in lowercase, words separated by '_'. - * @param T_P The #GType of the parent type. - * @param flags #GTypeFlags to register the type with. - * @param CODE Custom code that gets inserted in *_get_type(). + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, words separated by '_'. + * @T_P: The #GType of the parent type. + * @flags: #GTypeFlags to register the type with. + * @CODE: Custom code that gets inserted in *_get_type(). */ #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL) #define PURPLE_DEFINE_TYPE_EXTENDED \ @@ -270,8 +270,8 @@ * of PURPLE_DEFINE_TYPE_EXTENDED(). You should use this macro if the * interface is a part of the libpurple core. * - * @param TYPE_IFACE The #GType of the interface to add. - * @param iface_init The interface init function. + * @TYPE_IFACE: The #GType of the interface to add. + * @iface_init: The interface init function. */ #define PURPLE_IMPLEMENT_INTERFACE_STATIC(TYPE_IFACE, iface_init) { \ const GInterfaceInfo interface_info = { \ @@ -287,8 +287,8 @@ * of PURPLE_DEFINE_TYPE_EXTENDED(). You should use this macro if the * interface lives in the plugin. * - * @param TYPE_IFACE The #GType of the interface to add. - * @param iface_init The interface init function. + * @TYPE_IFACE: The #GType of the interface to add. + * @iface_init: The interface init function. */ #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL) #define PURPLE_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) \ @@ -379,11 +379,11 @@ /** * Attempts to load a plugin. * - * @param plugin The plugin to load. - * @param error Return location for a #GError or @c NULL. If provided, this + * @plugin: The plugin to load. + * @error: Return location for a #GError or @c NULL. If provided, this * will be set to the reason if the load fails. * - * @return @c TRUE if successful or already loaded, @c FALSE otherwise. + * Returns: @c TRUE if successful or already loaded, @c FALSE otherwise. * * @see purple_plugin_unload() */ @@ -392,11 +392,11 @@ /** * Unloads the specified plugin. * - * @param plugin The plugin handle. - * @param error Return location for a #GError or @c NULL. If provided, this + * @plugin: The plugin handle. + * @error: Return location for a #GError or @c NULL. If provided, this * will be set to the reason if the unload fails. * - * @return @c TRUE if successful or not loaded, @c FALSE otherwise. + * Returns: @c TRUE if successful or not loaded, @c FALSE otherwise. * * @see purple_plugin_load() */ @@ -405,27 +405,27 @@ /** * Returns whether or not a plugin is currently loaded. * - * @param plugin The plugin. + * @plugin: The plugin. * - * @return @c TRUE if loaded, or @c FALSE otherwise. + * Returns: @c TRUE if loaded, or @c FALSE otherwise. */ gboolean purple_plugin_is_loaded(const PurplePlugin *plugin); /** * Returns a plugin's filename, along with the path. * - * @param info The plugin. + * @info: The plugin. * - * @return The plugin's filename. + * Returns: The plugin's filename. */ const gchar *purple_plugin_get_filename(const PurplePlugin *plugin); /** * Returns a plugin's #PurplePluginInfo instance. * - * @param info The plugin. + * @info: The plugin. * - * @return The plugin's #PurplePluginInfo instance. + * Returns: The plugin's #PurplePluginInfo instance. */ PurplePluginInfo *purple_plugin_get_info(const PurplePlugin *plugin); @@ -442,15 +442,15 @@ /** * Registers a new dynamic type. * - * @param plugin The plugin that is registering the type. - * @param parent Type from which this type will be derived. - * @param name Name of the new type. - * @param info Information to initialize and destroy a type's classes and + * @plugin: The plugin that is registering the type. + * @parent: Type from which this type will be derived. + * @name: Name of the new type. + * @info: Information to initialize and destroy a type's classes and * instances. - * @param flags Bitwise combination of values that determines the nature + * @flags: Bitwise combination of values that determines the nature * (e.g. abstract or not) of the type. * - * @return The new GType, or @c G_TYPE_INVALID if registration failed. + * Returns: The new GType, or @c G_TYPE_INVALID if registration failed. */ GType purple_plugin_register_type(PurplePlugin *plugin, GType parent, const gchar *name, const GTypeInfo *info, @@ -459,10 +459,10 @@ /** * Adds a dynamic interface type to an instantiable type. * - * @param plugin The plugin that is adding the interface type. - * @param instance_type The GType of the instantiable type. - * @param interface_type The GType of the interface type. - * @param interface_info Information used to manage the interface type. + * @plugin: The plugin that is adding the interface type. + * @instance_type: The GType of the instantiable type. + * @interface_type: The GType of the interface type. + * @interface_info: Information used to manage the interface type. */ void purple_plugin_add_interface(PurplePlugin *plugin, GType instance_type, GType interface_type, @@ -474,18 +474,18 @@ * not be shown in plugin lists. Examples of such plugins are in-tree protocol * plugins, loaders etc. * - * @param plugin The plugin. + * @plugin: The plugin. * - * @return @c TRUE if the plugin is an internal plugin, @c FALSE otherwise. + * Returns: @c TRUE if the plugin is an internal plugin, @c FALSE otherwise. */ gboolean purple_plugin_is_internal(const PurplePlugin *plugin); /** * Returns a list of plugins that depend on a particular plugin. * - * @param plugin The plugin whose dependent plugins are returned. + * @plugin: The plugin whose dependent plugins are returned. * - * @constreturn The list of a plugins that depend on the specified plugin. + * Returns: (TODO const): The list of a plugins that depend on the specified plugin. */ GSList *purple_plugin_get_dependent_plugins(const PurplePlugin *plugin); @@ -539,11 +539,11 @@ * preferences request handle for the plugin. \n * "flags" (PurplePluginInfoFlags) The flags for a plugin. \n * - * @param first_property The first property name - * @param ... The value of the first property, followed optionally by more + * @first_property: The first property name + * @...: The value of the first property, followed optionally by more * name/value pairs, followed by @c NULL * - * @return A new #PurplePluginInfo instance. + * Returns: A new #PurplePluginInfo instance. * * @see PURPLE_PLUGIN_ABI_VERSION * @see @ref plugin-ids @@ -554,63 +554,63 @@ /** * Returns a plugin's ID. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The plugin's ID. + * Returns: The plugin's ID. */ const gchar *purple_plugin_info_get_id(const PurplePluginInfo *info); /** * Returns a plugin's translated name. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The name of the plugin, or @c NULL. + * Returns: The name of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_name(const PurplePluginInfo *info); /** * Returns a plugin's version. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The version of the plugin, or @c NULL. + * Returns: The version of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_version(const PurplePluginInfo *info); /** * Returns a plugin's primary category. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The primary category of the plugin, or @c NULL. + * Returns: The primary category of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_category(const PurplePluginInfo *info); /** * Returns a plugin's summary. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The summary of the plugin, or @c NULL. + * Returns: The summary of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_summary(const PurplePluginInfo *info); /** * Returns a plugin's description. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The description of the plugin, or @c NULL. + * Returns: The description of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_description(const PurplePluginInfo *info); /** * Returns a NULL-terminated list of the plugin's authors. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The authors of the plugin, or @c NULL. + * Returns: The authors of the plugin, or @c NULL. */ const gchar * const * purple_plugin_info_get_authors(const PurplePluginInfo *info); @@ -618,54 +618,54 @@ /** * Returns a plugin's website. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The website of the plugin, or @c NULL. + * Returns: The website of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_website(const PurplePluginInfo *info); /** * Returns the path to a plugin's icon. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The path to the plugin's icon, or @c NULL. + * Returns: The path to the plugin's icon, or @c NULL. */ const gchar *purple_plugin_info_get_icon(const PurplePluginInfo *info); /** * Returns a short name of the plugin's license. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The license name of the plugin, or @c NULL. + * Returns: The license name of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_license_id(const PurplePluginInfo *info); /** * Returns the text of a plugin's license. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The license text of the plugin, or @c NULL. + * Returns: The license text of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_license_text(const PurplePluginInfo *info); /** * Returns the URL of a plugin's license. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The license URL of the plugin, or @c NULL. + * Returns: The license URL of the plugin, or @c NULL. */ const gchar *purple_plugin_info_get_license_url(const PurplePluginInfo *info); /** * Returns a NULL-terminated list of IDs of plugins required by a plugin. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The dependencies of the plugin, or @c NULL. + * Returns: The dependencies of the plugin, or @c NULL. */ const gchar * const * purple_plugin_info_get_dependencies(const PurplePluginInfo *info); @@ -673,9 +673,9 @@ /** * Returns the required purple ABI version for a plugin. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The required purple ABI version for the plugin. + * Returns: The required purple ABI version for the plugin. */ guint32 purple_plugin_info_get_abi_version(const PurplePluginInfo *info); @@ -683,9 +683,9 @@ * Returns the callback that retrieves the list of actions a plugin can perform * at that moment. * - * @param info The plugin info to get the callback from. + * @info: The plugin info to get the callback from. * - * @return The callback that returns a list of #PurplePluginAction + * Returns: The callback that returns a list of #PurplePluginAction * instances corresponding to the actions a plugin can perform. */ PurplePluginActionsCb @@ -695,9 +695,9 @@ * Returns a callback that gives extra information about a plugin. You must * free the string returned by this callback. * - * @param info The plugin info to get extra information from. + * @info: The plugin info to get extra information from. * - * @return The callback that returns extra information about a plugin. + * Returns: The callback that returns extra information about a plugin. */ PurplePluginExtraCb purple_plugin_info_get_extra_cb(const PurplePluginInfo *info); @@ -706,9 +706,9 @@ * Returns the callback that retrieves the preferences frame for a plugin, set * via the "pref-frame-cb" property of the plugin info. * - * @param info The plugin info to get the callback from. + * @info: The plugin info to get the callback from. * - * @return The callback that returns the preferences frame. + * Returns: The callback that returns the preferences frame. */ PurplePluginPrefFrameCb purple_plugin_info_get_pref_frame_cb(const PurplePluginInfo *info); @@ -717,9 +717,9 @@ * Returns the callback that retrieves the preferences request handle for a * plugin, set via the "pref-request-cb" property of the plugin info. * - * @param info The plugin info to get the callback from. + * @info: The plugin info to get the callback from. * - * @return The callback that returns the preferences request handle. + * Returns: The callback that returns the preferences request handle. */ PurplePluginPrefRequestCb purple_plugin_info_get_pref_request_cb(const PurplePluginInfo *info); @@ -727,9 +727,9 @@ /** * Returns the plugin's flags. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The flags of the plugin. + * Returns: The flags of the plugin. */ PurplePluginInfoFlags purple_plugin_info_get_flags(const PurplePluginInfo *info); @@ -738,26 +738,26 @@ * Returns an error in the plugin info that would prevent the plugin from being * loaded. * - * @param info The plugin info. + * @info: The plugin info. * - * @return The plugin info error, or @c NULL. + * Returns: The plugin info error, or @c NULL. */ const gchar *purple_plugin_info_get_error(const PurplePluginInfo *info); /** * Set the UI data associated with a plugin. * - * @param info The plugin's info instance. - * @param ui_data A pointer to associate with this object. + * @info: The plugin's info instance. + * @ui_data: A pointer to associate with this object. */ void purple_plugin_info_set_ui_data(PurplePluginInfo *info, gpointer ui_data); /** * Returns the UI data associated with a plugin. * - * @param info The plugin's info instance. + * @info: The plugin's info instance. * - * @return The UI data associated with this plugin. This is a + * Returns: The UI data associated with this plugin. This is a * convenience field provided to the UIs--it is not * used by the libpurple core. */ @@ -779,8 +779,8 @@ * Allocates and returns a new PurplePluginAction. Use this to add actions in a * list in the "actions-cb" callback for your plugin. * - * @param label The description of the action to show to the user. - * @param callback The callback to call when the user selects this action. + * @label: The description of the action to show to the user. + * @callback: The callback to call when the user selects this action. */ PurplePluginAction *purple_plugin_action_new(const char* label, PurplePluginActionCb callback); @@ -788,7 +788,7 @@ /** * Frees a PurplePluginAction * - * @param action The PurplePluginAction to free. + * @action: The PurplePluginAction to free. */ void purple_plugin_action_free(PurplePluginAction *action); @@ -802,7 +802,7 @@ /** * Returns a list of all plugins, whether loaded or not. * - * @return A list of all plugins. The list is owned by the caller, and must be + * Returns: A list of all plugins. The list is owned by the caller, and must be * g_list_free()d to avoid leaking the nodes. */ GList *purple_plugins_find_all(void); @@ -810,14 +810,14 @@ /** * Returns a list of all loaded plugins. * - * @constreturn A list of all loaded plugins. + * Returns: (TODO const): A list of all loaded plugins. */ GList *purple_plugins_get_loaded(void); /** * Add a new directory to search for plugins * - * @param path The new search path. + * @path: The new search path. */ void purple_plugins_add_search_path(const gchar *path); @@ -832,18 +832,18 @@ /** * Finds a plugin with the specified plugin ID. * - * @param id The plugin ID. + * @id: The plugin ID. * - * @return The plugin if found, or @c NULL if not found. + * Returns: The plugin if found, or @c NULL if not found. */ PurplePlugin *purple_plugins_find_plugin(const gchar *id); /** * Finds a plugin with the specified filename (filename with a path). * - * @param filename The plugin filename. + * @filename: The plugin filename. * - * @return The plugin if found, or @c NULL if not found. + * Returns: The plugin if found, or @c NULL if not found. */ PurplePlugin *purple_plugins_find_by_filename(const char *filename); @@ -851,7 +851,7 @@ * Saves the list of loaded plugins to the specified preference key. * Plugins that are set to auto-load are not saved. * - * @param key The preference key to save the list of plugins to. + * @key: The preference key to save the list of plugins to. */ void purple_plugins_save_loaded(const char *key); @@ -859,7 +859,7 @@ * Attempts to load all the plugins in the specified preference key * that were loaded when purple last quit. * - * @param key The preference key containing the list of plugins. + * @key: The preference key containing the list of plugins. */ void purple_plugins_load_saved(const char *key); @@ -873,7 +873,7 @@ /** * Returns the plugin subsystem handle. * - * @return The plugin sybsystem handle. + * Returns: The plugin sybsystem handle. */ void *purple_plugins_get_handle(void);
--- a/libpurple/pounce.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/pounce.h Wed Jan 29 05:28:33 2014 +0530 @@ -69,13 +69,13 @@ /** * Creates a new buddy pounce. * - * @param ui_type The type of UI the pounce is for. - * @param pouncer The account that will pounce. - * @param pouncee The buddy to pounce on. - * @param event The event(s) to pounce on. - * @param option Pounce options. + * @ui_type: The type of UI the pounce is for. + * @pouncer: The account that will pounce. + * @pouncee: The buddy to pounce on. + * @event: The event(s) to pounce on. + * @option: Pounce options. * - * @return The new buddy pounce structure. + * Returns: The new buddy pounce structure. */ PurplePounce *purple_pounce_new(const char *ui_type, PurpleAccount *pouncer, const char *pouncee, PurplePounceEvent event, @@ -84,78 +84,78 @@ /** * Destroys a buddy pounce. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. */ void purple_pounce_destroy(PurplePounce *pounce); /** * Destroys all buddy pounces for the account * - * @param account The account to remove all pounces from. + * @account: The account to remove all pounces from. */ void purple_pounce_destroy_all_by_account(PurpleAccount *account); /** * Destroys all buddy pounces for a buddy * - * @param buddy The buddy whose pounces are to be removed + * @buddy: The buddy whose pounces are to be removed */ void purple_pounce_destroy_all_by_buddy(PurpleBuddy *buddy); /** * Sets the events a pounce should watch for. * - * @param pounce The buddy pounce. - * @param events The events to watch for. + * @pounce: The buddy pounce. + * @events: The events to watch for. */ void purple_pounce_set_events(PurplePounce *pounce, PurplePounceEvent events); /** * Sets the options for a pounce. * - * @param pounce The buddy pounce. - * @param options The options for the pounce. + * @pounce: The buddy pounce. + * @options: The options for the pounce. */ void purple_pounce_set_options(PurplePounce *pounce, PurplePounceOption options); /** * Sets the account that will do the pouncing. * - * @param pounce The buddy pounce. - * @param pouncer The account that will pounce. + * @pounce: The buddy pounce. + * @pouncer: The account that will pounce. */ void purple_pounce_set_pouncer(PurplePounce *pounce, PurpleAccount *pouncer); /** * Sets the buddy a pounce should pounce on. * - * @param pounce The buddy pounce. - * @param pouncee The buddy to pounce on. + * @pounce: The buddy pounce. + * @pouncee: The buddy to pounce on. */ void purple_pounce_set_pouncee(PurplePounce *pounce, const char *pouncee); /** * Sets whether or not the pounce should be saved after execution. * - * @param pounce The buddy pounce. - * @param save @c TRUE if the pounce should be saved, or @c FALSE otherwise. + * @pounce: The buddy pounce. + * @save: @c TRUE if the pounce should be saved, or @c FALSE otherwise. */ void purple_pounce_set_save(PurplePounce *pounce, gboolean save); /** * Registers an action type for the pounce. * - * @param pounce The buddy pounce. - * @param name The action name. + * @pounce: The buddy pounce. + * @name: The action name. */ void purple_pounce_action_register(PurplePounce *pounce, const char *name); /** * Enables or disables an action for a pounce. * - * @param pounce The buddy pounce. - * @param action The name of the action. - * @param enabled The enabled state. + * @pounce: The buddy pounce. + * @action: The name of the action. + * @enabled: The enabled state. */ void purple_pounce_action_set_enabled(PurplePounce *pounce, const char *action, gboolean enabled); @@ -165,10 +165,10 @@ * * If @a value is @c NULL, the value will be unset. * - * @param pounce The buddy pounce. - * @param action The action name. - * @param attr The attribute name. - * @param value The value. + * @pounce: The buddy pounce. + * @action: The action name. + * @attr: The attribute name. + * @value: The value. */ void purple_pounce_action_set_attribute(PurplePounce *pounce, const char *action, const char *attr, const char *value); @@ -176,53 +176,53 @@ /** * Sets the pounce-specific data. * - * @param pounce The buddy pounce. - * @param data Data specific to the pounce. + * @pounce: The buddy pounce. + * @data: Data specific to the pounce. */ void purple_pounce_set_data(PurplePounce *pounce, void *data); /** * Returns the events a pounce should watch for. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. * - * @return The events the pounce is watching for. + * Returns: The events the pounce is watching for. */ PurplePounceEvent purple_pounce_get_events(const PurplePounce *pounce); /** * Returns the options for a pounce. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. * - * @return The options for the pounce. + * Returns: The options for the pounce. */ PurplePounceOption purple_pounce_get_options(const PurplePounce *pounce); /** * Returns the account that will do the pouncing. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. * - * @return The account that will pounce. + * Returns: The account that will pounce. */ PurpleAccount *purple_pounce_get_pouncer(const PurplePounce *pounce); /** * Returns the buddy a pounce should pounce on. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. * - * @return The buddy to pounce on. + * Returns: The buddy to pounce on. */ const char *purple_pounce_get_pouncee(const PurplePounce *pounce); /** * Returns whether or not the pounce should save after execution. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. * - * @return @c TRUE if the pounce should be saved after execution, or + * Returns: @c TRUE if the pounce should be saved after execution, or * @c FALSE otherwise. */ gboolean purple_pounce_get_save(const PurplePounce *pounce); @@ -230,10 +230,10 @@ /** * Returns whether or not an action is enabled. * - * @param pounce The buddy pounce. - * @param action The action name. + * @pounce: The buddy pounce. + * @action: The action name. * - * @return @c TRUE if the action is enabled, or @c FALSE otherwise. + * Returns: @c TRUE if the action is enabled, or @c FALSE otherwise. */ gboolean purple_pounce_action_is_enabled(const PurplePounce *pounce, const char *action); @@ -241,11 +241,11 @@ /** * Returns the value for an attribute in an action. * - * @param pounce The buddy pounce. - * @param action The action name. - * @param attr The attribute name. + * @pounce: The buddy pounce. + * @action: The action name. + * @attr: The attribute name. * - * @return The attribute value, if it exists, or @c NULL. + * Returns: The attribute value, if it exists, or @c NULL. */ const char *purple_pounce_action_get_attribute(const PurplePounce *pounce, const char *action, @@ -254,18 +254,18 @@ /** * Returns the pounce-specific data. * - * @param pounce The buddy pounce. + * @pounce: The buddy pounce. * - * @return The data specific to a buddy pounce. + * Returns: The data specific to a buddy pounce. */ void *purple_pounce_get_data(const PurplePounce *pounce); /** * Executes a pounce with the specified pouncer, pouncee, and event type. * - * @param pouncer The account that will do the pouncing. - * @param pouncee The buddy that is being pounced. - * @param events The events that triggered the pounce. + * @pouncer: The account that will do the pouncing. + * @pouncee: The buddy that is being pounced. + * @events: The events that triggered the pounce. */ void purple_pounce_execute(const PurpleAccount *pouncer, const char *pouncee, PurplePounceEvent events); @@ -280,11 +280,11 @@ /** * Finds a pounce with the specified event(s) and buddy. * - * @param pouncer The account to match against. - * @param pouncee The buddy to match against. - * @param events The event(s) to match against. + * @pouncer: The account to match against. + * @pouncee: The buddy to match against. + * @events: The event(s) to match against. * - * @return The pounce if found, or @c NULL otherwise. + * Returns: The pounce if found, or @c NULL otherwise. */ PurplePounce *purple_find_pounce(const PurpleAccount *pouncer, const char *pouncee, PurplePounceEvent events); @@ -292,10 +292,10 @@ /** * Registers a pounce handler for a UI. * - * @param ui The UI name. - * @param cb The callback function. - * @param new_pounce The function called when a pounce is created. - * @param free_pounce The function called when a pounce is freed. + * @ui: The UI name. + * @cb: The callback function. + * @new_pounce: The function called when a pounce is created. + * @free_pounce: The function called when a pounce is freed. */ void purple_pounces_register_handler(const char *ui, PurplePounceCb cb, void (*new_pounce)(PurplePounce *pounce), @@ -304,23 +304,23 @@ /** * Unregisters a pounce handle for a UI. * - * @param ui The UI name. + * @ui: The UI name. */ void purple_pounces_unregister_handler(const char *ui); /** * Returns a list of all registered buddy pounces. * - * @constreturn The list of buddy pounces. + * Returns: (TODO const): The list of buddy pounces. */ GList *purple_pounces_get_all(void); /** * Returns a list of registered buddy pounces for the ui-type. * - * @param ui The ID of the UI using the core. + * @ui: The ID of the UI using the core. * - * @return The list of buddy pounces. The list should be freed by + * Returns: The list of buddy pounces. The list should be freed by * the caller when it's no longer used. */ GList *purple_pounces_get_all_for_ui(const char *ui); @@ -328,7 +328,7 @@ /** * Returns the buddy pounce subsystem handle. * - * @return The subsystem handle. + * Returns: The subsystem handle. */ void *purple_pounces_get_handle(void);
--- a/libpurple/prefs.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/prefs.h Wed Jan 29 05:28:33 2014 +0530 @@ -47,14 +47,14 @@ /** * The type of callbacks for preference changes. * - * @param name the name of the preference which has changed. - * @param type the type of the preferenced named @a name - * @param val the new value of the preferencs; should be cast to the correct + * @name: the name of the preference which has changed. + * @type: the type of the preferenced named @a name + * @val: the new value of the preferencs; should be cast to the correct * type. For instance, to recover the value of a #PURPLE_PREF_INT * preference, use <tt>GPOINTER_TO_INT(val)</tt>. Alternatively, * just call purple_prefs_get_int(), purple_prefs_get_string_list() * etc. - * @param data Arbitrary data specified when the callback was connected with + * @data: Arbitrary data specified when the callback was connected with * purple_prefs_connect_callback(). * * @see purple_prefs_connect_callback() @@ -74,7 +74,7 @@ /** * Returns the prefs subsystem handle. * - * @return The prefs subsystem handle. + * Returns: The prefs subsystem handle. */ void *purple_prefs_get_handle(void); @@ -91,39 +91,39 @@ /** * Add a new typeless pref. * - * @param name The name of the pref + * @name: The name of the pref */ void purple_prefs_add_none(const char *name); /** * Add a new boolean pref. * - * @param name The name of the pref - * @param value The initial value to set + * @name: The name of the pref + * @value: The initial value to set */ void purple_prefs_add_bool(const char *name, gboolean value); /** * Add a new integer pref. * - * @param name The name of the pref - * @param value The initial value to set + * @name: The name of the pref + * @value: The initial value to set */ void purple_prefs_add_int(const char *name, int value); /** * Add a new string pref. * - * @param name The name of the pref - * @param value The initial value to set + * @name: The name of the pref + * @value: The initial value to set */ void purple_prefs_add_string(const char *name, const char *value); /** * Add a new string list pref. * - * @param name The name of the pref - * @param value The initial value to set + * @name: The name of the pref + * @value: The initial value to set * @note This function takes a copy of the strings in the value list. The list * itself and original copies of the strings are up to the caller to * free. @@ -133,16 +133,16 @@ /** * Add a new path pref. * - * @param name The name of the pref - * @param value The initial value to set + * @name: The name of the pref + * @value: The initial value to set */ void purple_prefs_add_path(const char *name, const char *value); /** * Add a new path list pref. * - * @param name The name of the pref - * @param value The initial value to set + * @name: The name of the pref + * @value: The initial value to set * @note This function takes a copy of the strings in the value list. The list * itself and original copies of the strings are up to the caller to * free. @@ -153,23 +153,23 @@ /** * Remove a pref. * - * @param name The name of the pref + * @name: The name of the pref */ void purple_prefs_remove(const char *name); /** * Rename a pref * - * @param oldname The old name of the pref - * @param newname The new name for the pref + * @oldname: The old name of the pref + * @newname: The new name for the pref */ void purple_prefs_rename(const char *oldname, const char *newname); /** * Rename a boolean pref, toggling it's value * - * @param oldname The old name of the pref - * @param newname The new name for the pref + * @oldname: The old name of the pref + * @newname: The new name for the pref */ void purple_prefs_rename_boolean_toggle(const char *oldname, const char *newname); @@ -181,48 +181,48 @@ /** * Set boolean pref value * - * @param name The name of the pref - * @param value The value to set + * @name: The name of the pref + * @value: The value to set */ void purple_prefs_set_bool(const char *name, gboolean value); /** * Set integer pref value * - * @param name The name of the pref - * @param value The value to set + * @name: The name of the pref + * @value: The value to set */ void purple_prefs_set_int(const char *name, int value); /** * Set string pref value * - * @param name The name of the pref - * @param value The value to set + * @name: The name of the pref + * @value: The value to set */ void purple_prefs_set_string(const char *name, const char *value); /** * Set string list pref value * - * @param name The name of the pref - * @param value The value to set + * @name: The name of the pref + * @value: The value to set */ void purple_prefs_set_string_list(const char *name, GList *value); /** * Set path pref value * - * @param name The name of the pref - * @param value The value to set + * @name: The name of the pref + * @value: The value to set */ void purple_prefs_set_path(const char *name, const char *value); /** * Set path list pref value * - * @param name The name of the pref - * @param value The value to set + * @name: The name of the pref + * @value: The value to set */ void purple_prefs_set_path_list(const char *name, GList *value); @@ -230,72 +230,72 @@ /** * Check if a pref exists * - * @param name The name of the pref - * @return TRUE if the pref exists. Otherwise FALSE. + * @name: The name of the pref + * Returns: TRUE if the pref exists. Otherwise FALSE. */ gboolean purple_prefs_exists(const char *name); /** * Get pref type * - * @param name The name of the pref - * @return The type of the pref + * @name: The name of the pref + * Returns: The type of the pref */ PurplePrefType purple_prefs_get_type(const char *name); /** * Get boolean pref value * - * @param name The name of the pref - * @return The value of the pref + * @name: The name of the pref + * Returns: The value of the pref */ gboolean purple_prefs_get_bool(const char *name); /** * Get integer pref value * - * @param name The name of the pref - * @return The value of the pref + * @name: The name of the pref + * Returns: The value of the pref */ int purple_prefs_get_int(const char *name); /** * Get string pref value * - * @param name The name of the pref - * @return The value of the pref + * @name: The name of the pref + * Returns: The value of the pref */ const char *purple_prefs_get_string(const char *name); /** * Get string list pref value * - * @param name The name of the pref - * @return The value of the pref + * @name: The name of the pref + * Returns: The value of the pref */ GList *purple_prefs_get_string_list(const char *name); /** * Get path pref value * - * @param name The name of the pref - * @return The value of the pref + * @name: The name of the pref + * Returns: The value of the pref */ const char *purple_prefs_get_path(const char *name); /** * Get path list pref value * - * @param name The name of the pref - * @return The value of the pref + * @name: The name of the pref + * Returns: The value of the pref */ GList *purple_prefs_get_path_list(const char *name); /** * Returns a list of children for a pref * - * @param name The parent pref - * @return A list of newly allocated strings denoting the names of the children. + * @name: The parent pref + * Returns: A list of newly allocated strings denoting the names of the children. * Returns @c NULL if there are no children or if pref doesn't exist. * The caller must free all the strings and the list. */ @@ -304,12 +304,12 @@ /** * Add a callback to a pref (and its children) * - * @param handle The handle of the receiver. - * @param name The name of the preference - * @param cb The callback function - * @param data The data to pass to the callback function. + * @handle: The handle of the receiver. + * @name: The name of the preference + * @cb: The callback function + * @data: The data to pass to the callback function. * - * @return An id to disconnect the callback + * Returns: An id to disconnect the callback * * @see purple_prefs_disconnect_callback */
--- a/libpurple/presence.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/presence.h Wed Jan 29 05:28:33 2014 +0530 @@ -155,18 +155,18 @@ /** * Creates a presence for an account. * - * @param account The account to associate with the presence. + * @account: The account to associate with the presence. * - * @return The new presence. + * Returns: The new presence. */ PurpleAccountPresence *purple_account_presence_new(PurpleAccount *account); /** * Returns an account presence's account. * - * @param presence The presence. + * @presence: The presence. * - * @return The presence's account. + * Returns: The presence's account. */ PurpleAccount *purple_account_presence_get_account(const PurpleAccountPresence *presence); @@ -185,28 +185,28 @@ /** * Creates a presence for a buddy. * - * @param buddy The buddy to associate with the presence. + * @buddy: The buddy to associate with the presence. * - * @return The new presence. + * Returns: The new presence. */ PurpleBuddyPresence *purple_buddy_presence_new(PurpleBuddy *buddy); /** * Returns the buddy presence's buddy. * - * @param presence The presence. + * @presence: The presence. * - * @return The presence's buddy. + * Returns: The presence's buddy. */ PurpleBuddy *purple_buddy_presence_get_buddy(const PurpleBuddyPresence *presence); /** * Compares two buddy presences for availability. * - * @param buddy_presence1 The first presence. - * @param buddy_presence2 The second presence. + * @buddy_presence1: The first presence. + * @buddy_presence2: The second presence. * - * @return -1 if @a buddy_presence1 is more available than @a buddy_presence2. + * Returns: -1 if @a buddy_presence1 is more available than @a buddy_presence2. * 0 if @a buddy_presence1 is equal to @a buddy_presence2. * 1 if @a buddy_presence1 is less available than @a buddy_presence2. */ @@ -232,9 +232,9 @@ * be set active, so if you wish to disable a status, set another * non-independent status to active, or use purple_presence_switch_status(). * - * @param presence The presence. - * @param status_id The ID of the status. - * @param active The active state. + * @presence: The presence. + * @status_id: The ID of the status. + * @active: The active state. */ void purple_presence_set_status_active(PurplePresence *presence, const char *status_id, gboolean active); @@ -245,8 +245,8 @@ * This is similar to purple_presence_set_status_active(), except it won't * activate independent statuses. * - * @param presence The presence. - * @param status_id The status ID to switch to. + * @presence: The presence. + * @status_id: The status ID to switch to. */ void purple_presence_switch_status(PurplePresence *presence, const char *status_id); @@ -254,9 +254,9 @@ /** * Sets the idle state and time on a presence. * - * @param presence The presence. - * @param idle The idle state. - * @param idle_time The idle time, if @a idle is TRUE. This + * @presence: The presence. + * @idle: The idle state. + * @idle_time: The idle time, if @a idle is TRUE. This * is the time at which the user became idle, * in seconds since the epoch. If this value is * unknown then 0 should be used. @@ -267,27 +267,27 @@ /** * Sets the login time on a presence. * - * @param presence The presence. - * @param login_time The login time. + * @presence: The presence. + * @login_time: The login time. */ void purple_presence_set_login_time(PurplePresence *presence, time_t login_time); /** * Returns all the statuses in a presence. * - * @param presence The presence. + * @presence: The presence. * - * @constreturn The statuses. + * Returns: (TODO const): The statuses. */ GList *purple_presence_get_statuses(const PurplePresence *presence); /** * Returns the status with the specified ID from a presence. * - * @param presence The presence. - * @param status_id The ID of the status. + * @presence: The presence. + * @status_id: The ID of the status. * - * @return The status if found, or NULL. + * Returns: The status if found, or NULL. */ PurpleStatus *purple_presence_get_status(const PurplePresence *presence, const char *status_id); @@ -295,9 +295,9 @@ /** * Returns the active exclusive status from a presence. * - * @param presence The presence. + * @presence: The presence. * - * @return The active exclusive status. + * Returns: The active exclusive status. */ PurpleStatus *purple_presence_get_active_status(const PurplePresence *presence); @@ -306,18 +306,18 @@ * * Available presences are online and possibly invisible, but not away or idle. * - * @param presence The presence. + * @presence: The presence. * - * @return TRUE if the presence is available, or FALSE otherwise. + * Returns: TRUE if the presence is available, or FALSE otherwise. */ gboolean purple_presence_is_available(const PurplePresence *presence); /** * Returns whether or not a presence is online. * - * @param presence The presence. + * @presence: The presence. * - * @return TRUE if the presence is online, or FALSE otherwise. + * Returns: TRUE if the presence is online, or FALSE otherwise. */ gboolean purple_presence_is_online(const PurplePresence *presence); @@ -326,10 +326,10 @@ * * A status is active if itself or any of its sub-statuses are active. * - * @param presence The presence. - * @param status_id The ID of the status. + * @presence: The presence. + * @status_id: The ID of the status. * - * @return TRUE if the status is active, or FALSE. + * Returns: TRUE if the status is active, or FALSE. */ gboolean purple_presence_is_status_active(const PurplePresence *presence, const char *status_id); @@ -340,10 +340,10 @@ * * A status is active if itself or any of its sub-statuses are active. * - * @param presence The presence. - * @param primitive The status primitive. + * @presence: The presence. + * @primitive: The status primitive. * - * @return TRUE if the status is active, or FALSE. + * Returns: TRUE if the status is active, or FALSE. */ gboolean purple_presence_is_status_primitive_active( const PurplePresence *presence, PurpleStatusPrimitive primitive); @@ -351,9 +351,9 @@ /** * Returns whether or not a presence is idle. * - * @param presence The presence. + * @presence: The presence. * - * @return TRUE if the presence is idle, or FALSE otherwise. + * Returns: TRUE if the presence is idle, or FALSE otherwise. * If the presence is offline (purple_presence_is_online() * returns FALSE) then FALSE is returned. */ @@ -362,18 +362,18 @@ /** * Returns the presence's idle time. * - * @param presence The presence. + * @presence: The presence. * - * @return The presence's idle time. + * Returns: The presence's idle time. */ time_t purple_presence_get_idle_time(const PurplePresence *presence); /** * Returns the presence's login time. * - * @param presence The presence. + * @presence: The presence. * - * @return The presence's login time. + * Returns: The presence's login time. */ time_t purple_presence_get_login_time(const PurplePresence *presence);
--- a/libpurple/protocol.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/protocol.h Wed Jan 29 05:28:33 2014 +0530 @@ -197,17 +197,17 @@ * On the other hand, both of these are invalid for protocols with * number-based usernames, so function should return NULL in such case. * - * @param account The account the username is related to. Can + * @account: The account the username is related to. Can * be NULL. - * @param who The username to convert. - * @return Normalized username, or NULL, if it's invalid. + * @who: The username to convert. + * Returns: Normalized username, or NULL, if it's invalid. */ const char *(*normalize)(const PurpleAccount *account, const char *who); PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name); /** Checks whether offline messages to @a buddy are supported. - * @return @c TRUE if @a buddy can be sent messages while they are + * Returns: @c TRUE if @a buddy can be sent messages while they are * offline, or @c FALSE if not. */ gboolean (*offline_message)(const PurpleBuddy *buddy); @@ -217,8 +217,8 @@ * table instead of expanding the struct for every addition. This hash * table is allocated every call and MUST be unrefed by the caller. * - * @param account The account to specify. This can be NULL. - * @return The protocol's string hash table. The hash table should be + * @account: The account to specify. This can be NULL. + * Returns: The protocol's string hash table. The hash table should be * destroyed by the caller when it's no longer needed. */ GHashTable *(*get_account_text_table)(PurpleAccount *account); @@ -241,10 +241,10 @@ * - formatting, * - used special characters. * - * @param conv The conversation to query, or NULL to get safe minimum + * @conv: The conversation to query, or NULL to get safe minimum * for the protocol. * - * @return Maximum message size, 0 if unspecified, -1 for infinite. + * Returns: Maximum message size, 0 if unspecified, -1 for infinite. */ gssize (*get_max_message_size)(PurpleConversation *conv); }; @@ -348,12 +348,12 @@ * call one of the callbacks from an idle/0-second timeout) depending * on if the nickname is set successfully. * - * @param gc The connection for which to set an alias - * @param alias The new server-side alias/nickname for this account, + * @gc: The connection for which to set an alias + * @alias: The new server-side alias/nickname for this account, * or NULL to unset the alias/nickname (or return it to * a protocol-specific "default"). - * @param success_cb Callback to be called if the public alias is set - * @param failure_cb Callback to be called if setting the public alias + * @success_cb: Callback to be called if the public alias is set + * @failure_cb: Callback to be called if setting the public alias * fails * @see purple_account_set_public_alias */ @@ -368,9 +368,9 @@ * call one of the callbacks from an idle/0-second timeout) depending * on if the nickname is retrieved. * - * @param gc The connection for which to retireve the alias - * @param success_cb Callback to be called with the retrieved alias - * @param failure_cb Callback to be called if the protocol is unable to + * @gc: The connection for which to retireve the alias + * @success_cb: Callback to be called with the retrieved alias + * @failure_cb: Callback to be called if the protocol is unable to * retrieve the alias * @see purple_account_get_public_alias */ @@ -411,7 +411,7 @@ PurpleMessageFlags flags); /** - * @return If this protocol requires the PURPLE_IM_TYPING message to + * Returns: If this protocol requires the PURPLE_IM_TYPING message to * be sent repeatedly to signify that the user is still * typing, then the protocol should return the number of * seconds to wait before sending a subsequent notification. @@ -444,7 +444,7 @@ * information required by the protocol to join a chat. libpurple will * call join_chat along with the information filled by the user. * - * @return A list of #PurpleProtocolChatEntry structs + * Returns: A list of #PurpleProtocolChatEntry structs */ GList *(*info)(PurpleConnection *); @@ -456,8 +456,8 @@ * #get_chat_name if you instead need to extract a chat name from a * hashtable. * - * @param chat_name The chat name to be turned into components - * @return Hashtable containing the information extracted from chat_name + * @chat_name: The chat name to be turned into components + * Returns: Hashtable containing the information extracted from chat_name */ GHashTable *(*info_defaults)(PurpleConnection *, const char *chat_name); @@ -466,7 +466,7 @@ * Called when the user requests joining a chat. Should arrange for * #serv_got_joined_chat to be called. * - * @param components A hashtable containing information required to + * @components: A hashtable containing information required to * join the chat as described by the entries returned * by #chat_info. It may also be called when accepting * an invitation, in which case this matches the @@ -477,7 +477,7 @@ /** * Called when the user refuses a chat invitation. * - * @param components A hashtable containing information required to + * @components: A hashtable containing information required to * join the chat as passed to #serv_got_chat_invite. */ void (*reject)(PurpleConnection *, GHashTable *components); @@ -487,33 +487,33 @@ * #chat_info_defaults if you instead need to generate a hashtable * from a chat name. * - * @param components A hashtable containing information about the chat. + * @components: A hashtable containing information about the chat. */ char *(*get_name)(GHashTable *components); /** * Invite a user to join a chat. * - * @param id The id of the chat to invite the user to. - * @param message A message displayed to the user when the invitation + * @id: The id of the chat to invite the user to. + * @message: A message displayed to the user when the invitation * is received. - * @param who The name of the user to send the invation to. + * @who: The name of the user to send the invation to. */ void (*invite)(PurpleConnection *, int id, const char *message, const char *who); /** * Called when the user requests leaving a chat. * - * @param id The id of the chat to leave + * @id: The id of the chat to leave */ void (*leave)(PurpleConnection *, int id); /** * Send a whisper to a user in a chat. * - * @param id The id of the chat. - * @param who The name of the user to send the whisper to. - * @param message The message of the whisper. + * @id: The id of the chat. + * @who: The name of the user to send the whisper to. + * @message: The message of the whisper. */ void (*whisper)(PurpleConnection *, int id, const char *who, const char *message); @@ -527,11 +527,11 @@ * some other negative value. You can use one of the valid * errno values, or just big something. * - * @param id The id of the chat to send the message to. - * @param message The message to send to the chat. - * @param flags A bitwise OR of #PurpleMessageFlags representing + * @id: The id of the chat to send the message to. + * @message: The message to send to the chat. + * @flags: A bitwise OR of #PurpleMessageFlags representing * message flags. - * @return A positive number or 0 in case of success, + * Returns: A positive number or 0 in case of success, * a negative error number in case of failure. */ int (*send)(PurpleConnection *, int id, const char *message, @@ -540,10 +540,10 @@ /** Gets the real name of a participant in a chat. For example, on * XMPP this turns a chat room nick <tt>foo</tt> into * <tt>room\@server/foo</tt> - * @param gc the connection on which the room is. - * @param id the ID of the chat room. - * @param who the nickname of the chat participant. - * @return the real name of the participant. This string must be + * @gc: the connection on which the room is. + * @id: the ID of the chat room. + * @who: the nickname of the chat participant. + * Returns: the real name of the participant. This string must be * freed by the caller. */ char *(*get_user_real_name)(PurpleConnection *gc, int id, const char *who); @@ -671,10 +671,10 @@ /** * Initiate a media session with the given contact. * - * @param account The account to initiate the media session on. - * @param who The remote user to initiate the session with. - * @param type The type of media session to initiate. - * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media + * @account: The account to initiate the media session on. + * @who: The remote user to initiate the session with. + * @type: The type of media session to initiate. + * Returns: TRUE if the call succeeded else FALSE. (Doesn't imply the media * session or stream will be successfully created) */ gboolean (*initiate_session)(PurpleAccount *account, const char *who, @@ -684,9 +684,9 @@ * Checks to see if the given contact supports the given type of media * session. * - * @param account The account the contact is on. - * @param who The remote user to check for media capability with. - * @return The media caps the contact supports. + * @account: The account the contact is on. + * @who: The remote user to check for media capability with. + * Returns: The media caps the contact supports. */ PurpleMediaCaps (*get_caps)(PurpleAccount *account, const char *who); @@ -763,63 +763,63 @@ /** * Returns the ID of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The ID of the protocol. + * Returns: The ID of the protocol. */ const char *purple_protocol_get_id(const PurpleProtocol *protocol); /** * Returns the translated name of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The translated name of the protocol. + * Returns: The translated name of the protocol. */ const char *purple_protocol_get_name(const PurpleProtocol *protocol); /** * Returns the options of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The options of the protocol. + * Returns: The options of the protocol. */ PurpleProtocolOptions purple_protocol_get_options(const PurpleProtocol *protocol); /** * Returns the user splits of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The user splits of the protocol. + * Returns: The user splits of the protocol. */ GList *purple_protocol_get_user_splits(const PurpleProtocol *protocol); /** * Returns the protocol options of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The protocol options of the protocol. + * Returns: The protocol options of the protocol. */ GList *purple_protocol_get_protocol_options(const PurpleProtocol *protocol); /** * Returns the icon spec of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The icon spec of the protocol. + * Returns: The icon spec of the protocol. */ PurpleBuddyIconSpec *purple_protocol_get_icon_spec(const PurpleProtocol *protocol); /** * Returns the whiteboard ops of a protocol. * - * @param protocol The protocol. + * @protocol: The protocol. * - * @return The whiteboard ops of the protocol. + * Returns: The whiteboard ops of the protocol. */ PurpleWhiteboardOps *purple_protocol_get_whiteboard_ops(const PurpleProtocol *protocol); @@ -829,8 +829,8 @@ * This function is called in the *_init() function of your derived protocol, * to delete the parent type's data so you can define your own. * - * @param protocol The protocol instance. - * @param flags What instance data to delete. + * @protocol: The protocol instance. + * @flags: What instance data to delete. */ void purple_protocol_override(PurpleProtocol *protocol, PurpleProtocolOverrideFlags flags);
--- a/libpurple/protocols.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/protocols.h Wed Jan 29 05:28:33 2014 +0530 @@ -196,15 +196,15 @@ /** * Creates a new #PurpleAttentionType object and sets its mandatory parameters. * - * @param ulname A non-localized string that can be used by UIs in need of such + * @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, * without localization. - * @param name A localized string that the UI may display for the event. This + * @name: A localized string that the UI may display for the event. This * should be the same string as @a ulname, with localization. - * @param inc_desc A localized description shown when the event is received. - * @param out_desc A localized description shown when the event is sent. + * @inc_desc: A localized description shown when the event is received. + * @out_desc: A localized description shown when the event is sent. * - * @return A pointer to the new object. + * 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); @@ -212,8 +212,8 @@ /** * Sets the displayed name of the attention-demanding event. * - * @param type The attention type. - * @param name The localized name that will be displayed by UIs. This should be + * @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. */ @@ -223,8 +223,8 @@ * Sets the description of the attention-demanding event shown in conversations * when the event is received. * - * @param type The attention type. - * @param desc The localized description for incoming events. + * @type: The attention type. + * @desc: The localized description for incoming events. */ void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc); @@ -232,16 +232,16 @@ * Sets the description of the attention-demanding event shown in conversations * when the event is sent. * - * @param type The attention type. - * @param desc The localized description for outgoing events. + * @type: The attention type. + * @desc: The localized description for outgoing events. */ 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. * - * @param type The attention type. - * @param name The icon's name. + * @type: The attention type. + * @name: The icon's name. * @note Icons are optional for attention events. */ void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name); @@ -250,8 +250,8 @@ * Sets the unlocalized name of the attention event; some UIs may need this, * thus it is required. * - * @param type The attention type. - * @param ulname The unlocalized name. This should be the same string given as + * @type: The attention type. + * @ulname: The unlocalized name. This should be the same string given as * the localized name, but without localization. */ void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname); @@ -259,33 +259,33 @@ /** * Get the attention type's name as displayed by the UI. * - * @param type The attention type. + * @type: The attention type. * - * @return The name. + * Returns: The name. */ const char *purple_attention_type_get_name(const PurpleAttentionType *type); /** * Get the attention type's description shown when the event is received. * - * @param type The attention type. - * @return The description. + * @type: The attention type. + * Returns: The description. */ const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type); /** * Get the attention type's description shown when the event is sent. * - * @param type The attention type. - * @return The description. + * @type: The attention type. + * Returns: The description. */ const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type); /** * Get the attention type's icon name. * - * @param type The attention type. - * @return The icon name or @c NULL if unset/empty. + * @type: The attention type. + * Returns: The icon name or @c NULL if unset/empty. * @note Icons are optional for attention events. */ const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type); @@ -293,8 +293,8 @@ /** * Get the attention type's unlocalized name; this is useful for some UIs. * - * @param type The attention type - * @return The unlocalized name. + * @type: The attention type + * Returns: The unlocalized name. */ const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type); @@ -314,8 +314,8 @@ * Allocates and returns a new PurpleProtocolAction. Use this to add actions in * a list in the get_actions function of the protocol. * - * @param label The description of the action to show to the user. - * @param callback The callback to call when the user selects this action. + * @label: The description of the action to show to the user. + * @callback: The callback to call when the user selects this action. */ PurpleProtocolAction *purple_protocol_action_new(const char* label, PurpleProtocolActionCallback callback); @@ -323,7 +323,7 @@ /** * Frees a PurpleProtocolAction * - * @param action The PurpleProtocolAction to free. + * @action: The PurpleProtocolAction to free. */ void purple_protocol_action_free(PurpleProtocolAction *action); @@ -351,9 +351,9 @@ * * This is meant to be called from protocols. * - * @param account The account. - * @param idle The user's idle state. - * @param idle_time The user's idle time. + * @account: The account. + * @idle: The user's idle state. + * @idle_time: The user's idle time. */ void purple_protocol_got_account_idle(PurpleAccount *account, gboolean idle, time_t idle_time); @@ -363,8 +363,8 @@ * * This is meant to be called from protocols. * - * @param account The account the user is on. - * @param login_time The user's log-in time. + * @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); @@ -374,9 +374,9 @@ * * This is meant to be called from protocols. * - * @param account The account the user is on. - * @param status_id The status ID. - * @param ... A NULL-terminated list of attribute IDs and values, + * @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. */ void purple_protocol_got_account_status(PurpleAccount *account, @@ -390,7 +390,7 @@ * * This is meant to be called from protocols. * - * @param account The account. + * @account: The account. * * @see account-actions-changed */ @@ -401,10 +401,10 @@ * * This is meant to be called from protocols. * - * @param account The account the user is on. - * @param name The name of the buddy. - * @param idle The user's idle state. - * @param idle_time The user's idle time. This is the time at + * @account: The account the user is on. + * @name: The name of the buddy. + * @idle: The user's idle state. + * @idle_time: The user's idle time. This is the time at * which the user became idle, in seconds since * the epoch. If the protocol does not know this value * then it should pass 0. @@ -417,9 +417,9 @@ * * This is meant to be called from protocols. * - * @param account The account the user is on. - * @param name The name of the buddy. - * @param login_time The user's log-in time. + * @account: The account the user is on. + * @name: The name of the buddy. + * @login_time: The user's log-in time. */ void purple_protocol_got_user_login_time(PurpleAccount *account, const char *name, time_t login_time); @@ -429,10 +429,10 @@ * * This is meant to be called from protocols. * - * @param account The account the user is on. - * @param name The name of the buddy. - * @param status_id The status ID. - * @param ... A NULL-terminated list of attribute IDs and values, + * @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. */ void purple_protocol_got_user_status(PurpleAccount *account, const char *name, @@ -444,9 +444,9 @@ * * This is meant to be called from protocols. * - * @param account The account the user is on. - * @param name The name of the buddy. - * @param status_id The status ID. + * @account: The account the user is on. + * @name: The name of the buddy. + * @status_id: The status ID. */ void purple_protocol_got_user_status_deactive(PurpleAccount *account, const char *name, @@ -455,9 +455,9 @@ /** * Informs the server that our account's status changed. * - * @param account The account the user is on. - * @param old_status The previous status. - * @param new_status The status that was activated, or deactivated + * @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). */ void purple_protocol_change_account_status(PurpleAccount *account, @@ -467,10 +467,10 @@ /** * Retrieves the list of stock status types from a protocol. * - * @param account The account the user is on. - * @param presence The presence for which we're going to get statuses + * @account: The account the user is on. + * @presence: The presence for which we're going to get statuses * - * @return List of statuses + * Returns: List of statuses */ GList *purple_protocol_get_statuses(PurpleAccount *account, PurplePresence *presence); @@ -478,9 +478,9 @@ /** * Send an attention request message. * - * @param gc The connection to send the message on. - * @param who Whose attention to request. - * @param type_code An index into the protocol's attention_types list + * @gc: The connection to send the message on. + * @who: Whose attention to request. + * @type_code: An index into the protocol's attention_types list * determining the type of the attention request command to * send. 0 if protocol only defines one (for example, Yahoo and * MSN), but some protocols define more (MySpaceIM). @@ -494,9 +494,9 @@ /** * Process an incoming attention message. * - * @param gc The connection that received the attention message. - * @param who Who requested your attention. - * @param type_code An index into the protocol's attention_types list + * @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. */ @@ -506,10 +506,10 @@ /** * Process an incoming attention message in a chat. * - * @param gc The connection that received the attention message. - * @param id The chat id. - * @param who Who requested your attention. - * @param type_code An index into the protocol's attention_types list + * @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. */ @@ -519,10 +519,10 @@ /** * Determines if the contact supports the given media session type. * - * @param account The account the user is on. - * @param who The name of the contact to check capabilities for. + * @account: The account the user is on. + * @who: The name of the contact to check capabilities for. * - * @return The media caps the contact supports. + * Returns: The media caps the contact supports. */ PurpleMediaCaps purple_protocol_get_media_caps(PurpleAccount *account, const char *who); @@ -530,11 +530,11 @@ /** * Initiates a media session with the given contact. * - * @param account The account the user is on. - * @param who The name of the contact to start a session with. - * @param type The type of media session to start. + * @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. * - * @return TRUE if the call succeeded else FALSE. (Doesn't imply the media + * Returns: TRUE if the call succeeded else FALSE. (Doesn't imply the media * session or stream will be successfully created) */ gboolean purple_protocol_initiate_media(PurpleAccount *account, @@ -546,8 +546,8 @@ * * This function is intended to be used only by protocols. * - * @param account The account the user is on. - * @param who The name of the contact for which capabilities have been received. + * @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); @@ -556,9 +556,9 @@ * * @see PurpleProtocol#get_max_message_size * - * @param protocol The protocol to query. + * @protocol: The protocol to query. * - * @return Maximum message size, 0 if unspecified, -1 for infinite. + * Returns: Maximum message size, 0 if unspecified, -1 for infinite. */ gssize purple_protocol_get_max_message_size(PurpleProtocol *protocol); @@ -573,18 +573,18 @@ /** * Finds a protocol by ID. * - * @param id The protocol's ID. + * @id: The protocol's ID. */ PurpleProtocol *purple_protocols_find(const char *id); /** * Adds a protocol to the list of protocols. * - * @param protocol_type The type of the protocol to add. - * @param error Return location for a #GError or @c NULL. If provided, this + * @protocol_type: The type of the protocol to add. + * @error: Return location for a #GError or @c NULL. If provided, this * will be set to the reason if adding fails. * - * @return The protocol instance if the protocol was added, else @c NULL. + * Returns: The protocol instance if the protocol was added, else @c NULL. */ PurpleProtocol *purple_protocols_add(GType protocol_type, GError **error); @@ -593,18 +593,18 @@ * connected accounts using this protocol, and free the protocol's user splits * and protocol options. * - * @param protocol The protocol to remove. - * @param error Return location for a #GError or @c NULL. If provided, this + * @protocol: The protocol to remove. + * @error: Return location for a #GError or @c NULL. If provided, this * will be set to the reason if removing fails. * - * @return TRUE if the protocol was removed, else FALSE. + * Returns: TRUE if the protocol was removed, else FALSE. */ gboolean purple_protocols_remove(PurpleProtocol *protocol, GError **error); /** * Returns a list of all loaded protocols. * - * @return A list of all loaded protocols. The list is owned by the caller, and + * Returns: A list of all loaded protocols. The list is owned by the caller, and * must be g_list_free()d to avoid leaking the nodes. */ GList *purple_protocols_get_all(void); @@ -624,7 +624,7 @@ /** * Returns the protocols subsystem handle. * - * @return The protocols subsystem handle. + * Returns: The protocols subsystem handle. */ void *purple_protocols_get_handle(void);
--- a/libpurple/proxy.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/proxy.h Wed Jan 29 05:28:33 2014 +0530 @@ -66,99 +66,99 @@ /** * Creates a proxy information structure. * - * @return The proxy information structure. + * Returns: The proxy information structure. */ PurpleProxyInfo *purple_proxy_info_new(void); /** * Destroys a proxy information structure. * - * @param info The proxy information structure to destroy. + * @info: The proxy information structure to destroy. */ void purple_proxy_info_destroy(PurpleProxyInfo *info); /** * Sets the type of proxy. * - * @param info The proxy information. - * @param type The proxy type. + * @info: The proxy information. + * @type: The proxy type. */ void purple_proxy_info_set_type(PurpleProxyInfo *info, PurpleProxyType type); /** * Sets the proxy host. * - * @param info The proxy information. - * @param host The host. + * @info: The proxy information. + * @host: The host. */ void purple_proxy_info_set_host(PurpleProxyInfo *info, const char *host); /** * Sets the proxy port. * - * @param info The proxy information. - * @param port The port. + * @info: The proxy information. + * @port: The port. */ void purple_proxy_info_set_port(PurpleProxyInfo *info, int port); /** * Sets the proxy username. * - * @param info The proxy information. - * @param username The username. + * @info: The proxy information. + * @username: The username. */ void purple_proxy_info_set_username(PurpleProxyInfo *info, const char *username); /** * Sets the proxy password. * - * @param info The proxy information. - * @param password The password. + * @info: The proxy information. + * @password: The password. */ void purple_proxy_info_set_password(PurpleProxyInfo *info, const char *password); /** * Returns the proxy's type. * - * @param info The proxy information. + * @info: The proxy information. * - * @return The type. + * Returns: The type. */ PurpleProxyType purple_proxy_info_get_type(const PurpleProxyInfo *info); /** * Returns the proxy's host. * - * @param info The proxy information. + * @info: The proxy information. * - * @return The host. + * Returns: The host. */ const char *purple_proxy_info_get_host(const PurpleProxyInfo *info); /** * Returns the proxy's port. * - * @param info The proxy information. + * @info: The proxy information. * - * @return The port. + * Returns: The port. */ int purple_proxy_info_get_port(const PurpleProxyInfo *info); /** * Returns the proxy's username. * - * @param info The proxy information. + * @info: The proxy information. * - * @return The username. + * Returns: The username. */ const char *purple_proxy_info_get_username(const PurpleProxyInfo *info); /** * Returns the proxy's password. * - * @param info The proxy information. + * @info: The proxy information. * - * @return The password. + * Returns: The password. */ const char *purple_proxy_info_get_password(const PurpleProxyInfo *info); @@ -172,14 +172,14 @@ /** * Returns purple's global proxy information. * - * @return The global proxy information. + * Returns: The global proxy information. */ PurpleProxyInfo *purple_global_proxy_get_info(void); /** * Set purple's global proxy information. * - * @param info The proxy information. + * @info: The proxy information. */ void purple_global_proxy_set_info(PurpleProxyInfo *info); @@ -193,7 +193,7 @@ /** * Returns the proxy subsystem handle. * - * @return The proxy subsystem handle. + * Returns: The proxy subsystem handle. */ void *purple_proxy_get_handle(void); @@ -210,9 +210,9 @@ /** * Returns configuration of a proxy. * - * @param account The account for which the configuration is needed. + * @account: The account for which the configuration is needed. * - * @return The configuration of a proxy. + * Returns: The configuration of a proxy. */ PurpleProxyInfo *purple_proxy_get_setup(PurpleAccount *account); @@ -222,21 +222,21 @@ * connect," it is used for establishing any outgoing TCP connection, * whether through a proxy or not. * - * @param handle A handle that should be associated with this + * @handle: A handle that should be associated with this * connection attempt. The handle can be used * to cancel the connection attempt using the * purple_proxy_connect_cancel_with_handle() * function. - * @param account The account making the connection. - * @param host The destination host. - * @param port The destination port. - * @param connect_cb The function to call when the connection is + * @account: The account making the connection. + * @host: The destination host. + * @port: The destination port. + * @connect_cb: The function to call when the connection is * established. If the connection failed then * fd will be -1 and error message will be set * to something descriptive (hopefully). - * @param data User-defined data. + * @data: User-defined data. * - * @return NULL if there was an error, or a reference to an + * Returns: NULL if there was an error, or a reference to an * opaque data structure that can be used to cancel * the pending connection, if needed. */ @@ -251,21 +251,21 @@ * connect," it is used for establishing any outgoing UDP connection, * whether through a proxy or not. * - * @param handle A handle that should be associated with this + * @handle: A handle that should be associated with this * connection attempt. The handle can be used * to cancel the connection attempt using the * purple_proxy_connect_cancel_with_handle() * function. - * @param account The account making the connection. - * @param host The destination host. - * @param port The destination port. - * @param connect_cb The function to call when the connection is + * @account: The account making the connection. + * @host: The destination host. + * @port: The destination port. + * @connect_cb: The function to call when the connection is * established. If the connection failed then * fd will be -1 and error message will be set * to something descriptive (hopefully). - * @param data User-defined data. + * @data: User-defined data. * - * @return NULL if there was an error, or a reference to an + * Returns: NULL if there was an error, or a reference to an * opaque data structure that can be used to cancel * the pending connection, if needed. */ @@ -280,22 +280,22 @@ * Note that if the account that is making the connection uses a proxy, this * connection to a SOCKS5 proxy will be made through the account proxy. * - * @param handle A handle that should be associated with this + * @handle: A handle that should be associated with this * connection attempt. The handle can be used * to cancel the connection attempt using the * purple_proxy_connect_cancel_with_handle() * function. - * @param account The account making the connection. - * @param gpi The PurpleProxyInfo specifying the proxy settings - * @param host The destination host. - * @param port The destination port. - * @param connect_cb The function to call when the connection is + * @account: The account making the connection. + * @gpi: The PurpleProxyInfo specifying the proxy settings + * @host: The destination host. + * @port: The destination port. + * @connect_cb: The function to call when the connection is * established. If the connection failed then * fd will be -1 and error message will be set * to something descriptive (hopefully). - * @param data User-defined data. + * @data: User-defined data. * - * @return NULL if there was an error, or a reference to an + * Returns: NULL if there was an error, or a reference to an * opaque data structure that can be used to cancel * the pending connection, if needed. */ @@ -318,7 +318,7 @@ /* * Closes all proxy connections registered with the specified handle. * - * @param handle The handle. + * @handle: The handle. */ void purple_proxy_connect_cancel_with_handle(void *handle);
--- a/libpurple/purple-socket.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/purple-socket.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,9 +37,9 @@ /** * A callback fired after (successfully or not) establishing a connection. * - * @param ps The socket. - * @param error Error message, or NULL if connection was successful. - * @param user_data The user data passed with callback function. + * @ps: The socket. + * @error: Error message, or NULL if connection was successful. + * @user_data: The user data passed with callback function. */ typedef void (*PurpleSocketConnectCb)(PurpleSocket *ps, const gchar *error, gpointer user_data); @@ -49,9 +49,9 @@ * * Passing a PurpleConnection allows for proper proxy handling. * - * @param gs The connection for which the socket is needed, or NULL. + * @gs: The connection for which the socket is needed, or NULL. * - * @return The new socket struct. + * Returns: The new socket struct. */ PurpleSocket * purple_socket_new(PurpleConnection *gc); @@ -59,9 +59,9 @@ /** * Gets PurpleConnection tied with specified socket. * - * @param ps The socket. + * @ps: The socket. * - * @return The PurpleConnection object. + * Returns: The PurpleConnection object. */ PurpleConnection * purple_socket_get_connection(PurpleSocket *ps); @@ -69,8 +69,8 @@ /** * Determines, if socket should handle TLS. * - * @param ps The socket. - * @param is_tls TRUE, if TLS should be handled transparently, FALSE otherwise. + * @ps: The socket. + * @is_tls: TRUE, if TLS should be handled transparently, FALSE otherwise. */ void purple_socket_set_tls(PurpleSocket *ps, gboolean is_tls); @@ -78,8 +78,8 @@ /** * Sets connection host. * - * @param ps The socket. - * @param host The connection host. + * @ps: The socket. + * @host: The connection host. */ void purple_socket_set_host(PurpleSocket *ps, const gchar *host); @@ -87,8 +87,8 @@ /** * Sets connection port. * - * @param ps The socket. - * @param port The connection port. + * @ps: The socket. + * @port: The connection port. */ void purple_socket_set_port(PurpleSocket *ps, int port); @@ -96,12 +96,12 @@ /** * Establishes a connection. * - * @param ps The socket. - * @param cb The function to call after establishing a connection, or on + * @ps: The socket. + * @cb: The function to call after establishing a connection, or on * error. - * @param user_data The user data to be passed to callback function. + * @user_data: The user data to be passed to callback function. * - * @return TRUE on success (this doesn't mean it's connected yet), FALSE + * Returns: TRUE on success (this doesn't mean it's connected yet), FALSE * otherwise. */ gboolean @@ -113,11 +113,11 @@ * * This function deals with TLS, if the socket is configured to do it. * - * @param ps The socket. - * @param buf The buffer to write data to. - * @param len The buffer size. + * @ps: The socket. + * @buf: The buffer to write data to. + * @len: The buffer size. * - * @return Amount of data written, or -1 on error (errno will be also be set). + * Returns: Amount of data written, or -1 on error (errno will be also be set). */ gssize purple_socket_read(PurpleSocket *ps, guchar *buf, size_t len); @@ -127,11 +127,11 @@ * * This function deals with TLS, if the socket is configured to do it. * - * @param ps The socket. - * @param buf The buffer to read data from. - * @param len The amount of data to read and send. + * @ps: The socket. + * @buf: The buffer to read data from. + * @len: The amount of data to read and send. * - * @param Amount of data sent, or -1 on error (errno will albo be set). + * @Amount: of data sent, or -1 on error (errno will albo be set). */ gssize purple_socket_write(PurpleSocket *ps, const guchar *buf, size_t len); @@ -142,11 +142,11 @@ * If the specified socket had input handler already registered, it will be * removed. To remove any input handlers, pass an NULL handler function. * - * @param ps The socket. - * @param cond The condition type. - * @param func The callback function for data, or NULL to remove any + * @ps: The socket. + * @cond: The condition type. + * @func: The callback function for data, or NULL to remove any * existing callbacks. - * @param user_data The user data to be passed to callback function. + * @user_data: The user data to be passed to callback function. */ void purple_socket_watch(PurpleSocket *ps, PurpleInputCondition cond, @@ -158,9 +158,9 @@ * It's not meant to read/write data (use purple_socket_read/ * purple_socket_write), rather for watching for changes with select(). * - * @param ps The socket + * @ps: The socket * - * @return The file descriptor, or -1 on error. + * Returns: The file descriptor, or -1 on error. */ int purple_socket_get_fd(PurpleSocket *ps); @@ -168,9 +168,9 @@ /** * Sets extra data for a socket. * - * @param ps The socket. - * @param key The unique key. - * @param data The data to assign, or NULL to remove. + * @ps: The socket. + * @key: The unique key. + * @data: The data to assign, or NULL to remove. */ void purple_socket_set_data(PurpleSocket *ps, const gchar *key, gpointer data); @@ -178,10 +178,10 @@ /** * Returns extra data in a socket. * - * @param ps The socket. - * @param key The unqiue key. + * @ps: The socket. + * @key: The unqiue key. * - * @return The data associated with the key. + * Returns: The data associated with the key. */ gpointer purple_socket_get_data(PurpleSocket *ps, const gchar *key); @@ -192,7 +192,7 @@ * If file descriptor for the socket was extracted with purple_socket_get_fd and * added to event loop, it have to be removed prior this. * - * @param ps The socket. + * @ps: The socket. */ void purple_socket_destroy(PurpleSocket *ps);
--- a/libpurple/request-datasheet.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/request-datasheet.h Wed Jan 29 05:28:33 2014 +0530 @@ -53,7 +53,7 @@ /** * Creates new Datasheet. * - * @return The new datasheet. + * Returns: The new datasheet. */ PurpleRequestDatasheet * purple_request_datasheet_new(void); @@ -61,7 +61,7 @@ /** * Destroys datasheet with all its contents. * - * @param sheet The datasheet. + * @sheet: The datasheet. */ void purple_request_datasheet_free(PurpleRequestDatasheet *sheet); @@ -71,9 +71,9 @@ * * You cannot add a column if datasheet contains any data. * - * @param sheet The datasheet. - * @param type The column type. - * @param title The column title (may be @c NULL). + * @sheet: The datasheet. + * @type: The column type. + * @title: The column title (may be @c NULL). */ void purple_request_datasheet_add_column(PurpleRequestDatasheet *sheet, @@ -82,9 +82,9 @@ /** * Returns the column count of datasheet. * - * @param sheet The datasheet. + * @sheet: The datasheet. * - * @return The column count. + * Returns: The column count. */ guint purple_request_datasheet_get_column_count(PurpleRequestDatasheet *sheet); @@ -92,10 +92,10 @@ /** * Returns the column type for a datasheet. * - * @param sheet The datasheet. - * @param col_no The column number (0 is the first one). + * @sheet: The datasheet. + * @col_no: The column number (0 is the first one). * - * @return The column type. + * Returns: The column type. */ PurpleRequestDatasheetColumnType purple_request_datasheet_get_column_type(PurpleRequestDatasheet *sheet, @@ -104,10 +104,10 @@ /** * Returns the column title for a datasheet. * - * @param sheet The datasheet. - * @param col_no The column number (0 is the first one). + * @sheet: The datasheet. + * @col_no: The column number (0 is the first one). * - * @return The column title. + * Returns: The column title. */ const gchar * purple_request_datasheet_get_column_title(PurpleRequestDatasheet *sheet, @@ -118,9 +118,9 @@ * * You shouldn't modify datasheet's data while iterating through it. * - * @param sheet The datasheet. + * @sheet: The datasheet. * - * @constreturn The list of records. + * Returns: (TODO const): The list of records. */ const GList * purple_request_datasheet_get_records(PurpleRequestDatasheet *sheet); @@ -130,8 +130,8 @@ * * Action object is owned by the datasheet since this call. * - * @param sheet The datasheet. - * @param action The action. + * @sheet: The datasheet. + * @action: The action. */ void purple_request_datasheet_add_action(PurpleRequestDatasheet *sheet, @@ -140,9 +140,9 @@ /** * Returns the list of actions in a datasheet. * - * @param sheet The datasheet. + * @sheet: The datasheet. * - * @constreturn The list of actions. + * Returns: (TODO const): The list of actions. */ const GList * purple_request_datasheet_get_actions(PurpleRequestDatasheet *sheet); @@ -158,7 +158,7 @@ /** * Creates new datasheet action. * - * @return The new action. + * Returns: The new action. */ PurpleRequestDatasheetAction * purple_request_datasheet_action_new(void); @@ -166,7 +166,7 @@ /** * Destroys the datasheet action. * - * @param act The action. + * @act: The action. */ void purple_request_datasheet_action_free(PurpleRequestDatasheetAction *act); @@ -174,8 +174,8 @@ /** * Sets the localized label for the action. * - * @param act The action. - * @param label The label. + * @act: The action. + * @label: The label. */ void purple_request_datasheet_action_set_label(PurpleRequestDatasheetAction *act, @@ -184,9 +184,9 @@ /** * Gets the label of action. * - * @param act The action. + * @act: The action. * - * @return The localized label text. + * Returns: The localized label text. */ const gchar* purple_request_datasheet_action_get_label(PurpleRequestDatasheetAction *act); @@ -194,9 +194,9 @@ /** * Sets the callback for the action. * - * @param act The action. - * @param cb The callback function. - * @param user_data The data to be passed to the callback function. + * @act: The action. + * @cb: The callback function. + * @user_data: The data to be passed to the callback function. */ void purple_request_datasheet_action_set_cb(PurpleRequestDatasheetAction *act, @@ -205,8 +205,8 @@ /** * Calls the callback of the action. * - * @param act The action. - * @param rec The user selected record. + * @act: The action. + * @rec: The user selected record. */ void purple_request_datasheet_action_call(PurpleRequestDatasheetAction *act, @@ -218,9 +218,9 @@ * If there is no callback set, default is used: the action is enabled, if any * record is active. * - * @param act The action. - * @param cb The callback function, may be @c NULL. - * @param user_data The data to be passed to the callback function. + * @act: The action. + * @cb: The callback function, may be @c NULL. + * @user_data: The data to be passed to the callback function. */ void purple_request_datasheet_action_set_sens_cb( @@ -230,10 +230,10 @@ /** * Checks, if the action is enabled for the active record. * - * @param act The action. - * @param rec The record. + * @act: The action. + * @rec: The record. * - * @return @c TRUE, if the action is enabled, @c FALSE otherwise. + * Returns: @c TRUE, if the action is enabled, @c FALSE otherwise. */ gboolean purple_request_datasheet_action_is_sensitive(PurpleRequestDatasheetAction *act, @@ -250,9 +250,9 @@ /** * Returns the key of a record. * - * @param rec The record. + * @rec: The record. * - * @return The key. + * Returns: The key. */ gpointer purple_request_datasheet_record_get_key( @@ -261,9 +261,9 @@ /** * Returns the datasheet of a record. * - * @param rec The record. + * @rec: The record. * - * @return The datasheet. + * Returns: The datasheet. */ PurpleRequestDatasheet * purple_request_datasheet_record_get_datasheet( @@ -272,10 +272,10 @@ /** * Looks up for a record in datasheet. * - * @param sheet The datasheet. - * @param key The key. + * @sheet: The datasheet. + * @key: The key. * - * @return The record if found, @c NULL otherwise. + * Returns: The record if found, @c NULL otherwise. */ PurpleRequestDatasheetRecord * purple_request_datasheet_record_find(PurpleRequestDatasheet *sheet, @@ -286,10 +286,10 @@ * * If the specified key already exists in datasheet, old record is returned. * - * @param sheet The datasheet. - * @param key The key. + * @sheet: The datasheet. + * @key: The key. * - * @return The record. + * Returns: The record. */ PurpleRequestDatasheetRecord * purple_request_datasheet_record_add(PurpleRequestDatasheet *sheet, @@ -298,8 +298,8 @@ /** * Removes a record from a datasheet. * - * @param sheet The datasheet. - * @param key The key. + * @sheet: The datasheet. + * @key: The key. */ void purple_request_datasheet_record_remove(PurpleRequestDatasheet *sheet, @@ -308,7 +308,7 @@ /** * Removes all records from a datasheet. * - * @param sheet The datasheet. + * @sheet: The datasheet. */ void purple_request_datasheet_record_remove_all(PurpleRequestDatasheet *sheet); @@ -317,7 +317,7 @@ * Marks all records for removal. Record will be unmarked, when touched with * purple_request_datasheet_record_add. * - * @param sheet The datasheet. + * @sheet: The datasheet. * * @see purple_request_datasheet_record_add. */ @@ -327,7 +327,7 @@ /** * Removes all marked records. * - * @param sheet The datasheet. + * @sheet: The datasheet. * * @see purple_request_datasheet_record_mark_all_for_rem. */ @@ -337,9 +337,9 @@ /** * Sets data for a string column of specified record. * - * @param rec The record. - * @param col_no The column. - * @param data The data. + * @rec: The record. + * @col_no: The column. + * @data: The data. */ void purple_request_datasheet_record_set_string_data( @@ -348,9 +348,9 @@ /** * Sets data for a image column of specified record. * - * @param rec The record. - * @param col_no The column. - * @param data The stock identifier of a image. + * @rec: The record. + * @col_no: The column. + * @data: The stock identifier of a image. */ void purple_request_datasheet_record_set_image_data( @@ -359,10 +359,10 @@ /** * Returns data for a string column of specified record. * - * @param rec The record. - * @param col_no The column. + * @rec: The record. + * @col_no: The column. * - * @return The data. + * Returns: The data. */ const gchar * purple_request_datasheet_record_get_string_data( @@ -371,10 +371,10 @@ /** * Returns data for an image column of specified record. * - * @param rec The record. - * @param col_no The column. + * @rec: The record. + * @col_no: The column. * - * @return The stock id of an image. + * Returns: The stock id of an image. */ const gchar * purple_request_datasheet_record_get_image_data(
--- a/libpurple/request.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/request.h Wed Jan 29 05:28:33 2014 +0530 @@ -205,7 +205,7 @@ * Creates new parameters set for the request, which may or may not be used by * the UI to display the request. * - * @return The new parameters set. + * Returns: The new parameters set. */ PurpleRequestCommonParameters * purple_request_cpar_new(void); @@ -213,7 +213,7 @@ /** * Creates new parameters set initially bound with the #PurpleConnection. * - * @return The new parameters set. + * Returns: The new parameters set. */ PurpleRequestCommonParameters * purple_request_cpar_from_connection(PurpleConnection *gc); @@ -221,7 +221,7 @@ /** * Creates new parameters set initially bound with the #PurpleAccount. * - * @return The new parameters set. + * Returns: The new parameters set. */ PurpleRequestCommonParameters * purple_request_cpar_from_account(PurpleAccount *account); @@ -229,7 +229,7 @@ /** * Creates new parameters set initially bound with the #PurpleConversation. * - * @return The new parameters set. + * Returns: The new parameters set. */ PurpleRequestCommonParameters * purple_request_cpar_from_conversation(PurpleConversation *conv); @@ -237,7 +237,7 @@ /* * Increases the reference count on the parameters set. * - * @param cpar The object to ref. + * @cpar: The object to ref. */ void purple_request_cpar_ref(PurpleRequestCommonParameters *cpar); @@ -247,9 +247,9 @@ * * The object will be destroyed when this reaches 0. * - * @param cpar The parameters set object to unref and possibly destroy. + * @cpar: The parameters set object to unref and possibly destroy. * - * @return The NULL, if object was destroyed, cpar otherwise. + * Returns: The NULL, if object was destroyed, cpar otherwise. */ PurpleRequestCommonParameters * purple_request_cpar_unref(PurpleRequestCommonParameters *cpar); @@ -257,8 +257,8 @@ /** * Sets the #PurpleAccount associated with the request, or @c NULL, if none is. * - * @param cpar The parameters set. - * @param account The #PurpleAccount to associate. + * @cpar: The parameters set. + * @account: The #PurpleAccount to associate. */ void purple_request_cpar_set_account(PurpleRequestCommonParameters *cpar, @@ -267,9 +267,9 @@ /** * Gets the #PurpleAccount associated with the request. * - * @param cpar The parameters set (may be @c NULL). + * @cpar: The parameters set (may be @c NULL). * - * @return The associated #PurpleAccount, or NULL if none is. + * Returns: The associated #PurpleAccount, or NULL if none is. */ PurpleAccount * purple_request_cpar_get_account(PurpleRequestCommonParameters *cpar); @@ -278,8 +278,8 @@ * Sets the #PurpleConversation associated with the request, or @c NULL, if * none is. * - * @param cpar The parameters set. - * @param conv The #PurpleConversation to associate. + * @cpar: The parameters set. + * @conv: The #PurpleConversation to associate. */ void purple_request_cpar_set_conversation(PurpleRequestCommonParameters *cpar, @@ -288,9 +288,9 @@ /** * Gets the #PurpleConversation associated with the request. * - * @param cpar The parameters set (may be @c NULL). + * @cpar: The parameters set (may be @c NULL). * - * @return The associated #PurpleConversation, or NULL if none is. + * Returns: The associated #PurpleConversation, or NULL if none is. */ PurpleConversation * purple_request_cpar_get_conversation(PurpleRequestCommonParameters *cpar); @@ -298,8 +298,8 @@ /** * Sets the icon associated with the request. * - * @param cpar The parameters set. - * @param icon_type The icon type. + * @cpar: The parameters set. + * @icon_type: The icon type. */ void purple_request_cpar_set_icon(PurpleRequestCommonParameters *cpar, @@ -308,9 +308,9 @@ /** * Gets the icon associated with the request. * - * @param cpar The parameters set. + * @cpar: The parameters set. * - * @returns icon_type The icon type. + * Returns:s icon_type The icon type. */ PurpleRequestIconType purple_request_cpar_get_icon(PurpleRequestCommonParameters *cpar); @@ -318,9 +318,9 @@ /** * Sets the custom icon associated with the request. * - * @param cpar The parameters set. - * @param icon_data The icon image contents (@c NULL to reset). - * @param icon_size The icon image size. + * @cpar: The parameters set. + * @icon_data: The icon image contents (@c NULL to reset). + * @icon_size: The icon image size. */ void purple_request_cpar_set_custom_icon(PurpleRequestCommonParameters *cpar, @@ -329,11 +329,11 @@ /** * Gets the custom icon associated with the request. * - * @param cpar The parameters set (may be @c NULL). - * @param icon_size The pointer to variable, where icon size should be stored + * @cpar: The parameters set (may be @c NULL). + * @icon_size: The pointer to variable, where icon size should be stored * (may be @c NULL). * - * @return The icon image contents. + * Returns: The icon image contents. */ gconstpointer purple_request_cpar_get_custom_icon(PurpleRequestCommonParameters *cpar, @@ -342,8 +342,8 @@ /** * Switches the request text to be HTML or not. * - * @param cpar The parameters set. - * @param enabled 1, if the text passed with the request contains HTML, + * @cpar: The parameters set. + * @enabled: 1, if the text passed with the request contains HTML, * 0 otherwise. Don't use any other values, as they may be * redefined in the future. */ @@ -354,9 +354,9 @@ /** * Checks, if the text passed to the request is HTML. * - * @param cpar The parameters set (may be @c NULL). + * @cpar: The parameters set (may be @c NULL). * - * @return @c TRUE, if the text is HTML, @c FALSE otherwise. + * Returns: @c TRUE, if the text is HTML, @c FALSE otherwise. */ gboolean purple_request_cpar_is_html(PurpleRequestCommonParameters *cpar); @@ -364,8 +364,8 @@ /** * Sets dialog display mode to compact or default. * - * @param cpar The parameters set. - * @param compact TRUE for compact, FALSE otherwise. + * @cpar: The parameters set. + * @compact: TRUE for compact, FALSE otherwise. */ void purple_request_cpar_set_compact(PurpleRequestCommonParameters *cpar, @@ -374,9 +374,9 @@ /** * Gets dialog display mode. * - * @param cpar The parameters set (may be @c NULL). + * @cpar: The parameters set (may be @c NULL). * - * @return TRUE for compact, FALSE for default. + * Returns: TRUE for compact, FALSE for default. */ gboolean purple_request_cpar_is_compact(PurpleRequestCommonParameters *cpar); @@ -384,9 +384,9 @@ /** * Sets the callback for the Help button. * - * @param cpar The parameters set. - * @param cb The callback. - * @param user_data The data to be passed to the callback. + * @cpar: The parameters set. + * @cb: The callback. + * @user_data: The data to be passed to the callback. */ void purple_request_cpar_set_help_cb(PurpleRequestCommonParameters *cpar, @@ -395,11 +395,11 @@ /** * Gets the callback for the Help button. * - * @param cpar The parameters set (may be @c NULL). - * @param user_data The pointer to the variable, where user data (to be passed + * @cpar: The parameters set (may be @c NULL). + * @user_data: The pointer to the variable, where user data (to be passed * to callback function) should be stored. * - * @return The callback. + * Returns: The callback. */ PurpleRequestHelpCb purple_request_cpar_get_help_cb(PurpleRequestCommonParameters *cpar, @@ -408,8 +408,8 @@ /** * Sets extra actions for the PurpleRequestFields dialog. * - * @param cpar The parameters set. - * @param ... A list of actions. These are pairs of arguments. The first of + * @cpar: The parameters set. + * @...: A list of actions. These are pairs of arguments. The first of * each pair is the <tt>char *</tt> label that appears on the * button. It should have an underscore before the letter you want * to use as the accelerator key for the button. The second of each @@ -422,9 +422,9 @@ /** * Gets extra actions for the PurpleRequestFields dialog. * - * @param cpar The parameters set (may be @c NULL). + * @cpar: The parameters set (may be @c NULL). * - * @return A list of actions (pairs of arguments, as in setter). + * Returns: A list of actions (pairs of arguments, as in setter). */ GSList * purple_request_cpar_get_extra_actions(PurpleRequestCommonParameters *cpar); @@ -433,8 +433,8 @@ * Sets the same parent window for this dialog, as the parent of specified * Notify API or Request API dialog UI handle. * - * @param cpar The parameters set. - * @param ui_handle The UI handle. + * @cpar: The parameters set. + * @ui_handle: The UI handle. */ void purple_request_cpar_set_parent_from(PurpleRequestCommonParameters *cpar, @@ -443,9 +443,9 @@ /** * Gets the parent "donor" for this dialog. * - * @param cpar The parameters set (may be @c NULL). + * @cpar: The parameters set (may be @c NULL). * - * @return The donors UI handle. + * Returns: The donors UI handle. */ gpointer purple_request_cpar_get_parent_from(PurpleRequestCommonParameters *cpar); @@ -460,22 +460,22 @@ /** * Creates a list of fields to pass to purple_request_fields(). * - * @return A PurpleRequestFields structure. + * Returns: A PurpleRequestFields structure. */ PurpleRequestFields *purple_request_fields_new(void); /** * Destroys a list of fields. * - * @param fields The list of fields to destroy. + * @fields: The list of fields to destroy. */ void purple_request_fields_destroy(PurpleRequestFields *fields); /** * Adds a group of fields to the list. * - * @param fields The fields list. - * @param group The group to add. + * @fields: The fields list. + * @group: The group to add. */ void purple_request_fields_add_group(PurpleRequestFields *fields, PurpleRequestFieldGroup *group); @@ -483,17 +483,17 @@ /** * Returns a list of all groups in a field list. * - * @param fields The fields list. + * @fields: The fields list. * - * @constreturn A list of groups. + * Returns: (TODO const): A list of groups. */ GList *purple_request_fields_get_groups(const PurpleRequestFields *fields); /** * Set tab names for a field list. * - * @param fields The fields list. - * @param tab_names NULL-terminated array of localized tab labels, + * @fields: The fields list. + * @tab_names: NULL-terminated array of localized tab labels, * may be @c NULL. */ void purple_request_fields_set_tab_names(PurpleRequestFields *fields, @@ -502,9 +502,9 @@ /** * Returns tab names of a field list. * - * @param fields The fields list. + * @fields: The fields list. * - * @return NULL-terminated array of localized tab labels, or NULL if tabs + * Returns: NULL-terminated array of localized tab labels, or NULL if tabs * are disabled. */ const gchar ** @@ -513,10 +513,10 @@ /** * Returns whether or not the field with the specified ID exists. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return TRUE if the field exists, or FALSE. + * Returns: TRUE if the field exists, or FALSE. */ gboolean purple_request_fields_exists(const PurpleRequestFields *fields, const char *id); @@ -524,9 +524,9 @@ /** * Returns a list of all required fields. * - * @param fields The fields list. + * @fields: The fields list. * - * @constreturn The list of required fields. + * Returns: (TODO const): The list of required fields. */ const GList *purple_request_fields_get_required( const PurpleRequestFields *fields); @@ -534,9 +534,9 @@ /** * Returns a list of all validated fields. * - * @param fields The fields list. + * @fields: The fields list. * - * @constreturn The list of validated fields. + * Returns: (TODO const): The list of validated fields. */ const GList *purple_request_fields_get_validatable( const PurpleRequestFields *fields); @@ -544,9 +544,9 @@ /** * Returns a list of all fields with sensitivity callback added. * - * @param fields The fields list. + * @fields: The fields list. * - * @constreturn The list of fields with automatic sensitivity callback. + * Returns: (TODO const): The list of fields with automatic sensitivity callback. */ const GList * purple_request_fields_get_autosensitive(const PurpleRequestFields *fields); @@ -554,10 +554,10 @@ /** * Returns whether or not a field with the specified ID is required. * - * @param fields The fields list. - * @param id The field ID. + * @fields: The fields list. + * @id: The field ID. * - * @return TRUE if the specified field is required, or FALSE. + * Returns: TRUE if the specified field is required, or FALSE. */ gboolean purple_request_fields_is_field_required(const PurpleRequestFields *fields, const char *id); @@ -565,9 +565,9 @@ /** * Returns whether or not all required fields have values. * - * @param fields The fields list. + * @fields: The fields list. * - * @return TRUE if all required fields have values, or FALSE. + * Returns: TRUE if all required fields have values, or FALSE. */ gboolean purple_request_fields_all_required_filled( const PurpleRequestFields *fields); @@ -575,19 +575,19 @@ /** * Returns whether or not all fields are valid. * - * @param fields The fields list. + * @fields: The fields list. * - * @return TRUE if all fields are valid, or FALSE. + * Returns: TRUE if all fields are valid, or FALSE. */ gboolean purple_request_fields_all_valid(const PurpleRequestFields *fields); /** * Return the field with the specified ID. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return The field, if found. + * Returns: The field, if found. */ PurpleRequestField *purple_request_fields_get_field( const PurpleRequestFields *fields, const char *id); @@ -595,10 +595,10 @@ /** * Returns the string value of a field with the specified ID. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return The string value, if found, or @c NULL otherwise. + * Returns: The string value, if found, or @c NULL otherwise. */ const char *purple_request_fields_get_string(const PurpleRequestFields *fields, const char *id); @@ -606,10 +606,10 @@ /** * Returns the integer value of a field with the specified ID. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return The integer value, if found, or 0 otherwise. + * Returns: The integer value, if found, or 0 otherwise. */ int purple_request_fields_get_integer(const PurpleRequestFields *fields, const char *id); @@ -617,10 +617,10 @@ /** * Returns the boolean value of a field with the specified ID. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return The boolean value, if found, or @c FALSE otherwise. + * Returns: The boolean value, if found, or @c FALSE otherwise. */ gboolean purple_request_fields_get_bool(const PurpleRequestFields *fields, const char *id); @@ -628,10 +628,10 @@ /** * Returns the choice index of a field with the specified ID. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return The choice value, if found, or NULL otherwise. + * Returns: The choice value, if found, or NULL otherwise. */ gpointer purple_request_fields_get_choice(const PurpleRequestFields *fields, @@ -640,10 +640,10 @@ /** * Returns the account of a field with the specified ID. * - * @param fields The fields list. - * @param id The ID of the field. + * @fields: The fields list. + * @id: The ID of the field. * - * @return The account value, if found, or NULL otherwise. + * Returns: The account value, if found, or NULL otherwise. */ PurpleAccount *purple_request_fields_get_account(const PurpleRequestFields *fields, const char *id); @@ -651,9 +651,9 @@ /** * Returns the UI data associated with this object. * - * @param fields The fields list. + * @fields: The fields list. * - * @return The UI data associated with this object. This is a + * Returns: The UI data associated with this object. This is a * convenience field provided to the UIs--it is not * used by the libpurple core. */ @@ -662,8 +662,8 @@ /** * Set the UI data associated with this object. * - * @param fields The fields list. - * @param ui_data A pointer to associate with this object. + * @fields: The fields list. + * @ui_data: A pointer to associate with this object. */ void purple_request_fields_set_ui_data(PurpleRequestFields *fields, gpointer ui_data); @@ -677,17 +677,17 @@ /** * Creates a fields group with an optional title. * - * @param title The optional title to give the group. + * @title: The optional title to give the group. * - * @return A new fields group + * Returns: A new fields group */ PurpleRequestFieldGroup *purple_request_field_group_new(const char *title); /** * Sets tab number for a group. * - * @param group The group. - * @param tab_no The tab number. + * @group: The group. + * @tab_no: The tab number. * * @see purple_request_fields_set_tab_names */ @@ -697,9 +697,9 @@ /** * Returns tab number of a group. * - * @param group The group. + * @group: The group. * - * @return Tab number. + * Returns: Tab number. * * @see purple_request_fields_get_tab_names */ @@ -708,15 +708,15 @@ /** * Destroys a fields group. * - * @param group The group to destroy. + * @group: The group to destroy. */ void purple_request_field_group_destroy(PurpleRequestFieldGroup *group); /** * Adds a field to the group. * - * @param group The group to add the field to. - * @param field The field to add to the group. + * @group: The group to add the field to. + * @field: The field to add to the group. */ void purple_request_field_group_add_field(PurpleRequestFieldGroup *group, PurpleRequestField *field); @@ -724,9 +724,9 @@ /** * Returns the title of a fields group. * - * @param group The group. + * @group: The group. * - * @return The title, if set. + * Returns: The title, if set. */ const char *purple_request_field_group_get_title( const PurpleRequestFieldGroup *group); @@ -734,9 +734,9 @@ /** * Returns a list of all fields in a group. * - * @param group The group. + * @group: The group. * - * @constreturn The list of fields in the group. + * Returns: (TODO const): The list of fields in the group. */ GList *purple_request_field_group_get_fields( const PurpleRequestFieldGroup *group); @@ -744,9 +744,9 @@ /** * Returns a list of all fields in a group. * - * @param group The group. + * @group: The group. * - * @constreturn The list of fields in the group. + * Returns: (TODO const): The list of fields in the group. */ PurpleRequestFields *purple_request_field_group_get_fields_list( const PurpleRequestFieldGroup *group); @@ -761,11 +761,11 @@ /** * Creates a field of the specified type. * - * @param id The field ID. - * @param text The text label of the field. - * @param type The type of field. + * @id: The field ID. + * @text: The text label of the field. + * @type: The type of field. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_new(const char *id, const char *text, PurpleRequestFieldType type); @@ -773,23 +773,23 @@ /** * Destroys a field. * - * @param field The field to destroy. + * @field: The field to destroy. */ void purple_request_field_destroy(PurpleRequestField *field); /** * Sets the label text of a field. * - * @param field The field. - * @param label The text label. + * @field: The field. + * @label: The text label. */ void purple_request_field_set_label(PurpleRequestField *field, const char *label); /** * Sets whether or not a field is visible. * - * @param field The field. - * @param visible TRUE if visible, or FALSE if not. + * @field: The field. + * @visible: TRUE if visible, or FALSE if not. */ void purple_request_field_set_visible(PurpleRequestField *field, gboolean visible); @@ -799,8 +799,8 @@ * This is optionally used by the UIs to provide such features as * auto-completion for type hints like "account" and "screenname". * - * @param field The field. - * @param type_hint The type hint. + * @field: The field. + * @type_hint: The type hint. */ void purple_request_field_set_type_hint(PurpleRequestField *field, const char *type_hint); @@ -811,8 +811,8 @@ * This is optionally used by the UIs to provide a tooltip for * the field. * - * @param field The field. - * @param tooltip The tooltip text. + * @field: The field. + * @tooltip: The tooltip text. */ void purple_request_field_set_tooltip(PurpleRequestField *field, const char *tooltip); @@ -820,8 +820,8 @@ /** * Sets whether or not a field is required. * - * @param field The field. - * @param required TRUE if required, or FALSE. + * @field: The field. + * @required: TRUE if required, or FALSE. */ void purple_request_field_set_required(PurpleRequestField *field, gboolean required); @@ -829,90 +829,90 @@ /** * Returns the type of a field. * - * @param field The field. + * @field: The field. * - * @return The field's type. + * Returns: The field's type. */ PurpleRequestFieldType purple_request_field_get_type(const PurpleRequestField *field); /** * Returns the group for the field. * - * @param field The field. + * @field: The field. * - * @return The UI data. + * Returns: The UI data. */ PurpleRequestFieldGroup *purple_request_field_get_group(const PurpleRequestField *field); /** * Returns the ID of a field. * - * @param field The field. + * @field: The field. * - * @return The ID + * Returns: The ID */ const char *purple_request_field_get_id(const PurpleRequestField *field); /** * Returns the label text of a field. * - * @param field The field. + * @field: The field. * - * @return The label text. + * Returns: The label text. */ const char *purple_request_field_get_label(const PurpleRequestField *field); /** * Returns whether or not a field is visible. * - * @param field The field. + * @field: The field. * - * @return TRUE if the field is visible. FALSE otherwise. + * Returns: TRUE if the field is visible. FALSE otherwise. */ gboolean purple_request_field_is_visible(const PurpleRequestField *field); /** * Returns the field's type hint. * - * @param field The field. + * @field: The field. * - * @return The field's type hint. + * Returns: The field's type hint. */ const char *purple_request_field_get_type_hint(const PurpleRequestField *field); /** * Returns the field's tooltip. * - * @param field The field. + * @field: The field. * - * @return The field's tooltip. + * Returns: The field's tooltip. */ const char *purple_request_field_get_tooltip(const PurpleRequestField *field); /** * Returns whether or not a field is required. * - * @param field The field. + * @field: The field. * - * @return TRUE if the field is required, or FALSE. + * Returns: TRUE if the field is required, or FALSE. */ gboolean purple_request_field_is_required(const PurpleRequestField *field); /** * Checks, if specified field has value. * - * @param field The field. + * @field: The field. * - * @return TRUE if the field has value, or FALSE. + * Returns: TRUE if the field has value, or FALSE. */ gboolean purple_request_field_is_filled(const PurpleRequestField *field); /** * Sets validator for a single field. * - * @param field The field. - * @param validator The validator callback, NULL to disable validation. - * @param user_data The data to pass to the callback. + * @field: The field. + * @validator: The validator callback, NULL to disable validation. + * @user_data: The data to pass to the callback. */ void purple_request_field_set_validator(PurpleRequestField *field, PurpleRequestFieldValidator validator, void *user_data); @@ -920,9 +920,9 @@ /** * Returns whether or not field has validator set. * - * @param field The field. + * @field: The field. * - * @return TRUE if the field has validator, or FALSE. + * Returns: TRUE if the field has validator, or FALSE. */ gboolean purple_request_field_is_validatable(PurpleRequestField *field); @@ -935,19 +935,19 @@ * * Note: empty, not required fields are valid. * - * @param field The field. - * @param errmsg If non-NULL, the memory area, where the pointer to validation + * @field: The field. + * @errmsg: If non-NULL, the memory area, where the pointer to validation * failure message will be set. * - * @return TRUE, if the field is valid, FALSE otherwise. + * Returns: TRUE, if the field is valid, FALSE otherwise. */ gboolean purple_request_field_is_valid(PurpleRequestField *field, gchar **errmsg); /** * Sets field editable. * - * @param field The field. - * @param sensitive TRUE if the field should be sensitive for user input. + * @field: The field. + * @sensitive: TRUE if the field should be sensitive for user input. */ void purple_request_field_set_sensitive(PurpleRequestField *field, gboolean sensitive); @@ -955,17 +955,17 @@ /** * Checks, if field is editable. * - * @param field The field. + * @field: The field. * - * @return TRUE, if the field is sensitive for user input. + * Returns: TRUE, if the field is sensitive for user input. */ gboolean purple_request_field_is_sensitive(PurpleRequestField *field); /** * Sets the callback, used to determine if the field should be editable. * - * @param field The field. - * @param cb The callback. + * @field: The field. + * @cb: The callback. */ void purple_request_field_set_sensitivity_cb(PurpleRequestField *field, PurpleRequestFieldSensitivityCb cb); @@ -973,19 +973,19 @@ /** * Returns the ui_data for a field. * - * @param field The field. + * @field: The field. * - * @return The UI data. + * Returns: The UI data. */ gpointer purple_request_field_get_ui_data(const PurpleRequestField *field); /** * Sets the ui_data for a field. * - * @param field The field. - * @param ui_data The UI data. + * @field: The field. + * @ui_data: The UI data. * - * @return The UI data. + * Returns: The UI data. */ void purple_request_field_set_ui_data(PurpleRequestField *field, gpointer ui_data); @@ -1000,12 +1000,12 @@ /** * Creates a string request field. * - * @param id The field ID. - * @param text The text label of the field. - * @param default_value The optional default value. - * @param multiline Whether or not this should be a multiline string. + * @id: The field ID. + * @text: The text label of the field. + * @default_value: The optional default value. + * @multiline: Whether or not this should be a multiline string. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_string_new(const char *id, const char *text, @@ -1015,8 +1015,8 @@ /** * Sets the default value in a string field. * - * @param field The field. - * @param default_value The default value. + * @field: The field. + * @default_value: The default value. */ void purple_request_field_string_set_default_value(PurpleRequestField *field, const char *default_value); @@ -1024,8 +1024,8 @@ /** * Sets the value in a string field. * - * @param field The field. - * @param value The value. + * @field: The field. + * @value: The value. */ void purple_request_field_string_set_value(PurpleRequestField *field, const char *value); @@ -1034,8 +1034,8 @@ * Sets whether or not a string field is masked * (commonly used for password fields). * - * @param field The field. - * @param masked The masked value. + * @field: The field. + * @masked: The masked value. */ void purple_request_field_string_set_masked(PurpleRequestField *field, gboolean masked); @@ -1043,9 +1043,9 @@ /** * Returns the default value in a string field. * - * @param field The field. + * @field: The field. * - * @return The default value. + * Returns: The default value. */ const char *purple_request_field_string_get_default_value( const PurpleRequestField *field); @@ -1053,27 +1053,27 @@ /** * Returns the user-entered value in a string field. * - * @param field The field. + * @field: The field. * - * @return The value. + * Returns: The value. */ const char *purple_request_field_string_get_value(const PurpleRequestField *field); /** * Returns whether or not a string field is multi-line. * - * @param field The field. + * @field: The field. * - * @return @c TRUE if the field is mulit-line, or @c FALSE otherwise. + * Returns: @c TRUE if the field is mulit-line, or @c FALSE otherwise. */ gboolean purple_request_field_string_is_multiline(const PurpleRequestField *field); /** * Returns whether or not a string field is masked. * - * @param field The field. + * @field: The field. * - * @return @c TRUE if the field is masked, or @c FALSE otherwise. + * Returns: @c TRUE if the field is masked, or @c FALSE otherwise. */ gboolean purple_request_field_string_is_masked(const PurpleRequestField *field); @@ -1087,13 +1087,13 @@ /** * Creates an integer field. * - * @param id The field ID. - * @param text The text label of the field. - * @param default_value The default value. - * @param lower_bound The lower bound. - * @param upper_bound The upper bound. + * @id: The field ID. + * @text: The text label of the field. + * @default_value: The default value. + * @lower_bound: The lower bound. + * @upper_bound: The upper bound. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_int_new(const char *id, const char *text, int default_value, int lower_bound, int upper_bound); @@ -1101,8 +1101,8 @@ /** * Sets the default value in an integer field. * - * @param field The field. - * @param default_value The default value. + * @field: The field. + * @default_value: The default value. */ void purple_request_field_int_set_default_value(PurpleRequestField *field, int default_value); @@ -1110,60 +1110,60 @@ /** * Sets the lower bound in an integer field. * - * @param field The field. - * @param lower_bound The lower bound. + * @field: The field. + * @lower_bound: The lower bound. */ void purple_request_field_int_set_lower_bound(PurpleRequestField *field, int lower_bound); /** * Sets the upper bound in an integer field. * - * @param field The field. - * @param upper_bound The upper bound. + * @field: The field. + * @upper_bound: The upper bound. */ void purple_request_field_int_set_upper_bound(PurpleRequestField *field, int lower_bound); /** * Sets the value in an integer field. * - * @param field The field. - * @param value The value. + * @field: The field. + * @value: The value. */ void purple_request_field_int_set_value(PurpleRequestField *field, int value); /** * Returns the default value in an integer field. * - * @param field The field. + * @field: The field. * - * @return The default value. + * Returns: The default value. */ int purple_request_field_int_get_default_value(const PurpleRequestField *field); /** * Returns the lower bound in an integer field. * - * @param field The field. + * @field: The field. * - * @return The lower bound. + * Returns: The lower bound. */ int purple_request_field_int_get_lower_bound(const PurpleRequestField *field); /** * Returns the upper bound in an integer field. * - * @param field The field. + * @field: The field. * - * @return The upper bound. + * Returns: The upper bound. */ int purple_request_field_int_get_upper_bound(const PurpleRequestField *field); /** * Returns the user-entered value in an integer field. * - * @param field The field. + * @field: The field. * - * @return The value. + * Returns: The value. */ int purple_request_field_int_get_value(const PurpleRequestField *field); @@ -1179,11 +1179,11 @@ * * This is often represented as a checkbox. * - * @param id The field ID. - * @param text The text label of the field. - * @param default_value The default value. + * @id: The field ID. + * @text: The text label of the field. + * @default_value: The default value. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_bool_new(const char *id, const char *text, @@ -1192,8 +1192,8 @@ /** * Sets the default value in an boolean field. * - * @param field The field. - * @param default_value The default value. + * @field: The field. + * @default_value: The default value. */ void purple_request_field_bool_set_default_value(PurpleRequestField *field, gboolean default_value); @@ -1201,8 +1201,8 @@ /** * Sets the value in an boolean field. * - * @param field The field. - * @param value The value. + * @field: The field. + * @value: The value. */ void purple_request_field_bool_set_value(PurpleRequestField *field, gboolean value); @@ -1210,9 +1210,9 @@ /** * Returns the default value in an boolean field. * - * @param field The field. + * @field: The field. * - * @return The default value. + * Returns: The default value. */ gboolean purple_request_field_bool_get_default_value( const PurpleRequestField *field); @@ -1220,9 +1220,9 @@ /** * Returns the user-entered value in an boolean field. * - * @param field The field. + * @field: The field. * - * @return The value. + * Returns: The value. */ gboolean purple_request_field_bool_get_value(const PurpleRequestField *field); @@ -1238,11 +1238,11 @@ * * This is often represented as a group of radio buttons. * - * @param id The field ID. - * @param text The optional label of the field. - * @param default_value The default choice. + * @id: The field ID. + * @text: The optional label of the field. + * @default_value: The default choice. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField * purple_request_field_choice_new(const char *id, const char *text, @@ -1251,9 +1251,9 @@ /** * Adds a choice to a multiple choice field. * - * @param field The choice field. - * @param label The choice label. - * @param data The choice value. + * @field: The choice field. + * @label: The choice label. + * @data: The choice value. */ void purple_request_field_choice_add(PurpleRequestField *field, const char *label, @@ -1262,8 +1262,8 @@ /** * Sets the default value in an choice field. * - * @param field The field. - * @param default_value The default value. + * @field: The field. + * @default_value: The default value. */ void purple_request_field_choice_set_default_value(PurpleRequestField *field, @@ -1272,8 +1272,8 @@ /** * Sets the value in an choice field. * - * @param field The field. - * @param value The value. + * @field: The field. + * @value: The value. */ void purple_request_field_choice_set_value(PurpleRequestField *field, @@ -1282,9 +1282,9 @@ /** * Returns the default value in an choice field. * - * @param field The field. + * @field: The field. * - * @return The default value. + * Returns: The default value. */ gpointer purple_request_field_choice_get_default_value(const PurpleRequestField *field); @@ -1292,9 +1292,9 @@ /** * Returns the user-entered value in an choice field. * - * @param field The field. + * @field: The field. * - * @return The value. + * Returns: The value. */ gpointer purple_request_field_choice_get_value(const PurpleRequestField *field); @@ -1302,9 +1302,9 @@ /** * Returns a list of elements in a choice field. * - * @param field The field. + * @field: The field. * - * @constreturn The list of pairs <label, value>. + * Returns: (TODO const): The list of pairs <label, value>. */ GList * purple_request_field_choice_get_elements(const PurpleRequestField *field); @@ -1312,8 +1312,8 @@ /** * Sets the destructor for field values. * - * @param field The field. - * @param destroy The destroy function. + * @field: The field. + * @destroy: The destroy function. */ void purple_request_field_choice_set_data_destructor(PurpleRequestField *field, @@ -1329,18 +1329,18 @@ /** * Creates a multiple list item field. * - * @param id The field ID. - * @param text The optional label of the field. + * @id: The field ID. + * @text: The optional label of the field. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_list_new(const char *id, const char *text); /** * Sets whether or not a list field allows multiple selection. * - * @param field The list field. - * @param multi_select TRUE if multiple selection is enabled, + * @field: The list field. + * @multi_select: TRUE if multiple selection is enabled, * or FALSE otherwise. */ void purple_request_field_list_set_multi_select(PurpleRequestField *field, @@ -1349,9 +1349,9 @@ /** * Returns whether or not a list field allows multiple selection. * - * @param field The list field. + * @field: The list field. * - * @return TRUE if multiple selection is enabled, or FALSE otherwise. + * Returns: TRUE if multiple selection is enabled, or FALSE otherwise. */ gboolean purple_request_field_list_get_multi_select( const PurpleRequestField *field); @@ -1359,10 +1359,10 @@ /** * Returns the data for a particular item. * - * @param field The list field. - * @param text The item text. + * @field: The list field. + * @text: The item text. * - * @return The data associated with the item. + * Returns: The data associated with the item. */ void *purple_request_field_list_get_data(const PurpleRequestField *field, const char *text); @@ -1370,10 +1370,10 @@ /** * Adds an item to a list field. * - * @param field The list field. - * @param item The list item. - * @param icon_path The path to icon file, or @c NULL for no icon. - * @param data The associated data. + * @field: The list field. + * @item: The list item. + * @icon_path: The path to icon file, or @c NULL for no icon. + * @data: The associated data. */ void purple_request_field_list_add_icon(PurpleRequestField *field, const char *item, const char* icon_path, void* data); @@ -1381,8 +1381,8 @@ /** * Adds a selected item to the list field. * - * @param field The field. - * @param item The item to add. + * @field: The field. + * @item: The item to add. */ void purple_request_field_list_add_selected(PurpleRequestField *field, const char *item); @@ -1390,15 +1390,15 @@ /** * Clears the list of selected items in a list field. * - * @param field The field. + * @field: The field. */ void purple_request_field_list_clear_selected(PurpleRequestField *field); /** * Sets a list of selected items in a list field. * - * @param field The field. - * @param items The list of selected items, which is not modified or freed. + * @field: The field. + * @items: The list of selected items, which is not modified or freed. */ void purple_request_field_list_set_selected(PurpleRequestField *field, GList *items); @@ -1406,10 +1406,10 @@ /** * Returns whether or not a particular item is selected in a list field. * - * @param field The field. - * @param item The item. + * @field: The field. + * @item: The item. * - * @return TRUE if the item is selected. FALSE otherwise. + * Returns: TRUE if the item is selected. FALSE otherwise. */ gboolean purple_request_field_list_is_selected(const PurpleRequestField *field, const char *item); @@ -1420,9 +1420,9 @@ * To retrieve the data for each item, use * purple_request_field_list_get_data(). * - * @param field The field. + * @field: The field. * - * @constreturn The list of selected items. + * Returns: (TODO const): The list of selected items. */ GList *purple_request_field_list_get_selected( const PurpleRequestField *field); @@ -1430,9 +1430,9 @@ /** * Returns a list of items in a list field. * - * @param field The field. + * @field: The field. * - * @constreturn The list of items. + * Returns: (TODO const): The list of items. */ GList *purple_request_field_list_get_items(const PurpleRequestField *field); @@ -1441,9 +1441,9 @@ * * The icons will correspond with the items, in order. * - * @param field The field. + * @field: The field. * - * @constreturn The list of icons or @c NULL (i.e. the empty GList) if no + * Returns: (TODO const): The list of icons or @c NULL (i.e. the empty GList) if no * items have icons. */ GList *purple_request_field_list_get_icons(const PurpleRequestField *field); @@ -1458,10 +1458,10 @@ /** * Creates a label field. * - * @param id The field ID. - * @param text The label of the field. + * @id: The field ID. + * @text: The label of the field. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_label_new(const char *id, const char *text); @@ -1476,12 +1476,12 @@ /** * Creates an image field. * - * @param id The field ID. - * @param text The label of the field. - * @param buf The image data. - * @param size The size of the data in @a buffer. + * @id: The field ID. + * @text: The label of the field. + * @buf: The image data. + * @size: The size of the data in @a buffer. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_image_new(const char *id, const char *text, const char *buf, gsize size); @@ -1489,7 +1489,7 @@ /** * Sets the scale factors of an image field. * - * @param field The image field. + * @field: The image field. * @param x The x scale factor. * @param y The y scale factor. */ @@ -1498,36 +1498,36 @@ /** * Returns pointer to the image. * - * @param field The image field. + * @field: The image field. * - * @return Pointer to the image. + * Returns: Pointer to the image. */ const char *purple_request_field_image_get_buffer(PurpleRequestField *field); /** * Returns size (in bytes) of the image. * - * @param field The image field. + * @field: The image field. * - * @return Size of the image. + * Returns: Size of the image. */ gsize purple_request_field_image_get_size(PurpleRequestField *field); /** * Returns X scale coefficient of the image. * - * @param field The image field. + * @field: The image field. * - * @return X scale coefficient of the image. + * Returns: X scale coefficient of the image. */ unsigned int purple_request_field_image_get_scale_x(PurpleRequestField *field); /** * Returns Y scale coefficient of the image. * - * @param field The image field. + * @field: The image field. * - * @return Y scale coefficient of the image. + * Returns: Y scale coefficient of the image. */ unsigned int purple_request_field_image_get_scale_y(PurpleRequestField *field); @@ -1543,11 +1543,11 @@ * * By default, this field will not show offline accounts. * - * @param id The field ID. - * @param text The text label of the field. - * @param account The optional default account. + * @id: The field ID. + * @text: The text label of the field. + * @account: The optional default account. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_account_new(const char *id, const char *text, @@ -1556,8 +1556,8 @@ /** * Sets the default account on an account field. * - * @param field The account field. - * @param default_value The default account. + * @field: The account field. + * @default_value: The default account. */ void purple_request_field_account_set_default_value(PurpleRequestField *field, PurpleAccount *default_value); @@ -1565,8 +1565,8 @@ /** * Sets the account in an account field. * - * @param field The account field. - * @param value The account. + * @field: The account field. + * @value: The account. */ void purple_request_field_account_set_value(PurpleRequestField *field, PurpleAccount *value); @@ -1577,8 +1577,8 @@ * If TRUE, all accounts, online or offline, will be shown. If FALSE, * only online accounts will be shown. * - * @param field The account field. - * @param show_all Whether or not to show all accounts. + * @field: The account field. + * @show_all: Whether or not to show all accounts. */ void purple_request_field_account_set_show_all(PurpleRequestField *field, gboolean show_all); @@ -1589,8 +1589,8 @@ * This function will determine which accounts get displayed and which * don't. * - * @param field The account field. - * @param filter_func The account filter function. + * @field: The account field. + * @filter_func: The account filter function. */ void purple_request_field_account_set_filter(PurpleRequestField *field, PurpleFilterAccountFunc filter_func); @@ -1598,9 +1598,9 @@ /** * Returns the default account in an account field. * - * @param field The field. + * @field: The field. * - * @return The default account. + * Returns: The default account. */ PurpleAccount *purple_request_field_account_get_default_value( const PurpleRequestField *field); @@ -1608,9 +1608,9 @@ /** * Returns the user-entered account in an account field. * - * @param field The field. + * @field: The field. * - * @return The user-entered account. + * Returns: The user-entered account. */ PurpleAccount *purple_request_field_account_get_value( const PurpleRequestField *field); @@ -1621,8 +1621,8 @@ * If TRUE, all accounts, online or offline, will be shown. If FALSE, * only online accounts will be shown. * - * @param field The account field. - * @return Whether or not to show all accounts. + * @field: The account field. + * Returns: Whether or not to show all accounts. */ gboolean purple_request_field_account_get_show_all( const PurpleRequestField *field); @@ -1633,9 +1633,9 @@ * This function will determine which accounts get displayed and which * don't. * - * @param field The account field. + * @field: The account field. * - * @return The account filter function. + * Returns: The account filter function. */ PurpleFilterAccountFunc purple_request_field_account_get_filter( const PurpleRequestField *field); @@ -1650,11 +1650,11 @@ /** * Creates a certificate field. * - * @param id The field ID. - * @param text The label of the field. - * @param cert The certificate of the field. + * @id: The field ID. + * @text: The label of the field. + * @cert: The certificate of the field. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_certificate_new(const char *id, const char *text, @@ -1663,9 +1663,9 @@ /** * Returns the certificate in a certificate field. * - * @param field The field. + * @field: The field. * - * @return The certificate. + * Returns: The certificate. */ PurpleCertificate *purple_request_field_certificate_get_value( const PurpleRequestField *field); @@ -1680,11 +1680,11 @@ /** * Creates a datasheet item field. * - * @param id The field ID. - * @param text The label of the field, may be @c NULL. - * @param sheet The datasheet. + * @id: The field ID. + * @text: The label of the field, may be @c NULL. + * @sheet: The datasheet. * - * @return The new field. + * Returns: The new field. */ PurpleRequestField *purple_request_field_datasheet_new(const char *id, const gchar *text, PurpleRequestDatasheet *sheet); @@ -1692,9 +1692,9 @@ /** * Returns a datasheet for a field. * - * @param field The field. + * @field: The field. * - * @constreturn The datasheet object. + * Returns: (TODO const): The datasheet object. */ PurpleRequestDatasheet *purple_request_field_datasheet_get_sheet( PurpleRequestField *field); @@ -1711,11 +1711,11 @@ * * @see purple_request_field_set_validator * - * @param field The field. - * @param errmsg (Optional) destination for error message. - * @param user_data Ignored. + * @field: The field. + * @errmsg: (Optional) destination for error message. + * @user_data: Ignored. * - * @return TRUE, if field contains valid email address. + * Returns: TRUE, if field contains valid email address. */ gboolean purple_request_field_email_validator(PurpleRequestField *field, gchar **errmsg, void *user_data); @@ -1725,11 +1725,11 @@ * * @see purple_request_field_set_validator * - * @param field The field. - * @param errmsg (Optional) destination for error message. - * @param user_data (Optional) allowed character list (NULL-terminated string). + * @field: The field. + * @errmsg: (Optional) destination for error message. + * @user_data: (Optional) allowed character list (NULL-terminated string). * - * @return TRUE, if field contains only alphanumeric characters. + * Returns: TRUE, if field contains only alphanumeric characters. */ gboolean purple_request_field_alphanumeric_validator(PurpleRequestField *field, gchar **errmsg, void *allowed_characters); @@ -1744,7 +1744,7 @@ /** * Prompts the user for text input. * - * @param handle The plugin or connection handle. For some + * @handle: The plugin or connection handle. For some * things this is <em>extremely</em> important. The * handle is used to programmatically close the request * dialog when it is no longer needed. For protocols this @@ -1757,31 +1757,31 @@ * <em>not</em> closed it is <strong>very</strong> * likely to cause a crash whenever the callback * handler functions are triggered. - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param primary The main point of the message, or @c NULL if you're + * @primary: The main point of the message, or @c NULL if you're * feeling enigmatic. - * @param secondary Secondary information, or @c NULL if there is none. - * @param default_value The default value. - * @param multiline @c TRUE if the inputted text can span multiple lines. - * @param masked @c TRUE if the inputted text should be masked in some + * @secondary: Secondary information, or @c NULL if there is none. + * @default_value: The default value. + * @multiline: @c TRUE if the inputted text can span multiple lines. + * @masked: @c TRUE if the inputted text should be masked in some * way (such as by displaying characters as stars). This * might be because the input is some kind of password. - * @param hint Optionally suggest how the input box should appear. + * @hint: Optionally suggest how the input box should appear. * Use "html", for example, to allow the user to enter * HTML. - * @param ok_text The text for the @c OK button, which may not be @c NULL. - * @param ok_cb The callback for the @c OK button, which may not be @c + * @ok_text: The text for the @c OK button, which may not be @c NULL. + * @ok_cb: The callback for the @c OK button, which may not be @c * NULL. - * @param cancel_text The text for the @c Cancel button, which may not be @c + * @cancel_text: The text for the @c Cancel button, which may not be @c * NULL. - * @param cancel_cb The callback for the @c Cancel button, which may be + * @cancel_cb: The callback for the @c Cancel button, which may be * @c NULL. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_request_input(void *handle, const char *title, const char *primary, const char *secondary, const char *default_value, gboolean multiline, @@ -1794,31 +1794,31 @@ /** * Prompts the user for multiple-choice input. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param primary The main point of the message, or @c NULL if you're + * @primary: The main point of the message, or @c NULL if you're * feeling enigmatic. - * @param secondary Secondary information, or @c NULL if there is none. - * @param default_value The default choice; this should be one of the values + * @secondary: Secondary information, or @c NULL if there is none. + * @default_value: The default choice; this should be one of the values * listed in the varargs. - * @param ok_text The text for the @c OK button, which may not be @c NULL. - * @param ok_cb The callback for the @c OK button, which may not be @c + * @ok_text: The text for the @c OK button, which may not be @c NULL. + * @ok_cb: The callback for the @c OK button, which may not be @c * NULL. - * @param cancel_text The text for the @c Cancel button, which may not be @c + * @cancel_text: The text for the @c Cancel button, which may not be @c * NULL. - * @param cancel_cb The callback for the @c Cancel button, or @c NULL to + * @cancel_cb: The callback for the @c Cancel button, or @c NULL to * do nothing. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. - * @param ... The choices, which should be pairs of <tt>char *</tt> + * @user_data: The data to pass to the callback. + * @...: The choices, which should be pairs of <tt>char *</tt> * descriptions and <tt>int</tt> values, terminated with a * @c NULL parameter. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_request_choice(void *handle, const char *title, const char *primary, const char *secondary, gpointer default_value, @@ -1842,23 +1842,23 @@ * * This is often represented as a dialog with a button for each action. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param primary The main point of the message, or @c NULL if you're + * @primary: The main point of the message, or @c NULL if you're * feeling enigmatic. - * @param secondary Secondary information, or @c NULL if there is none. - * @param default_action The default action, zero-indexed; if the third action + * @secondary: Secondary information, or @c NULL if there is none. + * @default_action: The default action, zero-indexed; if the third action * supplied should be the default, supply <tt>2</tt>. * The should be the action that users are most likely * to select. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. - * @param action_count The number of actions. - * @param ... A list of actions. These are pairs of + * @user_data: The data to pass to the callback. + * @action_count: The number of actions. + * @...: A list of actions. These are pairs of * arguments. The first of each pair is the * <tt>char *</tt> label that appears on the button. It * should have an underscore before the letter you want @@ -1866,7 +1866,7 @@ * second of each pair is the #PurpleRequestActionCb * function to use when the button is clicked. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void * purple_request_action(void *handle, const char *title, const char *primary, @@ -1886,23 +1886,23 @@ /** * Displays a "please wait" dialog. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * default title. - * @param primary The main point of the message, or @c NULL if you're + * @primary: The main point of the message, or @c NULL if you're * feeling enigmatic. - * @param secondary Secondary information, or @c NULL if there is none. - * @param with_progress @c TRUE, if we want to display progress bar, @c FALSE + * @secondary: Secondary information, or @c NULL if there is none. + * @with_progress: @c TRUE, if we want to display progress bar, @c FALSE * otherwise - * @param cancel_cb The callback for the @c Cancel button, which may be + * @cancel_cb: The callback for the @c Cancel button, which may be * @c NULL. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void * purple_request_wait(void *handle, const char *title, const char *primary, @@ -1914,7 +1914,7 @@ * Notifies the "please wait" dialog that some progress has been made, but you * don't know how much. * - * @param ui_handle The request UI handle. + * @ui_handle: The request UI handle. */ void purple_request_wait_pulse(void *ui_handle); @@ -1922,8 +1922,8 @@ /** * Notifies the "please wait" dialog about progress has been made. * - * @param ui_handle The request UI handle. - * @param fraction The part of task that is done (between 0.0 and 1.0, + * @ui_handle: The request UI handle. + * @fraction: The part of task that is done (between 0.0 and 1.0, * inclusive). */ void @@ -1932,27 +1932,27 @@ /** * Displays groups of fields for the user to fill in. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param primary The main point of the message, or @c NULL if you're + * @primary: The main point of the message, or @c NULL if you're * feeling enigmatic. - * @param secondary Secondary information, or @c NULL if there is none. - * @param fields The list of fields. - * @param ok_text The text for the @c OK button, which may not be @c NULL. - * @param ok_cb The callback for the @c OK button, which may not be @c + * @secondary: Secondary information, or @c NULL if there is none. + * @fields: The list of fields. + * @ok_text: The text for the @c OK button, which may not be @c NULL. + * @ok_cb: The callback for the @c OK button, which may not be @c * NULL. - * @param cancel_text The text for the @c Cancel button, which may not be @c + * @cancel_text: The text for the @c Cancel button, which may not be @c * NULL. - * @param cancel_cb The callback for the @c Cancel button, which may be + * @cancel_cb: The callback for the @c Cancel button, which may be * @c NULL. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void * purple_request_fields(void *handle, const char *title, const char *primary, @@ -1965,11 +1965,11 @@ /** * Checks, if passed UI handle is valid. * - * @param ui_handle The UI handle. - * @param type The pointer to variable, where request type may be stored + * @ui_handle: The UI handle. + * @type: The pointer to variable, where request type may be stored * (may be @c NULL). * - * @return TRUE, if handle is valid, FALSE otherwise. + * Returns: TRUE, if handle is valid, FALSE otherwise. */ gboolean purple_request_is_valid_ui_handle(void *ui_handle, PurpleRequestType *type); @@ -1977,9 +1977,9 @@ /** * Adds a function called when notification dialog is closed. * - * @param ui_handle The UI handle. - * @param notify The function to be called. - * @param notify_data The data to be passed to the callback function. + * @ui_handle: The UI handle. + * @notify: The function to be called. + * @notify_data: The data to be passed to the callback function. */ void purple_request_add_close_notify(void *ui_handle, GDestroyNotify notify, @@ -1988,15 +1988,15 @@ /** * Closes a request. * - * @param type The request type. - * @param uihandle The request UI handle. + * @type: The request type. + * @uihandle: The request UI handle. */ void purple_request_close(PurpleRequestType type, void *uihandle); /** * Closes all requests registered with the specified handle. * - * @param handle The handle, as supplied as the @a handle parameter to one of the + * @handle: The handle, as supplied as the @a handle parameter to one of the * <tt>purple_request_*</tt> functions. * * @see purple_request_input(). @@ -2034,21 +2034,21 @@ * Displays a file selector request dialog. Returns the selected filename to * the callback. Can be used for either opening a file or saving a file. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param filename The default filename (may be @c NULL) - * @param savedialog True if this dialog is being used to save a file. + * @filename: The default filename (may be @c NULL) + * @savedialog: True if this dialog is being used to save a file. * False if it is being used to open a file. - * @param ok_cb The callback for the @c OK button. - * @param cancel_cb The callback for the @c Cancel button, which may be @c NULL. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @ok_cb: The callback for the @c OK button. + * @cancel_cb: The callback for the @c Cancel button, which may be @c NULL. + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void * purple_request_file(void *handle, const char *title, const char *filename, @@ -2059,19 +2059,19 @@ * Displays a folder select dialog. Returns the selected filename to * the callback. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param dirname The default directory name (may be @c NULL) - * @param ok_cb The callback for the @c OK button. - * @param cancel_cb The callback for the @c Cancel button, which may be @c NULL. - * @param cpar The #PurpleRequestCommonParameters object, which gets + * @dirname: The default directory name (may be @c NULL) + * @ok_cb: The callback for the @c OK button. + * @cancel_cb: The callback for the @c Cancel button, which may be @c NULL. + * @cpar: The #PurpleRequestCommonParameters object, which gets * unref'ed after this call. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void * purple_request_folder(void *handle, const char *title, const char *dirname, @@ -2083,25 +2083,25 @@ * * This is often represented as a dialog with a button for each action. * - * @param handle The plugin or connection handle. For some things this + * @handle: The plugin or connection handle. For some things this * is <em>extremely</em> important. See the comments on * purple_request_input(). - * @param title The title of the message, or @c NULL if it should have + * @title: The title of the message, or @c NULL if it should have * no title. - * @param primary The main point of the message, or @c NULL if you're + * @primary: The main point of the message, or @c NULL if you're * feeling enigmatic. - * @param secondary Secondary information, or @c NULL if there is none. - * @param cert The #PurpleCertificate associated with this request. - * @param ok_text The text for the @c OK button, which may not be @c NULL. - * @param ok_cb The callback for the @c OK button, which may not be + * @secondary: Secondary information, or @c NULL if there is none. + * @cert: The #PurpleCertificate associated with this request. + * @ok_text: The text for the @c OK button, which may not be @c NULL. + * @ok_cb: The callback for the @c OK button, which may not be * @c NULL. - * @param cancel_text The text for the @c Cancel button, which may not be + * @cancel_text: The text for the @c Cancel button, which may not be * @c NULL. - * @param cancel_cb The callback for the @c Cancel button, which may be + * @cancel_cb: The callback for the @c Cancel button, which may be * @c NULL. - * @param user_data The data to pass to the callback. + * @user_data: The data to pass to the callback. * - * @return A UI-specific handle. + * Returns: A UI-specific handle. */ void *purple_request_certificate(void *handle, const char *title, const char *primary, const char *secondary, PurpleCertificate *cert, @@ -2120,7 +2120,7 @@ * Sets the UI operations structure to be used when displaying a * request. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_request_set_ui_ops(PurpleRequestUiOps *ops); @@ -2128,7 +2128,7 @@ * Returns the UI operations structure to be used when displaying a * request. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleRequestUiOps *purple_request_get_ui_ops(void);
--- 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);
--- a/libpurple/savedstatuses.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/savedstatuses.h Wed Jan 29 05:28:33 2014 +0530 @@ -79,12 +79,12 @@ * Create a new saved status. This will add the saved status to the * list of saved statuses and writes the revised list to status.xml. * - * @param title The title of the saved status. This must be + * @title: The title of the saved status. This must be * unique. Or, if you want to create a transient * saved status, then pass in NULL. - * @param type The type of saved status. + * @type: The type of saved status. * - * @return The newly created saved status, or NULL if the title you + * Returns: The newly created saved status, or NULL if the title you * used was already taken. */ PurpleSavedStatus *purple_savedstatus_new(const char *title, @@ -93,8 +93,8 @@ /** * Set the title for the given saved status. * - * @param status The saved status. - * @param title The title of the saved status. + * @status: The saved status. + * @title: The title of the saved status. */ void purple_savedstatus_set_title(PurpleSavedStatus *status, const char *title); @@ -102,8 +102,8 @@ /** * Set the type for the given saved status. * - * @param status The saved status. - * @param type The type of saved status. + * @status: The saved status. + * @type: The type of saved status. */ void purple_savedstatus_set_type(PurpleSavedStatus *status, PurpleStatusPrimitive type); @@ -111,8 +111,8 @@ /** * Set the message for the given saved status. * - * @param status The saved status. - * @param message The message, or NULL if you want to unset the + * @status: The saved status. + * @message: The message, or NULL if you want to unset the * message for this status. */ void purple_savedstatus_set_message(PurpleSavedStatus *status, @@ -121,11 +121,11 @@ /** * Set a substatus for an account in a saved status. * - * @param status The saved status. - * @param account The account. - * @param type The status type for the account in the staved + * @status: The saved status. + * @account: The account. + * @type: The status type for the account in the staved * status. - * @param message The message for the account in the substatus. + * @message: The message for the account in the substatus. */ void purple_savedstatus_set_substatus(PurpleSavedStatus *status, const PurpleAccount *account, @@ -138,8 +138,8 @@ * saved status is activated then this account will use the default * status type and message. * - * @param saved_status The saved status. - * @param account The account. + * @saved_status: The saved status. + * @account: The account. */ void purple_savedstatus_unset_substatus(PurpleSavedStatus *saved_status, const PurpleAccount *account); @@ -148,9 +148,9 @@ * Delete a saved status. This removes the saved status from the list * of saved statuses, and writes the revised list to status.xml. * - * @param title The title of the saved status. + * @title: The title of the saved status. * - * @return TRUE if the status was successfully deleted. FALSE if the + * Returns: TRUE if the status was successfully deleted. FALSE if the * status could not be deleted because no saved status exists * with the given title. */ @@ -160,7 +160,7 @@ * Delete a saved status. This removes the saved status from the list * of saved statuses, and writes the revised list to status.xml. * - * @param saved_status the status to delete, the pointer is invalid after + * @saved_status: the status to delete, the pointer is invalid after * the call * */ @@ -169,7 +169,7 @@ /** * Returns all saved statuses. * - * @constreturn A list of saved statuses. + * Returns: (TODO const): A list of saved statuses. */ GList *purple_savedstatuses_get_all(void); @@ -179,10 +179,10 @@ * how many times it has been used. Transient statuses without * messages are not included in the list. * - * @param how_many The maximum number of saved statuses + * @how_many: The maximum number of saved statuses * to return, or '0' to get all saved * statuses sorted by popularity. - * @return A linked list containing at most how_many + * Returns: A linked list containing at most how_many * PurpleSavedStatuses. This list should be * g_list_free'd by the caller (but the * PurpleSavedStatuses must not be free'd). @@ -194,7 +194,7 @@ * then this returns purple_savedstatus_get_idleaway(). Otherwise * it returns purple_savedstatus_get_default(). * - * @return A pointer to the in-use PurpleSavedStatus. + * Returns: A pointer to the in-use PurpleSavedStatus. * This function never returns NULL. */ PurpleSavedStatus *purple_savedstatus_get_current(void); @@ -203,7 +203,7 @@ * Returns the default saved status that is used when our * accounts are not idle-away. * - * @return A pointer to the in-use PurpleSavedStatus. + * Returns: A pointer to the in-use PurpleSavedStatus. * This function never returns NULL. */ PurpleSavedStatus *purple_savedstatus_get_default(void); @@ -212,7 +212,7 @@ * Returns the saved status that is used when your * accounts become idle-away. * - * @return A pointer to the idle-away PurpleSavedStatus. + * Returns: A pointer to the idle-away PurpleSavedStatus. * This function never returns NULL. */ PurpleSavedStatus *purple_savedstatus_get_idleaway(void); @@ -221,14 +221,14 @@ * Return TRUE if we are currently idle-away. Otherwise * returns FALSE. * - * @return TRUE if our accounts have been set to idle-away. + * Returns: TRUE if our accounts have been set to idle-away. */ gboolean purple_savedstatus_is_idleaway(void); /** * Set whether accounts in Purple are idle-away or not. * - * @param idleaway TRUE if accounts should be switched to use the + * @idleaway: TRUE if accounts should be switched to use the * idle-away saved status. FALSE if they should * be switched to use the default status. */ @@ -237,7 +237,7 @@ /** * Returns the status to be used when purple is starting up * - * @return A pointer to the startup PurpleSavedStatus. + * Returns: A pointer to the startup PurpleSavedStatus. * This function never returns NULL. */ PurpleSavedStatus *purple_savedstatus_get_startup(void); @@ -245,31 +245,31 @@ /** * Finds a saved status with the specified title. * - * @param title The name of the saved status. + * @title: The name of the saved status. * - * @return The saved status if found, or NULL. + * Returns: The saved status if found, or NULL. */ PurpleSavedStatus *purple_savedstatus_find(const char *title); /** * Finds a saved status with the specified creation time. * - * @param creation_time The timestamp when the saved + * @creation_time: The timestamp when the saved * status was created. * - * @return The saved status if found, or NULL. + * Returns: The saved status if found, or NULL. */ PurpleSavedStatus *purple_savedstatus_find_by_creation_time(time_t creation_time); /** * Finds a saved status with the specified primitive and message. * - * @param type The PurpleStatusPrimitive for the status you're trying + * @type: The PurpleStatusPrimitive for the status you're trying * to find. - * @param message The message for the status you're trying + * @message: The message for the status you're trying * to find. * - * @return The saved status if found, or NULL. + * Returns: The saved status if found, or NULL. */ PurpleSavedStatus *purple_savedstatus_find_transient_by_type_and_message(PurpleStatusPrimitive type, const char *message); @@ -286,18 +286,18 @@ * we need to save this status information is so we can * restore it when Purple restarts. * - * @param saved_status The saved status. + * @saved_status: The saved status. * - * @return TRUE if the saved status is transient. + * Returns: TRUE if the saved status is transient. */ gboolean purple_savedstatus_is_transient(const PurpleSavedStatus *saved_status); /** * Return the name of a given saved status. * - * @param saved_status The saved status. + * @saved_status: The saved status. * - * @return The title. This value may be a static buffer which may + * Returns: The title. This value may be a static buffer which may * be overwritten on subsequent calls to this function. If * you need a reference to the title for prolonged use then * you should make a copy of it. @@ -307,18 +307,18 @@ /** * Return the type of a given saved status. * - * @param saved_status The saved status. + * @saved_status: The saved status. * - * @return The name. + * Returns: The name. */ PurpleStatusPrimitive purple_savedstatus_get_type(const PurpleSavedStatus *saved_status); /** * Return the default message of a given saved status. * - * @param saved_status The saved status. + * @saved_status: The saved status. * - * @return The message. This will return NULL if the saved + * Returns: The message. This will return NULL if the saved * status does not have a message. This will * contain the normal markup that is created by * Purple's IMHTML (basically HTML markup). @@ -336,9 +336,9 @@ * However, this value is guaranteed to be a unique * identifier for the given saved status. * - * @param saved_status The saved status. + * @saved_status: The saved status. * - * @return The timestamp when this saved status was created. + * Returns: The timestamp when this saved status was created. */ time_t purple_savedstatus_get_creation_time(const PurpleSavedStatus *saved_status); @@ -347,9 +347,9 @@ * or if it is a simple status (the same for all * accounts). * - * @param saved_status The saved status. + * @saved_status: The saved status. * - * @return TRUE if the saved_status has substatuses. + * Returns: TRUE if the saved_status has substatuses. * FALSE otherwise. */ gboolean purple_savedstatus_has_substatuses(const PurpleSavedStatus *saved_status); @@ -357,10 +357,10 @@ /** * Get the substatus for an account in a saved status. * - * @param saved_status The saved status. - * @param account The account. + * @saved_status: The saved status. + * @account: The account. * - * @return The PurpleSavedStatusSub for the account, or NULL if + * Returns: The PurpleSavedStatusSub for the account, or NULL if * the given account does not have a substatus that * differs from the default status of this PurpleSavedStatus. */ @@ -371,18 +371,18 @@ /** * Get the status type of a given substatus. * - * @param substatus The substatus. + * @substatus: The substatus. * - * @return The status type. + * Returns: The status type. */ const PurpleStatusType *purple_savedstatus_substatus_get_type(const PurpleSavedStatusSub *substatus); /** * Get the message of a given substatus. * - * @param substatus The substatus. + * @substatus: The substatus. * - * @return The message of the substatus, or NULL if this substatus does + * Returns: The message of the substatus, or NULL if this substatus does * not have a message. */ const char *purple_savedstatus_substatus_get_message(const PurpleSavedStatusSub *substatus); @@ -392,7 +392,7 @@ * by the given saved_status. This function calls * purple_savedstatus_activate_for_account() for all your accounts. * - * @param saved_status The status you want to set your accounts to. + * @saved_status: The status you want to set your accounts to. */ void purple_savedstatus_activate(PurpleSavedStatus *saved_status); @@ -400,15 +400,15 @@ * Sets the statuses for a given account to those specified * by the given saved_status. * - * @param saved_status The status you want to set your accounts to. - * @param account The account whose statuses you want to change. + * @saved_status: The status you want to set your accounts to. + * @account: The account whose statuses you want to change. */ void purple_savedstatus_activate_for_account(const PurpleSavedStatus *saved_status, PurpleAccount *account); /** * Get the handle for the status subsystem. * - * @return the handle to the status subsystem + * Returns: the handle to the status subsystem */ void *purple_savedstatuses_get_handle(void);
--- a/libpurple/server.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/server.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,10 +37,10 @@ * * TODO: Could probably move this into the conversation API. * - * @param gc The connection over which to send the typing notification. - * @param name The user to send the typing notification to. - * @param state One of PURPLE_IM_TYPING, PURPLE_IM_TYPED, or PURPLE_IM_NOT_TYPING. - * @return A quiet-period, specified in seconds, where Purple will not + * @gc: The connection over which to send the typing notification. + * @name: The user to send the typing notification to. + * @state: One of PURPLE_IM_TYPING, PURPLE_IM_TYPED, or PURPLE_IM_NOT_TYPING. + * Returns: A quiet-period, specified in seconds, where Purple will not * send any additional typing notification messages. Most * protocols should return 0, which means that no additional * PURPLE_IM_TYPING messages need to be sent. If this is 5, for @@ -55,7 +55,7 @@ /** Get information about an account's attention commands, from the protocol. * - * @return The attention command numbered 'code' from the protocol's attention_types, or NULL. + * Returns: The attention command numbered 'code' from the protocol's attention_types, or NULL. */ PurpleAttentionType *purple_get_attention_type_from_code(PurpleAccount *account, guint type_code); @@ -79,9 +79,9 @@ * the server. Private aliases are the aliases the user sets, while public * aliases are the aliases or display names that buddies set for themselves. * - * @param gc The connection on which the alias was received. - * @param who The name of the buddy whose alias was received. - * @param alias The alias that was received. + * @gc: The connection on which the alias was received. + * @who: The name of the buddy whose alias was received. + * @alias: The alias that was received. */ void purple_serv_got_private_alias(PurpleConnection *gc, const char *who, const char *alias); @@ -93,14 +93,14 @@ * * TODO: Could probably move this into the conversation API. * - * @param gc The connection on which the typing message was received. - * @param name The name of the remote user. - * @param timeout If this is a number greater than 0, then + * @gc: The connection on which the typing message was received. + * @name: The name of the remote user. + * @timeout: If this is a number greater than 0, then * Purple will wait this number of seconds and then * set this buddy to the PURPLE_IM_NOT_TYPING state. This * is used by protocols that send repeated typing messages * while the user is composing the message. - * @param state The typing state received + * @state: The typing state received */ void serv_got_typing(PurpleConnection *gc, const char *name, int timeout, PurpleIMTypingState state); @@ -114,13 +114,13 @@ PurpleMessageFlags flags, time_t mtime); /** - * @param data The hash function should be g_str_hash() and the equal + * @data: The hash function should be g_str_hash() and the equal * function should be g_str_equal(). */ void serv_join_chat(PurpleConnection *, GHashTable *data); /** - * @param data The hash function should be g_str_hash() and the equal + * @data: The hash function should be g_str_hash() and the equal * function should be g_str_equal(). */ void serv_reject_chat(PurpleConnection *, GHashTable *data); @@ -128,11 +128,11 @@ /** * Called by a protocol when an account is invited into a chat. * - * @param gc The connection on which the invite arrived. - * @param name The name of the chat you're being invited to. - * @param who The username of the person inviting the account. - * @param message The optional invite message. - * @param data The components necessary if you want to call serv_join_chat(). + * @gc: The connection on which the invite arrived. + * @name: The name of the chat you're being invited to. + * @who: The username of the person inviting the account. + * @message: The optional invite message. + * @data: The components necessary if you want to call serv_join_chat(). * The hash function should be g_str_hash() and the equal * function should be g_str_equal(). */ @@ -143,10 +143,10 @@ /** * Called by a protocol when an account has joined a chat. * - * @param gc The connection on which the chat was joined. - * @param id The id of the chat, assigned by the protocol. - * @param name The name of the chat. - * @return The resulting conversation + * @gc: The connection on which the chat was joined. + * @id: The id of the chat, assigned by the protocol. + * @name: The name of the chat. + * Returns: The resulting conversation */ PurpleChatConversation *serv_got_joined_chat(PurpleConnection *gc, int id, const char *name); @@ -154,8 +154,8 @@ * Called by a protocol when an attempt to join a chat via serv_join_chat() * fails. * - * @param gc The connection on which chat joining failed - * @param data The components passed to serv_join_chat() originally. + * @gc: The connection on which chat joining failed + * @data: The components passed to serv_join_chat() originally. * The hash function should be g_str_hash() and the equal * function should be g_str_equal(). */ @@ -165,7 +165,7 @@ * Called by a protocol when an account has left a chat. * * @param g The connection on which the chat was left. - * @param id The id of the chat, as assigned by the protocol. + * @id: The id of the chat, as assigned by the protocol. */ void serv_got_chat_left(PurpleConnection *g, int id); @@ -173,11 +173,11 @@ * Called by a protocol when a message has been received in a chat. * * @param g The connection on which the message was received. - * @param id The id of the chat, as assigned by the protocol. - * @param who The name of the user who sent the message. - * @param flags The flags of the message. - * @param message The message received in the chat. - * @param mtime The time when the message was received. + * @id: The id of the chat, as assigned by the protocol. + * @who: The name of the user who sent the message. + * @flags: The flags of the message. + * @message: The message received in the chat. + * @mtime: The time when the message was received. */ void serv_got_chat_in(PurpleConnection *g, int id, const char *who, PurpleMessageFlags flags, const char *message, time_t mtime);
--- a/libpurple/signals.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/signals.h Wed Jan 29 05:28:33 2014 +0530 @@ -65,14 +65,14 @@ /** * Registers a signal in an instance. * - * @param instance The instance to register the signal for. - * @param signal The signal name. - * @param marshal The marshal function. - * @param ret_type The return type, or G_TYPE_NONE for no return type. - * @param num_values The number of values to be passed to the callbacks. - * @param ... The types of the parameters for the callbacks. + * @instance: The instance to register the signal for. + * @signal: The signal name. + * @marshal: The marshal function. + * @ret_type: The return type, or G_TYPE_NONE for no return type. + * @num_values: The number of values to be passed to the callbacks. + * @...: The types of the parameters for the callbacks. * - * @return The signal ID local to that instance, or 0 if the signal + * Returns: The signal ID local to that instance, or 0 if the signal * couldn't be registered. */ gulong purple_signal_register(void *instance, const char *signal, @@ -82,26 +82,26 @@ /** * Unregisters a signal in an instance. * - * @param instance The instance to unregister the signal for. - * @param signal The signal name. + * @instance: The instance to unregister the signal for. + * @signal: The signal name. */ void purple_signal_unregister(void *instance, const char *signal); /** * Unregisters all signals in an instance. * - * @param instance The instance to unregister the signal for. + * @instance: The instance to unregister the signal for. */ void purple_signals_unregister_by_instance(void *instance); /** * Returns a list of value types used for a signal. * - * @param instance The instance the signal is registered to. - * @param signal The signal. - * @param ret_type The return type. - * @param num_values The returned number of parameters. - * @param param_types The returned list of parameter types. + * @instance: The instance the signal is registered to. + * @signal: The signal. + * @ret_type: The return type. + * @num_values: The returned number of parameters. + * @param_types: The returned list of parameter types. */ void purple_signal_get_types(void *instance, const char *signal, GType *ret_type, int *num_values, @@ -113,17 +113,17 @@ * Take care not to register a handler function twice. Purple will * not correct any mistakes for you in this area. * - * @param instance The instance to connect to. - * @param signal The name of the signal to connect. - * @param handle The handle of the receiver. - * @param func The callback function. - * @param data The data to pass to the callback function. - * @param priority The priority with which the handler should be called. Signal + * @instance: The instance to connect to. + * @signal: The name of the signal to connect. + * @handle: The handle of the receiver. + * @func: The callback function. + * @data: The data to pass to the callback function. + * @priority: The priority with which the handler should be called. Signal * handlers are called in ascending numerical order of @a * priority from #PURPLE_SIGNAL_PRIORITY_LOWEST to * #PURPLE_SIGNAL_PRIORITY_HIGHEST. * - * @return The signal handler ID. + * Returns: The signal handler ID. * * @see purple_signal_disconnect() */ @@ -137,13 +137,13 @@ * Take care not to register a handler function twice. Purple will * not correct any mistakes for you in this area. * - * @param instance The instance to connect to. - * @param signal The name of the signal to connect. - * @param handle The handle of the receiver. - * @param func The callback function. - * @param data The data to pass to the callback function. + * @instance: The instance to connect to. + * @signal: The name of the signal to connect. + * @handle: The handle of the receiver. + * @func: The callback function. + * @data: The data to pass to the callback function. * - * @return The signal handler ID. + * Returns: The signal handler ID. * * @see purple_signal_disconnect() */ @@ -159,17 +159,17 @@ * Take care not to register a handler function twice. Purple will * not correct any mistakes for you in this area. * - * @param instance The instance to connect to. - * @param signal The name of the signal to connect. - * @param handle The handle of the receiver. - * @param func The callback function. - * @param data The data to pass to the callback function. - * @param priority The priority with which the handler should be called. Signal + * @instance: The instance to connect to. + * @signal: The name of the signal to connect. + * @handle: The handle of the receiver. + * @func: The callback function. + * @data: The data to pass to the callback function. + * @priority: The priority with which the handler should be called. Signal * handlers are called in ascending numerical order of @a * priority from #PURPLE_SIGNAL_PRIORITY_LOWEST to * #PURPLE_SIGNAL_PRIORITY_HIGHEST. * - * @return The signal handler ID. + * Returns: The signal handler ID. * * @see purple_signal_disconnect() */ @@ -186,13 +186,13 @@ * Take care not to register a handler function twice. Purple will * not correct any mistakes for you in this area. * - * @param instance The instance to connect to. - * @param signal The name of the signal to connect. - * @param handle The handle of the receiver. - * @param func The callback function. - * @param data The data to pass to the callback function. + * @instance: The instance to connect to. + * @signal: The name of the signal to connect. + * @handle: The handle of the receiver. + * @func: The callback function. + * @data: The data to pass to the callback function. * - * @return The signal handler ID. + * Returns: The signal handler ID. * * @see purple_signal_disconnect() */ @@ -202,10 +202,10 @@ /** * Disconnects a signal handler from a signal on an object. * - * @param instance The instance to disconnect from. - * @param signal The name of the signal to disconnect. - * @param handle The handle of the receiver. - * @param func The registered function to disconnect. + * @instance: The instance to disconnect from. + * @signal: The name of the signal to disconnect. + * @handle: The handle of the receiver. + * @func: The registered function to disconnect. * * @see purple_signal_connect() */ @@ -215,15 +215,15 @@ /** * Removes all callbacks associated with a receiver handle. * - * @param handle The receiver handle. + * @handle: The receiver handle. */ void purple_signals_disconnect_by_handle(void *handle); /** * Emits a signal. * - * @param instance The instance emitting the signal. - * @param signal The signal being emitted. + * @instance: The instance emitting the signal. + * @signal: The signal being emitted. * * @see purple_signal_connect() * @see purple_signal_disconnect() @@ -233,9 +233,9 @@ /** * Emits a signal, using a va_list of arguments. * - * @param instance The instance emitting the signal. - * @param signal The signal being emitted. - * @param args The arguments list. + * @instance: The instance emitting the signal. + * @signal: The signal being emitted. + * @args: The arguments list. * * @see purple_signal_connect() * @see purple_signal_disconnect() @@ -248,10 +248,10 @@ * Further signal handlers are NOT called after a handler returns * something other than NULL. * - * @param instance The instance emitting the signal. - * @param signal The signal being emitted. + * @instance: The instance emitting the signal. + * @signal: The signal being emitted. * - * @return The first non-NULL return value + * Returns: The first non-NULL return value */ void *purple_signal_emit_return_1(void *instance, const char *signal, ...); @@ -261,11 +261,11 @@ * Further signal handlers are NOT called after a handler returns * something other than NULL. * - * @param instance The instance emitting the signal. - * @param signal The signal being emitted. - * @param args The arguments list. + * @instance: The instance emitting the signal. + * @signal: The signal being emitted. + * @args: The arguments list. * - * @return The first non-NULL return value + * Returns: The first non-NULL return value */ void *purple_signal_emit_vargs_return_1(void *instance, const char *signal, va_list args);
--- a/libpurple/smiley.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/smiley.h Wed Jan 29 05:28:33 2014 +0530 @@ -86,10 +86,10 @@ * If a custom smiley with the given shortcut already exists, it * will be automaticaly returned. * - * @param img The image associated with the smiley. - * @param shortcut The associated shortcut (e.g. "(homer)"). + * @img: The image associated with the smiley. + * @shortcut: The associated shortcut (e.g. "(homer)"). * - * @return The custom smiley. + * Returns: The custom smiley. */ PurpleSmiley * purple_smiley_new(PurpleStoredImage *img, const char *shortcut); @@ -100,10 +100,10 @@ * If a custom smiley with the given shortcut already exists, it * will be automaticaly returned. * - * @param shortcut The associated shortcut (e.g. "(homer)"). - * @param filepath The image file. + * @shortcut: The associated shortcut (e.g. "(homer)"). + * @filepath: The image file. * - * @return The custom smiley. + * Returns: The custom smiley. */ PurpleSmiley * purple_smiley_new_from_file(const char *shortcut, const char *filepath); @@ -111,7 +111,7 @@ /** * Destroys the custom smiley and releases the associated resources. * - * @param smiley The custom smiley. + * @smiley: The custom smiley. */ void purple_smiley_delete(PurpleSmiley *smiley); @@ -119,11 +119,11 @@ /** * Changes the custom smiley's shortcut. * - * @param smiley The custom smiley. - * @param shortcut The new shortcut. A custom smiley with this shortcut + * @smiley: The custom smiley. + * @shortcut: The new shortcut. A custom smiley with this shortcut * cannot already be in use. * - * @return TRUE if the shortcut was changed. FALSE otherwise. + * Returns: TRUE if the shortcut was changed. FALSE otherwise. */ gboolean purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut); @@ -131,10 +131,10 @@ /** * Changes the custom smiley's image data. * - * @param smiley The custom smiley. - * @param smiley_data The custom smiley data, which the smiley code + * @smiley: The custom smiley. + * @smiley_data: The custom smiley data, which the smiley code * takes ownership of and will free. - * @param smiley_data_len The length of the data in @a smiley_data. + * @smiley_data_len: The length of the data in @a smiley_data. */ void purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data, @@ -143,18 +143,18 @@ /** * Returns the custom smiley's associated shortcut (e.g. "(homer)"). * - * @param smiley The custom smiley. + * @smiley: The custom smiley. * - * @return The shortcut. + * Returns: The shortcut. */ const char *purple_smiley_get_shortcut(const PurpleSmiley *smiley); /** * Returns the custom smiley data's checksum. * - * @param smiley The custom smiley. + * @smiley: The custom smiley. * - * @return The checksum. + * Returns: The checksum. */ const char *purple_smiley_get_checksum(const PurpleSmiley *smiley); @@ -164,29 +164,29 @@ * The returned PurpleStoredImage reference counter must be decremented * when the caller is done using it. * - * @param smiley The custom smiley. + * @smiley: The custom smiley. * - * @return A PurpleStoredImage. + * Returns: A PurpleStoredImage. */ PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley); /** * Returns the custom smiley's data. * - * @param smiley The custom smiley. - * @param len If not @c NULL, the length of the image data returned + * @smiley: The custom smiley. + * @len: If not @c NULL, the length of the image data returned * will be set in the location pointed to by this. * - * @return A pointer to the custom smiley data. + * Returns: A pointer to the custom smiley data. */ gconstpointer purple_smiley_get_data(const PurpleSmiley *smiley, size_t *len); /** * Returns an extension corresponding to the custom smiley's file type. * - * @param smiley The custom smiley. + * @smiley: The custom smiley. * - * @return The custom smiley's extension, "icon" if unknown, or @c NULL if + * Returns: The custom smiley's extension, "icon" if unknown, or @c NULL if * the image data has disappeared. */ const char *purple_smiley_get_extension(const PurpleSmiley *smiley); @@ -203,9 +203,9 @@ * * Think some more. * - * @param smiley The custom smiley. + * @smiley: The custom smiley. * - * @return A full path to the file, or @c NULL under various conditions. + * Returns: A full path to the file, or @c NULL under various conditions. * The caller should use g_free to free the returned string. */ char *purple_smiley_get_full_path(PurpleSmiley *smiley); @@ -222,7 +222,7 @@ * Returns a list of all custom smileys. The caller is responsible for freeing * the list. * - * @return A list of all custom smileys. + * Returns: A list of all custom smileys. */ GList * purple_smileys_get_all(void); @@ -230,9 +230,9 @@ /** * Returns a custom smiley given its shortcut. * - * @param shortcut The custom smiley's shortcut. + * @shortcut: The custom smiley's shortcut. * - * @return The custom smiley if found, or @c NULL if not found. + * Returns: The custom smiley if found, or @c NULL if not found. */ PurpleSmiley * purple_smileys_find_by_shortcut(const char *shortcut); @@ -240,9 +240,9 @@ /** * Returns a custom smiley given its checksum. * - * @param checksum The custom smiley's checksum. + * @checksum: The custom smiley's checksum. * - * @return The custom smiley if found, or @c NULL if not found. + * Returns: The custom smiley if found, or @c NULL if not found. */ PurpleSmiley * purple_smileys_find_by_checksum(const char *checksum); @@ -252,7 +252,7 @@ * * The default directory is PURPLEDIR/custom_smiley. * - * @return The directory in which to store custom smileys cached files. + * Returns: The directory in which to store custom smileys cached files. */ const char *purple_smileys_get_storing_dir(void);
--- a/libpurple/sound-theme.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/sound-theme.h Wed Jan 29 05:28:33 2014 +0530 @@ -78,10 +78,10 @@ /** * Returns a copy of the filename for the sound event. * - * @param theme The theme. - * @param event The purple sound event to look up. + * @theme: The theme. + * @event: The purple sound event to look up. * - * @returns The filename of the sound event. + * Returns:s The filename of the sound event. */ const gchar *purple_sound_theme_get_file(PurpleSoundTheme *theme, const gchar *event); @@ -89,10 +89,10 @@ /** * Returns a copy of the directory and filename for the sound event * - * @param theme The theme. - * @param event The purple sound event to look up + * @theme: The theme. + * @event: The purple sound event to look up * - * @returns The directory + '/' + filename of the sound event. This is + * Returns:s The directory + '/' + filename of the sound event. This is * a newly allocated string that should be freed with g_free. */ gchar *purple_sound_theme_get_file_full(PurpleSoundTheme *theme, @@ -101,9 +101,9 @@ /** * Sets the filename for a given sound event * - * @param theme The theme. - * @param event the purple sound event to look up - * @param filename the name of the file to be used for the event + * @theme: The theme. + * @event: the purple sound event to look up + * @filename: the name of the file to be used for the event */ void purple_sound_theme_set_file(PurpleSoundTheme *theme, const gchar *event,
--- a/libpurple/sound.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/sound.h Wed Jan 29 05:28:33 2014 +0530 @@ -83,8 +83,8 @@ /** * Plays the specified sound file. * - * @param filename The file to play. - * @param account The account that this sound is associated with, or + * @filename: The file to play. + * @account: The account that this sound is associated with, or * NULL if the sound is not associated with any specific * account. This is needed for the "sounds while away?" * preference to work correctly. @@ -94,8 +94,8 @@ /** * Plays the sound associated with the specified event. * - * @param event The event. - * @param account The account that this sound is associated with, or + * @event: The event. + * @account: The account that this sound is associated with, or * NULL if the sound is not associated with any specific * account. This is needed for the "sounds while away?" * preference to work correctly. @@ -105,14 +105,14 @@ /** * Sets the UI sound operations * - * @param ops The UI sound operations structure. + * @ops: The UI sound operations structure. */ void purple_sound_set_ui_ops(PurpleSoundUiOps *ops); /** * Gets the UI sound operations * - * @return The UI sound operations structure. + * Returns: The UI sound operations structure. */ PurpleSoundUiOps *purple_sound_get_ui_ops(void); @@ -129,7 +129,7 @@ /** * Returns the sound subsystem handle. * - * @return The sound subsystem handle. + * Returns: The sound subsystem handle. */ void *purple_sounds_get_handle(void);
--- a/libpurple/sslconn.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/sslconn.h Wed Jan 29 05:28:33 2014 +0530 @@ -88,7 +88,7 @@ typedef struct { /** Initializes the SSL system provided. - * @return @a TRUE if initialization succeeded + * Returns: @a TRUE if initialization succeeded * @see purple_ssl_init */ gboolean (*init)(void); @@ -107,27 +107,27 @@ */ void (*close)(PurpleSslConnection *gsc); /** Reads data from a connection (like POSIX read()) - * @param gsc Connection context - * @param data Pointer to buffer to drop data into - * @param len Maximum number of bytes to read - * @return Number of bytes actually written into @a data (which may be + * @gsc: Connection context + * @data: Pointer to buffer to drop data into + * @len: Maximum number of bytes to read + * Returns: Number of bytes actually written into @a data (which may be * less than @a len), or <0 on error * @see purple_ssl_read */ size_t (*read)(PurpleSslConnection *gsc, void *data, size_t len); /** Writes data to a connection (like POSIX send()) - * @param gsc Connection context - * @param data Data buffer to send data from - * @param len Number of bytes to send from buffer - * @return The number of bytes written to @a data (may be less than + * @gsc: Connection context + * @data: Data buffer to send data from + * @len: Number of bytes to send from buffer + * Returns: The number of bytes written to @a data (may be less than * @a len) or <0 on error * @see purple_ssl_write */ size_t (*write)(PurpleSslConnection *gsc, const void *data, size_t len); /** Obtains the certificate chain provided by the peer * - * @param gsc Connection context - * @return A newly allocated list containing the certificates + * @gsc: Connection context + * Returns: A newly allocated list containing the certificates * the peer provided. * @see PurpleCertificate * @todo Decide whether the ordering of certificates in this @@ -152,15 +152,15 @@ /** * Returns whether or not SSL is currently supported. * - * @return @a TRUE if SSL is supported, or @a FALSE otherwise. + * Returns: @a TRUE if SSL is supported, or @a FALSE otherwise. */ gboolean purple_ssl_is_supported(void); /** * Returns a human-readable string for an SSL error. * - * @param error Error code - * @return Human-readable error explanation + * @error: Error code + * Returns: Human-readable error explanation */ const gchar * purple_ssl_strerror(PurpleSslErrorType error); @@ -169,17 +169,17 @@ * should keep track of the returned value and use it to cancel the * connection, if needed. * - * @param account The account making the connection. - * @param host The destination host. - * @param port The destination port. - * @param func The SSL input handler function. - * @param error_func The SSL error handler function. This function + * @account: The account making the connection. + * @host: The destination host. + * @port: The destination port. + * @func: The SSL input handler function. + * @error_func: The SSL error handler function. This function * should <strong>NOT</strong> call purple_ssl_close(). In * the event of an error the #PurpleSslConnection will be * destroyed for you. - * @param data User-defined data. + * @data: User-defined data. * - * @return The SSL connection handle. + * Returns: The SSL connection handle. */ PurpleSslConnection *purple_ssl_connect(PurpleAccount *account, const char *host, int port, PurpleSslInputFunction func, @@ -191,18 +191,18 @@ * name to verify with the certificate. The caller should keep track of the * returned value and use it to cancel the connection, if needed. * - * @param account The account making the connection. - * @param host The destination host. - * @param port The destination port. - * @param func The SSL input handler function. - * @param error_func The SSL error handler function. This function + * @account: The account making the connection. + * @host: The destination host. + * @port: The destination port. + * @func: The SSL input handler function. + * @error_func: The SSL error handler function. This function * should <strong>NOT</strong> call purple_ssl_close(). In * the event of an error the #PurpleSslConnection will be * destroyed for you. - * @param ssl_host The hostname of the other peer (to verify the CN) - * @param data User-defined data. + * @ssl_host: The hostname of the other peer (to verify the CN) + * @data: User-defined data. * - * @return The SSL connection handle. + * Returns: The SSL connection handle. */ PurpleSslConnection *purple_ssl_connect_with_ssl_cn(PurpleAccount *account, const char *host, int port, PurpleSslInputFunction func, @@ -213,14 +213,14 @@ /** * Makes a SSL connection using an already open file descriptor. * - * @param account The account making the connection. - * @param fd The file descriptor. - * @param func The SSL input handler function. - * @param error_func The SSL error handler function. - * @param host The hostname of the other peer (to verify the CN) - * @param data User-defined data. + * @account: The account making the connection. + * @fd: The file descriptor. + * @func: The SSL input handler function. + * @error_func: The SSL error handler function. + * @host: The hostname of the other peer (to verify the CN) + * @data: User-defined data. * - * @return The SSL connection handle. + * Returns: The SSL connection handle. */ PurpleSslConnection *purple_ssl_connect_with_host_fd(PurpleAccount *account, int fd, PurpleSslInputFunction func, @@ -232,9 +232,9 @@ * Adds an input watcher for the specified SSL connection. * Once the SSL handshake is complete, use this to watch for actual data across it. * - * @param gsc The SSL connection handle. - * @param func The callback function. - * @param data User-defined data. + * @gsc: The SSL connection handle. + * @func: The callback function. + * @data: User-defined data. */ void purple_ssl_input_add(PurpleSslConnection *gsc, PurpleSslInputFunction func, void *data); @@ -244,7 +244,7 @@ * * If there is no input watcher set, does nothing. * - * @param gsc The SSL connection handle. + * @gsc: The SSL connection handle. */ void purple_ssl_input_remove(PurpleSslConnection *gsc); @@ -252,38 +252,38 @@ /** * Closes a SSL connection. * - * @param gsc The SSL connection to close. + * @gsc: The SSL connection to close. */ void purple_ssl_close(PurpleSslConnection *gsc); /** * Reads data from an SSL connection. * - * @param gsc The SSL connection handle. - * @param buffer The destination buffer. - * @param len The maximum number of bytes to read. + * @gsc: The SSL connection handle. + * @buffer: The destination buffer. + * @len: The maximum number of bytes to read. * - * @return The number of bytes read. + * Returns: The number of bytes read. */ size_t purple_ssl_read(PurpleSslConnection *gsc, void *buffer, size_t len); /** * Writes data to an SSL connection. * - * @param gsc The SSL connection handle. - * @param buffer The buffer to write. - * @param len The length of the data to write. + * @gsc: The SSL connection handle. + * @buffer: The buffer to write. + * @len: The length of the data to write. * - * @return The number of bytes written. + * Returns: The number of bytes written. */ size_t purple_ssl_write(PurpleSslConnection *gsc, const void *buffer, size_t len); /** * Obtains the peer's presented certificates * - * @param gsc The SSL connection handle + * @gsc: The SSL connection handle * - * @return The peer certificate chain, in the order of certificate, issuer, + * Returns: The peer certificate chain, in the order of certificate, issuer, * issuer's issuer, etc. @a NULL if no certificates have been provided, */ GList * purple_ssl_get_peer_certificates(PurpleSslConnection *gsc); @@ -298,14 +298,14 @@ /** * Sets the current SSL operations structure. * - * @param ops The SSL operations structure to assign. + * @ops: The SSL operations structure to assign. */ void purple_ssl_set_ops(PurpleSslOps *ops); /** * Returns the current SSL operations structure. * - * @return The SSL operations structure. + * Returns: The SSL operations structure. */ PurpleSslOps *purple_ssl_get_ops(void);
--- a/libpurple/status.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/status.h Wed Jan 29 05:28:33 2014 +0530 @@ -158,9 +158,9 @@ * Lookup the id of a primitive status type based on the type. This * ID is a unique plain-text name of the status, without spaces. * - * @param type A primitive status type. + * @type: A primitive status type. * - * @return The unique ID for this type. + * Returns: The unique ID for this type. */ const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type); @@ -169,9 +169,9 @@ * name is the plain-English name of the status type. It is usually one * or two words. * - * @param type A primitive status type. + * @type: A primitive status type. * - * @return The name of this type, suitable for users to see. + * Returns: The name of this type, suitable for users to see. */ const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type); @@ -179,9 +179,9 @@ * Lookup the value of a primitive status type based on the id. The * ID is a unique plain-text name of the status, without spaces. * - * @param id The unique ID of a primitive status type. + * @id: The unique ID of a primitive status type. * - * @return The PurpleStatusPrimitive value. + * Returns: The PurpleStatusPrimitive value. */ PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id); @@ -200,18 +200,18 @@ /** * Creates a new status type. * - * @param primitive The primitive status type. - * @param id The ID of the status type, or @c NULL to use the id of + * @primitive: The primitive status type. + * @id: The ID of the status type, or @c NULL to use the id of * the primitive status type. - * @param name The name presented to the user, or @c NULL to use the + * @name: The name presented to the user, or @c NULL to use the * name of the primitive status type. - * @param saveable TRUE if the information set for this status by the + * @saveable: TRUE if the information set for this status by the * user can be saved for future sessions. - * @param user_settable TRUE if this is a status the user can manually set. - * @param independent TRUE if this is an independent (non-exclusive) + * @user_settable: TRUE if this is a status the user can manually set. + * @independent: TRUE if this is an independent (non-exclusive) * status type. * - * @return A new status type. + * Returns: A new status type. */ PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive, const char *id, const char *name, @@ -223,14 +223,14 @@ * Creates a new status type with some default values ( * saveable and not independent). * - * @param primitive The primitive status type. - * @param id The ID of the status type, or @c NULL to use the id of + * @primitive: The primitive status type. + * @id: The ID of the status type, or @c NULL to use the id of * the primitive status type. - * @param name The name presented to the user, or @c NULL to use the + * @name: The name presented to the user, or @c NULL to use the * name of the primitive status type. - * @param user_settable TRUE if this is a status the user can manually set. + * @user_settable: TRUE if this is a status the user can manually set. * - * @return A new status type. + * Returns: A new status type. */ PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive, const char *id, const char *name, @@ -239,22 +239,22 @@ /** * Creates a new status type with attributes. * - * @param primitive The primitive status type. - * @param id The ID of the status type, or @c NULL to use the id of + * @primitive: The primitive status type. + * @id: The ID of the status type, or @c NULL to use the id of * the primitive status type. - * @param name The name presented to the user, or @c NULL to use the + * @name: The name presented to the user, or @c NULL to use the * name of the primitive status type. - * @param saveable TRUE if the information set for this status by the + * @saveable: TRUE if the information set for this status by the * user can be saved for future sessions. - * @param user_settable TRUE if this is a status the user can manually set. - * @param independent TRUE if this is an independent (non-exclusive) + * @user_settable: TRUE if this is a status the user can manually set. + * @independent: TRUE if this is an independent (non-exclusive) * status type. - * @param attr_id The ID of the first attribute. - * @param attr_name The name of the first attribute. - * @param attr_value The value type of the first attribute. - * @param ... Additional attribute information. + * @attr_id: The ID of the first attribute. + * @attr_name: The name of the first attribute. + * @attr_value: The value type of the first attribute. + * @...: Additional attribute information. * - * @return A new status type. + * Returns: A new status type. */ PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive, const char *id, @@ -269,16 +269,16 @@ /** * Destroys a status type. * - * @param status_type The status type to destroy. + * @status_type: The status type to destroy. */ void purple_status_type_destroy(PurpleStatusType *status_type); /** * Returns the primitive type of a status type. * - * @param status_type The status type. + * @status_type: The status type. * - * @return The primitive type of the status type. + * Returns: The primitive type of the status type. */ PurpleStatusPrimitive purple_status_type_get_primitive( const PurpleStatusType *status_type); @@ -286,27 +286,27 @@ /** * Returns the ID of a status type. * - * @param status_type The status type. + * @status_type: The status type. * - * @return The ID of the status type. + * Returns: The ID of the status type. */ const char *purple_status_type_get_id(const PurpleStatusType *status_type); /** * Returns the name of a status type. * - * @param status_type The status type. + * @status_type: The status type. * - * @return The name of the status type. + * Returns: The name of the status type. */ const char *purple_status_type_get_name(const PurpleStatusType *status_type); /** * Returns whether or not the status type is saveable. * - * @param status_type The status type. + * @status_type: The status type. * - * @return TRUE if user-defined statuses based off this type are saveable. + * Returns: TRUE if user-defined statuses based off this type are saveable. * FALSE otherwise. */ gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type); @@ -315,9 +315,9 @@ * Returns whether or not the status type can be set or modified by the * user. * - * @param status_type The status type. + * @status_type: The status type. * - * @return TRUE if the status type can be set or modified by the user. + * Returns: TRUE if the status type can be set or modified by the user. * FALSE if it's a protocol-set setting. */ gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type); @@ -328,18 +328,18 @@ * Independent status types are non-exclusive. If other status types on * the same hierarchy level are set, this one will not be affected. * - * @param status_type The status type. + * @status_type: The status type. * - * @return TRUE if the status type is independent, or FALSE otherwise. + * Returns: TRUE if the status type is independent, or FALSE otherwise. */ gboolean purple_status_type_is_independent(const PurpleStatusType *status_type); /** * Returns whether the status type is exclusive. * - * @param status_type The status type. + * @status_type: The status type. * - * @return TRUE if the status type is exclusive, FALSE otherwise. + * Returns: TRUE if the status type is exclusive, FALSE otherwise. */ gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type); @@ -348,19 +348,19 @@ * * Available status types are online and possibly invisible, but not away. * - * @param status_type The status type. + * @status_type: The status type. * - * @return TRUE if the status is available, or FALSE otherwise. + * Returns: TRUE if the status is available, or FALSE otherwise. */ gboolean purple_status_type_is_available(const PurpleStatusType *status_type); /** * Returns the attribute with the specified ID. * - * @param status_type The status type containing the attribute. - * @param id The ID of the desired attribute. + * @status_type: The status type containing the attribute. + * @id: The ID of the desired attribute. * - * @return The attribute, if found. NULL otherwise. + * Returns: The attribute, if found. NULL otherwise. */ PurpleStatusAttribute *purple_status_type_get_attr(const PurpleStatusType *status_type, const char *id); @@ -368,19 +368,19 @@ /** * Returns a list of all attributes in a status type. * - * @param status_type The status type. + * @status_type: The status type. * - * @constreturn The list of attributes. + * Returns: (TODO const): The list of attributes. */ GList *purple_status_type_get_attrs(const PurpleStatusType *status_type); /** * Find the PurpleStatusType with the given id. * - * @param status_types A list of status types. Often account->status_types. - * @param id The unique ID of the status type you wish to find. + * @status_types: A list of status types. Often account->status_types. + * @id: The unique ID of the status type you wish to find. * - * @return The status type with the given ID, or NULL if one could + * Returns: The status type with the given ID, or NULL if one could * not be found. */ const PurpleStatusType *purple_status_type_find_with_id(GList *status_types, @@ -401,11 +401,11 @@ /** * Creates a new status attribute. * - * @param id The ID of the attribute. - * @param name The name presented to the user. - * @param value_type The type of data contained in the attribute. + * @id: The ID of the attribute. + * @name: The name presented to the user. + * @value_type: The type of data contained in the attribute. * - * @return A new status attribute. + * Returns: A new status attribute. */ PurpleStatusAttribute *purple_status_attribute_new(const char *id, const char *name, GValue *value_type); @@ -413,34 +413,34 @@ /** * Destroys a status attribute. * - * @param attr The status attribute to destroy. + * @attr: The status attribute to destroy. */ void purple_status_attribute_destroy(PurpleStatusAttribute *attr); /** * Returns the ID of a status attribute. * - * @param attr The status attribute. + * @attr: The status attribute. * - * @return The status attribute's ID. + * Returns: The status attribute's ID. */ const char *purple_status_attribute_get_id(const PurpleStatusAttribute *attr); /** * Returns the name of a status attribute. * - * @param attr The status attribute. + * @attr: The status attribute. * - * @return The status attribute's name. + * Returns: The status attribute's name. */ const char *purple_status_attribute_get_name(const PurpleStatusAttribute *attr); /** * Returns the value of a status attribute. * - * @param attr The status attribute. + * @attr: The status attribute. * - * @return The status attribute's value. + * Returns: The status attribute's value. */ GValue *purple_status_attribute_get_value(const PurpleStatusAttribute *attr); @@ -471,10 +471,10 @@ /** * Creates a new status. * - * @param status_type The type of status. - * @param presence The parent presence. + * @status_type: The type of status. + * @presence: The parent presence. * - * @return The new status. + * Returns: The new status. */ PurpleStatus *purple_status_new(PurpleStatusType *status_type, PurplePresence *presence); @@ -484,8 +484,8 @@ * * This should only be called by the account, conversation, and buddy APIs. * - * @param status The status. - * @param active The active state. + * @status: The status. + * @active: The active state. */ void purple_status_set_active(PurpleStatus *status, gboolean active); @@ -494,9 +494,9 @@ * * This should only be called by the account, conversation, and buddy APIs. * - * @param status The status. - * @param active The active state. - * @param args A list of attributes to set on the status. This list is + * @status: The status. + * @active: The active state. + * @args: A list of attributes to set on the status. This list is * composed of key/value pairs, where each key is a valid * attribute name for this PurpleStatusType. The list should * be NULL terminated. @@ -509,9 +509,9 @@ * * This should only be called by the account, conversation, and buddy APIs. * - * @param status The status. - * @param active The active state. - * @param attrs A list of attributes to set on the status. This list is + * @status: The status. + * @active: The active state. + * @attrs: A list of attributes to set on the status. This list is * composed of key/value pairs, where each key is a valid * attribute name for this PurpleStatusType. The list is * not modified or freed by this function. @@ -522,18 +522,18 @@ /** * Returns the status's type. * - * @param status The status. + * @status: The status. * - * @return The status's type. + * Returns: The status's type. */ PurpleStatusType *purple_status_get_status_type(const PurpleStatus *status); /** * Returns the status's presence. * - * @param status The status. + * @status: The status. * - * @return The status's presence. + * Returns: The status's presence. */ PurplePresence *purple_status_get_presence(const PurpleStatus *status); @@ -543,9 +543,9 @@ * This is a convenience method for * purple_status_type_get_id(purple_status_get_type(status)). * - * @param status The status. + * @status: The status. * - * @return The status's ID. + * Returns: The status's ID. */ const char *purple_status_get_id(const PurpleStatus *status); @@ -555,9 +555,9 @@ * This is a convenience method for * purple_status_type_get_name(purple_status_get_type(status)). * - * @param status The status. + * @status: The status. * - * @return The status's name. + * Returns: The status's name. */ const char *purple_status_get_name(const PurpleStatus *status); @@ -567,9 +567,9 @@ * This is a convenience method for * purple_status_type_is_independent(purple_status_get_type(status)). * - * @param status The status. + * @status: The status. * - * @return TRUE if the status is independent, or FALSE otherwise. + * Returns: TRUE if the status is independent, or FALSE otherwise. */ gboolean purple_status_is_independent(const PurpleStatus *status); @@ -579,9 +579,9 @@ * This is a convenience method for * purple_status_type_is_exclusive(purple_status_get_type(status)). * - * @param status The status. + * @status: The status. * - * @return TRUE if the status is exclusive, FALSE otherwise. + * Returns: TRUE if the status is exclusive, FALSE otherwise. */ gboolean purple_status_is_exclusive(const PurpleStatus *status); @@ -593,37 +593,37 @@ * This is a convenience method for * purple_status_type_is_available(purple_status_get_type(status)). * - * @param status The status. + * @status: The status. * - * @return TRUE if the status is available, or FALSE otherwise. + * Returns: TRUE if the status is available, or FALSE otherwise. */ gboolean purple_status_is_available(const PurpleStatus *status); /** * Returns the active state of a status. * - * @param status The status. + * @status: The status. * - * @return The active state of the status. + * Returns: The active state of the status. */ gboolean purple_status_is_active(const PurpleStatus *status); /** * Returns whether or not a status is considered 'online' * - * @param status The status. + * @status: The status. * - * @return TRUE if the status is considered online, FALSE otherwise + * Returns: TRUE if the status is considered online, FALSE otherwise */ gboolean purple_status_is_online(const PurpleStatus *status); /** * Returns the value of an attribute in a status with the specified ID. * - * @param status The status. - * @param id The attribute ID. + * @status: The status. + * @id: The attribute ID. * - * @return The value of the attribute. + * Returns: The value of the attribute. */ GValue *purple_status_get_attr_value(const PurpleStatus *status, const char *id); @@ -631,10 +631,10 @@ /** * Returns the boolean value of an attribute in a status with the specified ID. * - * @param status The status. - * @param id The attribute ID. + * @status: The status. + * @id: The attribute ID. * - * @return The boolean value of the attribute. + * Returns: The boolean value of the attribute. */ gboolean purple_status_get_attr_boolean(const PurpleStatus *status, const char *id); @@ -642,20 +642,20 @@ /** * Returns the integer value of an attribute in a status with the specified ID. * - * @param status The status. - * @param id The attribute ID. + * @status: The status. + * @id: The attribute ID. * - * @return The integer value of the attribute. + * Returns: The integer value of the attribute. */ int purple_status_get_attr_int(const PurpleStatus *status, const char *id); /** * Returns the string value of an attribute in a status with the specified ID. * - * @param status The status. - * @param id The attribute ID. + * @status: The status. + * @id: The attribute ID. * - * @return The string value of the attribute. + * Returns: The string value of the attribute. */ const char *purple_status_get_attr_string(const PurpleStatus *status, const char *id); @@ -663,10 +663,10 @@ /** * Compares two statuses for availability. * - * @param status1 The first status. - * @param status2 The second status. + * @status1: The first status. + * @status2: The second status. * - * @return -1 if @a status1 is more available than @a status2. + * Returns: -1 if @a status1 is more available than @a status2. * 0 if @a status1 is equal to @a status2. * 1 if @a status2 is more available than @a status1. */ @@ -682,7 +682,7 @@ /** * Get the handle for the status subsystem. * - * @return the handle to the status subsystem + * Returns: the handle to the status subsystem */ void *purple_statuses_get_handle(void);
--- a/libpurple/stringref.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/stringref.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,10 +37,10 @@ * Creates an immutable reference-counted string object. The newly * created object will have a reference count of 1. * - * @param value This will be the value of the string; it will be + * @value: This will be the value of the string; it will be * duplicated. * - * @return A newly allocated string reference object with a refcount + * Returns: A newly allocated string reference object with a refcount * of 1. */ PurpleStringref *purple_stringref_new(const char *value); @@ -51,10 +51,10 @@ * not referenced before the next iteration of the mainloop it will * be freed at that time. * - * @param value This will be the value of the string; it will be + * @value: This will be the value of the string; it will be * duplicated. * - * @return A newly allocated string reference object with a refcount + * Returns: A newly allocated string reference object with a refcount * of zero. */ PurpleStringref *purple_stringref_new_noref(const char *value); @@ -64,9 +64,9 @@ * format specification and arguments. The created object will have a * reference count of 1. * - * @param format A printf-style format specification. + * @format: A printf-style format specification. * - * @return A newly allocated string reference object with a refcount + * Returns: A newly allocated string reference object with a refcount * of 1. */ PurpleStringref *purple_stringref_printf(const char *format, ...); @@ -74,9 +74,9 @@ /** * Increase the reference count of the given stringref. * - * @param stringref String to be referenced. + * @stringref: String to be referenced. * - * @return A pointer to the referenced string. + * Returns: A pointer to the referenced string. */ PurpleStringref *purple_stringref_ref(PurpleStringref *stringref); @@ -85,7 +85,7 @@ * reference count reaches zero, the stringref will be freed; thus * you MUST NOT use this string after dereferencing it. * - * @param stringref String to be dereferenced. + * @stringref: String to be dereferenced. */ void purple_stringref_unref(PurpleStringref *stringref); @@ -101,9 +101,9 @@ * be valid or invalid nondeterministically based on how many * other references to it exist. * - * @param stringref String reference from which to retrieve the value. + * @stringref: String reference from which to retrieve the value. * - * @return The contents of the string reference. + * Returns: The contents of the string reference. */ const char *purple_stringref_value(const PurpleStringref *stringref); @@ -112,20 +112,20 @@ * value as strcmp would, where <0 indicates that s1 is "less than" s2 * in the ASCII lexicography, 0 indicates equality, etc. * - * @param s1 The reference string. + * @s1: The reference string. * - * @param s2 The string to compare against the reference. + * @s2: The string to compare against the reference. * - * @return An ordering indication on s1 and s2. + * Returns: An ordering indication on s1 and s2. */ int purple_stringref_cmp(const PurpleStringref *s1, const PurpleStringref *s2); /** * Find the length of the string inside a stringref. * - * @param stringref The string in whose length we are interested. + * @stringref: The string in whose length we are interested. * - * @return The length of the string in stringref + * Returns: The length of the string in stringref */ size_t purple_stringref_len(const PurpleStringref *stringref);
--- a/libpurple/stun.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/stun.h Wed Jan 29 05:28:33 2014 +0530 @@ -66,11 +66,11 @@ * is already done. Otherwise the callback is called when the discovery is over * and NULL is returned. * - * @param cb The callback to call when the STUN discovery is finished if the + * @cb: The callback to call when the STUN discovery is finished if the * discovery would block. If the discovery is done, this is NOT * called. * - * @return a PurpleStunNatDiscovery which includes the public IP and the type + * Returns: a PurpleStunNatDiscovery which includes the public IP and the type * of NAT or NULL is discovery would block */ PurpleStunNatDiscovery *purple_stun_discover(StunCallback cb);
--- a/libpurple/theme-loader.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/theme-loader.h Wed Jan 29 05:28:33 2014 +0530 @@ -80,19 +80,19 @@ /** * Returns the string representing the type of the theme loader * - * @param self The theme loader + * @self: The theme loader * - * @returns The string representing this type + * Returns:s The string representing this type */ const gchar *purple_theme_loader_get_type_string(PurpleThemeLoader *self); /** * Creates a new PurpleTheme * - * @param loader The theme loader - * @param dir The directory containing the theme + * @loader: The theme loader + * @dir: The directory containing the theme * - * @returns A PurpleTheme containing the information from the directory + * Returns:s A PurpleTheme containing the information from the directory */ PurpleTheme *purple_theme_loader_build(PurpleThemeLoader *loader, const gchar *dir); @@ -103,10 +103,10 @@ * Loading of a theme may fail for other reasons. * The default prober checks for $dir/purple/$type. * - * @param loader The theme loader - * @param dir The directory that may contain the theme + * @loader: The theme loader + * @dir: The directory that may contain the theme * - * @returns TRUE if the directory appears to contain a theme, FALSE otherwise. + * Returns:s TRUE if the directory appears to contain a theme, FALSE otherwise. */ gboolean purple_theme_loader_probe(PurpleThemeLoader *loader, const gchar *dir);
--- a/libpurple/theme-manager.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/theme-manager.h Wed Jan 29 05:28:33 2014 +0530 @@ -90,10 +90,10 @@ /** * Finds the PurpleTheme object stored by the theme manager. * - * @param name The name of the PurpleTheme. - * @param type The type of the PurpleTheme. + * @name: The name of the PurpleTheme. + * @type: The type of the PurpleTheme. * - * @returns The PurpleTheme, or NULL if it wasn't found. + * Returns:s The PurpleTheme, or NULL if it wasn't found. */ PurpleTheme *purple_theme_manager_find_theme(const gchar *name, const gchar *type); @@ -101,43 +101,43 @@ * Adds a PurpleTheme to the theme manager. If the theme already exists * then this function does nothing. * - * @param theme The PurpleTheme to add to the manager. + * @theme: The PurpleTheme to add to the manager. */ void purple_theme_manager_add_theme(PurpleTheme *theme); /** * Removes a PurpleTheme from the theme manager and frees the theme. * - * @param theme The PurpleTheme to remove from the manager. + * @theme: The PurpleTheme to remove from the manager. */ void purple_theme_manager_remove_theme(PurpleTheme *theme); /** * Adds a loader to the theme manager so it knows how to build themes. * - * @param loader The PurpleThemeLoader to add. + * @loader: The PurpleThemeLoader to add. */ void purple_theme_manager_register_type(PurpleThemeLoader *loader); /** * Removes the loader and all themes of the same type from the loader. * - * @param loader The PurpleThemeLoader to be removed. + * @loader: The PurpleThemeLoader to be removed. */ void purple_theme_manager_unregister_type(PurpleThemeLoader *loader); /** * Calls the given function on each purple theme. * - * @param func The PTFunc to be applied to each theme. + * @func: The PTFunc to be applied to each theme. */ void purple_theme_manager_for_each_theme(PTFunc func); /** * Loads a theme of the given type without adding it to the manager * - * @param theme_dir the directory of the theme to load - * @param type the type of theme to load + * @theme_dir: the directory of the theme to load + * @type: the type of theme to load */ PurpleTheme *purple_theme_manager_load_theme(const gchar *theme_dir, const gchar *type);
--- a/libpurple/theme.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/theme.h Wed Jan 29 05:28:33 2014 +0530 @@ -76,103 +76,103 @@ /** * Returns the name of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return The string representing the name of the theme. + * Returns: The string representing the name of the theme. */ const gchar *purple_theme_get_name(PurpleTheme *theme); /** * Sets the name of the PurpleTheme object. * - * @param theme The purple theme. - * @param name The name of the PurpleTheme object. + * @theme: The purple theme. + * @name: The name of the PurpleTheme object. */ void purple_theme_set_name(PurpleTheme *theme, const gchar *name); /** * Returns the description of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return A short description of the theme. + * Returns: A short description of the theme. */ const gchar *purple_theme_get_description(PurpleTheme *theme); /** * Sets the description of the PurpleTheme object. * - * @param theme The purple theme. - * @param description The description of the PurpleTheme object. + * @theme: The purple theme. + * @description: The description of the PurpleTheme object. */ void purple_theme_set_description(PurpleTheme *theme, const gchar *description); /** * Returns the author of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return The author of the theme. + * Returns: The author of the theme. */ const gchar *purple_theme_get_author(PurpleTheme *theme); /** * Sets the author of the PurpleTheme object. * - * @param theme The purple theme. - * @param author The author of the PurpleTheme object. + * @theme: The purple theme. + * @author: The author of the PurpleTheme object. */ void purple_theme_set_author(PurpleTheme *theme, const gchar *author); /** * Returns the type (string) of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return The string representing the type. + * Returns: The string representing the type. */ const gchar *purple_theme_get_type_string(PurpleTheme *theme); /** * Returns the directory of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return The string representing the theme directory. + * Returns: The string representing the theme directory. */ const gchar *purple_theme_get_dir(PurpleTheme *theme); /** * Sets the directory of the PurpleTheme object. * - * @param theme The purple theme. - * @param dir The directory of the PurpleTheme object. + * @theme: The purple theme. + * @dir: The directory of the PurpleTheme object. */ void purple_theme_set_dir(PurpleTheme *theme, const gchar *dir); /** * Returns the image preview of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return The image preview of the PurpleTheme object. + * Returns: The image preview of the PurpleTheme object. */ const gchar *purple_theme_get_image(PurpleTheme *theme); /** * Returns the image preview and directory of the PurpleTheme object. * - * @param theme The purple theme. + * @theme: The purple theme. * - * @return The image preview of the PurpleTheme object. + * Returns: The image preview of the PurpleTheme object. */ gchar *purple_theme_get_image_full(PurpleTheme *theme); /** * Sets the directory of the PurpleTheme object. * - * @param theme The purple theme. - * @param img The image preview of the PurpleTheme object. + * @theme: The purple theme. + * @img: The image preview of the PurpleTheme object. */ void purple_theme_set_image(PurpleTheme *theme, const gchar *img);
--- a/libpurple/upnp.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/upnp.h Wed Jan 29 05:28:33 2014 +0530 @@ -53,9 +53,9 @@ * public IP address of the IGD, and control it for forwarding ports. * The result will be cached for further use. * - * @param cb an optional callback function to be notified when the UPnP + * @cb: an optional callback function to be notified when the UPnP * discovery is complete - * @param cb_data Extra data to be passed to the callback + * @cb_data: Extra data to be passed to the callback */ void purple_upnp_discover(PurpleUPnPCallback cb, gpointer cb_data); @@ -65,7 +65,7 @@ * This will only be filled in if purple_upnp_discover() had been called, * and finished discovering. * - * @return The control URL for the IGD we'll use to use the IGD services + * Returns: The control URL for the IGD we'll use to use the IGD services */ const PurpleUPnPControlInfo* purple_upnp_get_control_info(void); #endif @@ -76,7 +76,7 @@ * local network IP, the public IP is retrieved. This is a cached value from * the time of the UPnP discovery. * - * @return The IP address of the network, or NULL if something went wrong + * Returns: The IP address of the network, or NULL if something went wrong */ const gchar* purple_upnp_get_public_ip(void); @@ -84,7 +84,7 @@ * Cancel a pending port mapping request initiated with either * purple_upnp_set_port_mapping() or purple_upnp_remove_port_mapping(). * - * @param mapping_data The data returned when you initiated the UPnP mapping request. + * @mapping_data: The data returned when you initiated the UPnP mapping request. */ void purple_upnp_cancel_port_mapping(UPnPMappingAddRemove *mapping_data); @@ -93,13 +93,13 @@ * this purple client. Essentially, this function takes care of the port * forwarding so things like file transfers can work behind NAT firewalls * - * @param portmap The port to map to this client - * @param protocol The protocol to map, either "TCP" or "UDP" - * @param cb an optional callback function to be notified when the mapping + * @portmap: The port to map to this client + * @protocol: The protocol to map, either "TCP" or "UDP" + * @cb: an optional callback function to be notified when the mapping * addition is complete - * @param cb_data Extra data to be passed to the callback + * @cb_data: Extra data to be passed to the callback * - * @return Data which can be passed to purple_upnp_port_mapping_cancel() to cancel + * Returns: Data which can be passed to purple_upnp_port_mapping_cancel() to cancel */ UPnPMappingAddRemove *purple_upnp_set_port_mapping(unsigned short portmap, const gchar* protocol, PurpleUPnPCallback cb, gpointer cb_data); @@ -110,13 +110,13 @@ * port forwarding after they have completed a connection so another client on * the local network can take advantage of the port forwarding * - * @param portmap The port to delete the mapping for - * @param protocol The protocol to map to. Either "TCP" or "UDP" - * @param cb an optional callback function to be notified when the mapping + * @portmap: The port to delete the mapping for + * @protocol: The protocol to map to. Either "TCP" or "UDP" + * @cb: an optional callback function to be notified when the mapping * removal is complete - * @param cb_data Extra data to be passed to the callback + * @cb_data: Extra data to be passed to the callback * - * @return Data which can be passed to purple_upnp_port_mapping_cancel() to cancel + * Returns: Data which can be passed to purple_upnp_port_mapping_cancel() to cancel */ UPnPMappingAddRemove *purple_upnp_remove_port_mapping(unsigned short portmap, const gchar* protocol, PurpleUPnPCallback cb, gpointer cb_data);
--- a/libpurple/util.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/util.h Wed Jan 29 05:28:33 2014 +0530 @@ -67,13 +67,13 @@ /** * Creates a new PurpleMenuAction. * - * @param label The text label to display for this action. - * @param callback The function to be called when the action is used on + * @label: The text label to display for this action. + * @callback: The function to be called when the action is used on * the selected item. - * @param data Additional data to be passed to the callback. - * @param children A GList of PurpleMenuActions to be added as a submenu + * @data: Additional data to be passed to the callback. + * @children: A GList of PurpleMenuActions to be added as a submenu * of the action. - * @return The PurpleMenuAction. + * Returns: The PurpleMenuAction. */ PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback, gpointer data, GList *children); @@ -81,83 +81,83 @@ /** * Frees a PurpleMenuAction * - * @param act The PurpleMenuAction to free. + * @act: The PurpleMenuAction to free. */ void purple_menu_action_free(PurpleMenuAction *act); /** * Returns the label of the PurpleMenuAction. * - * @param act The PurpleMenuAction. + * @act: The PurpleMenuAction. * - * @return The label string. + * Returns: The label string. */ char * purple_menu_action_get_label(const PurpleMenuAction *act); /** * Returns the callback of the PurpleMenuAction. * - * @param act The PurpleMenuAction. + * @act: The PurpleMenuAction. * - * @return The callback function. + * Returns: The callback function. */ PurpleCallback purple_menu_action_get_callback(const PurpleMenuAction *act); /** * Returns the data stored in the PurpleMenuAction. * - * @param act The PurpleMenuAction. + * @act: The PurpleMenuAction. * - * @return The data. + * Returns: The data. */ gpointer purple_menu_action_get_data(const PurpleMenuAction *act); /** * Returns the children of the PurpleMenuAction. * - * @param act The PurpleMenuAction. + * @act: The PurpleMenuAction. * - * @return The GList of children. + * Returns: The GList of children. */ GList* purple_menu_action_get_children(const PurpleMenuAction *act); /** * Set the label to the PurpleMenuAction. * - * @param act The menu action. - * @param label The label for the menu action. + * @act: The menu action. + * @label: The label for the menu action. */ void purple_menu_action_set_label(PurpleMenuAction *act, char *label); /** * Set the callback that will be used by the PurpleMenuAction. * - * @param act The menu action. - * @param callback The callback. + * @act: The menu action. + * @callback: The callback. */ void purple_menu_action_set_callback(PurpleMenuAction *act, PurpleCallback callback); /** * Set the label to the PurpleMenuAction. * - * @param act The menu action. - * @param data The data used by this PurpleMenuAction + * @act: The menu action. + * @data: The data used by this PurpleMenuAction */ void purple_menu_action_set_data(PurpleMenuAction *act, gpointer data); /** * Set the children of the PurpleMenuAction. * - * @param act The menu action. - * @param children The PurpleMenuAtion children + * @act: The menu action. + * @children: The PurpleMenuAtion children */ void purple_menu_action_set_children(PurpleMenuAction *act, GList *children); /** * Sets the icon for the PurpleMenuAction. * - * @param act The menu action. - * @param strock The stock icon identifier. + * @act: The menu action. + * @strock: The stock icon identifier. */ void purple_menu_action_set_stock_icon(PurpleMenuAction *act, const gchar *stock); @@ -165,9 +165,9 @@ /** * Gets the stock icon of the PurpleMenuAction. * - * @param act The menu action. + * @act: The menu action. * - * @return The stock icon identifier. + * Returns: The stock icon identifier. */ const gchar * purple_menu_action_get_stock_icon(PurpleMenuAction *act); @@ -175,9 +175,9 @@ /** * Set the appropriate presence values for the currently playing song. * - * @param title The title of the song, @c NULL to unset the value. - * @param artist The artist of the song, can be @c NULL. - * @param album The album of the song, can be @c NULL. + * @title: The title of the song, @c NULL to unset the value. + * @artist: The artist of the song, can be @c NULL. + * @album: The album of the song, can be @c NULL. */ void purple_util_set_current_song(const char *title, const char *artist, const char *album); @@ -185,12 +185,12 @@ /** * Format song information. * - * @param title The title of the song, @c NULL to unset the value. - * @param artist The artist of the song, can be @c NULL. - * @param album The album of the song, can be @c NULL. - * @param unused Currently unused, must be @c NULL. + * @title: The title of the song, @c NULL to unset the value. + * @artist: The artist of the song, can be @c NULL. + * @album: The album of the song, can be @c NULL. + * @unused: Currently unused, must be @c NULL. * - * @return The formatted string. The caller must g_free the returned string. + * Returns: The formatted string. The caller must g_free the returned string. */ char * purple_util_format_song_info(const char *title, const char *artist, const char *album, gpointer unused); @@ -220,10 +220,10 @@ /** * Converts a chunk of binary data to its base-16 equivalent. * - * @param data The data to convert. - * @param len The length of the data. + * @data: The data to convert. + * @len: The length of the data. * - * @return The base-16 string in the ASCII encoding. Must be + * Returns: The base-16 string in the ASCII encoding. Must be * g_free'd when no longer needed. * * @see purple_base16_decode() @@ -234,14 +234,14 @@ * Converts an ASCII string of base-16 encoded data to * the binary equivalent. * - * @param str The base-16 string to convert to raw data. - * @param ret_len The length of the returned data. You can + * @str: The base-16 string to convert to raw data. + * @ret_len: The length of the returned data. You can * pass in NULL if you're sure that you know * the length of the decoded data, or if you * know you'll be able to use strlen to * determine the length, etc. * - * @return The raw data. Must be g_free'd when no longer needed. + * Returns: The raw data. Must be g_free'd when no longer needed. * * @see purple_base16_encode() */ @@ -253,10 +253,10 @@ * * Example output: 01:23:45:67:89:AB:CD:EF * - * @param data The data to convert. - * @param len The length of the data. + * @data: The data to convert. + * @len: The length of the data. * - * @return The base-16 string in the ASCII chunked encoding. Must be + * Returns: The base-16 string in the ASCII chunked encoding. Must be * g_free'd when no longer needed. */ gchar *purple_base16_encode_chunked(const guchar *data, gsize len); @@ -272,10 +272,10 @@ /** * Converts a chunk of binary data to its base-64 equivalent. * - * @param data The data to convert. - * @param len The length of the data. + * @data: The data to convert. + * @len: The length of the data. * - * @return The base-64 string in the ASCII encoding. Must be + * Returns: The base-64 string in the ASCII encoding. Must be * g_free'd when no longer needed. * * @see purple_base64_decode() @@ -286,14 +286,14 @@ * Converts an ASCII string of base-64 encoded data to * the binary equivalent. * - * @param str The base-64 string to convert to raw data. - * @param ret_len The length of the returned data. You can + * @str: The base-64 string to convert to raw data. + * @ret_len: The length of the returned data. You can * pass in NULL if you're sure that you know * the length of the decoded data, or if you * know you'll be able to use strlen to * determine the length, etc. * - * @return The raw data. Must be g_free'd when no longer needed. + * Returns: The raw data. Must be g_free'd when no longer needed. * * @see purple_base64_encode() */ @@ -313,10 +313,10 @@ * emails containing non-ASCII characters. Wikipedia has a pretty good * explanation. Also see RFC 2045. * - * @param str The quoted printable ASCII string to convert to raw data. - * @param ret_len The length of the returned data. + * @str: The quoted printable ASCII string to convert to raw data. + * @ret_len: The length of the returned data. * - * @return The readable string. Must be g_free'd when no longer needed. + * Returns: The readable string. Must be g_free'd when no longer needed. */ guchar *purple_quotedp_decode(const char *str, gsize *ret_len); @@ -339,10 +339,10 @@ * question mark. The first piece is the character set, the second * piece is the encoding, and the third piece is the encoded text. * - * @param str The ASCII string, possibly containing any number of + * @str: The ASCII string, possibly containing any number of * encoded-word sections. * - * @return The string, with any encoded-word sections decoded and + * Returns: The string, with any encoded-word sections decoded and * converted to UTF-8. Must be g_free'd when no longer * needed. */ @@ -374,10 +374,10 @@ * abbreviation (as is the case on Unix). As with %z, conversion specifiers * should not be used. * - * @param format The format string, in UTF-8 - * @param tm The time to format, or @c NULL to use the current local time + * @format: The format string, in UTF-8 + * @tm: The time to format, or @c NULL to use the current local time * - * @return The formatted time, in UTF-8. + * Returns: The formatted time, in UTF-8. * * @note @a format is required to be in UTF-8. This differs from strftime(), * where the format is provided in the locale charset. @@ -387,8 +387,8 @@ /** * Gets a string representation of the local timezone offset * - * @param tm The time to get the timezone for - * @param iso TRUE to format the offset according to ISO-8601, FALSE to + * @tm: The time to get the timezone for + * @iso: TRUE to format the offset according to ISO-8601, FALSE to * not substitute 'Z' for 0 offset, and to not separate * hours and minutes with a colon. */ @@ -400,9 +400,9 @@ * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @param tm The time to format, or @c NULL to use the current local time + * @tm: The time to format, or @c NULL to use the current local time * - * @return The date, formatted as per the user's settings. In the USA this + * Returns: The date, formatted as per the user's settings. In the USA this * is something like "02/18/13" */ const char *purple_date_format_short(const struct tm *tm); @@ -413,9 +413,9 @@ * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @param tm The time to format, or @c NULL to use the current local time + * @tm: The time to format, or @c NULL to use the current local time * - * @return The timestamp, formatted as per the user's settings. In the USA + * Returns: The timestamp, formatted as per the user's settings. In the USA * this is something like "02/18/13 15:26:44" */ const char *purple_date_format_long(const struct tm *tm); @@ -426,9 +426,9 @@ * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @param tm The time to format, or @c NULL to use the current local time + * @tm: The time to format, or @c NULL to use the current local time * - * @return The date and time, formatted as per the user's settings. In the + * Returns: The date and time, formatted as per the user's settings. In the * USA this is something like "Mon Feb 18 15:26:44 2013" */ const char *purple_date_format_full(const struct tm *tm); @@ -439,9 +439,9 @@ * The returned string is stored in a static buffer, so the result * should be g_strdup()'d if it's going to be kept. * - * @param tm The time to format, or @c NULL to use the current local time + * @tm: The time to format, or @c NULL to use the current local time * - * @return The time, formatted as per the user's settings. In the USA this + * Returns: The time, formatted as per the user's settings. In the USA this * is something like "15:26:44" */ const char *purple_time_format(const struct tm *tm); @@ -449,14 +449,14 @@ /** * Builds a time_t from the supplied information. * - * @param year The year. - * @param month The month. - * @param day The day. - * @param hour The hour. - * @param min The minute. - * @param sec The second. + * @year: The year. + * @month: The month. + * @day: The day. + * @hour: The hour. + * @min: The minute. + * @sec: The second. * - * @return A time_t. + * Returns: A time_t. */ time_t purple_time_build(int year, int month, int day, int hour, int min, int sec); @@ -469,21 +469,21 @@ * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns * a time_t. * - * @param timestamp The timestamp - * @param utc Assume UTC if no timezone specified - * @param tm If not @c NULL, the caller can get a copy of the + * @timestamp: The timestamp + * @utc: Assume UTC if no timezone specified + * @tm: If not @c NULL, the caller can get a copy of the * struct tm used to calculate the time_t return value. - * @param tz_off If not @c NULL, the caller can get a copy of the + * @tz_off: If not @c NULL, the caller can get a copy of the * timezone offset (from UTC) used to calculate the time_t * return value. Note: Zero is a valid offset. As such, * the value of the macro @c PURPLE_NO_TZ_OFF indicates no * offset was specified (which means that the local * timezone was used in the calculation). - * @param rest If not @c NULL, the caller can get a pointer to the + * @rest: If not @c NULL, the caller can get a pointer to the * part of @a timestamp left over after parsing is * completed, if it's not the end of @a timestamp. * - * @return A time_t. + * Returns: A time_t. */ time_t purple_str_to_time(const char *timestamp, gboolean utc, struct tm *tm, long *tz_off, const char **rest); @@ -491,13 +491,13 @@ /** * Formats a datetime according to a UTS-35 Date Format Pattern. * - * @param format The formatting string, according to UTS #35 + * @format: The formatting string, according to UTS #35 * See http://unicode.org/reports/tr35/ * (NOTE: not all formats are supported) - * @param len The length of the formatting string - * @param tm The time to format, or @c NULL to use the current local time + * @len: The length of the formatting string + * @tm: The time to format, or @c NULL to use the current local time * - * @return The time, formatted as per the user's settings. + * Returns: The time, formatted as per the user's settings. */ char *purple_uts35_to_str(const char *format, size_t len, struct tm *tm); @@ -527,13 +527,13 @@ * in a GData hash table. The names of the attributes are lower-cased * in the hash table, and the name of the tag is case insensitive. * - * @param needle The name of the tag - * @param haystack The null-delimited string to search in - * @param start A pointer to the start of the tag if found - * @param end A pointer to the end of the tag if found - * @param attributes The attributes, if the tag was found. This should + * @needle: The name of the tag + * @haystack: The null-delimited string to search in + * @start: A pointer to the start of the tag if found + * @end: A pointer to the end of the tag if found + * @attributes: The attributes, if the tag was found. This should * be freed with g_datalist_clear(). - * @return TRUE if the tag was found + * Returns: TRUE if the tag was found */ gboolean purple_markup_find_tag(const char *needle, const char *haystack, const char **start, const char **end, @@ -545,22 +545,22 @@ * This is a scary function. See protocols/msn/msn.c and * protocols/yahoo/yahoo_profile.c for example usage. * - * @param str The string to parse. - * @param len The size of str. - * @param user_info The destination PurpleNotifyUserInfo to which the new + * @str: The string to parse. + * @len: The size of str. + * @user_info: The destination PurpleNotifyUserInfo to which the new * field info should be added. - * @param start_token The beginning token. - * @param skip The number of characters to skip after the + * @start_token: The beginning token. + * @skip: The number of characters to skip after the * start token. - * @param end_token The ending token. - * @param check_value The value that the last character must meet. - * @param no_value_token The token indicating no value is given. - * @param display_name The short descriptive name to display for this token. - * @param is_link TRUE if this should be a link, or FALSE otherwise. - * @param link_prefix The prefix for the link. - * @param format_cb A callback to format the value before adding it. + * @end_token: The ending token. + * @check_value: The value that the last character must meet. + * @no_value_token: The token indicating no value is given. + * @display_name: The short descriptive name to display for this token. + * @is_link: TRUE if this should be a link, or FALSE otherwise. + * @link_prefix: The prefix for the link. + * @format_cb: A callback to format the value before adding it. * - * @return TRUE if successful, or FALSE otherwise. + * Returns: TRUE if successful, or FALSE otherwise. */ gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info, const char *start_token, int skip, @@ -573,9 +573,9 @@ /** * Converts HTML markup to XHTML. * - * @param html The HTML markup. - * @param dest_xhtml The destination XHTML output. - * @param dest_plain The destination plain-text output. + * @html: The HTML markup. + * @dest_xhtml: The destination XHTML output. + * @dest_plain: The destination plain-text output. */ void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml, char **dest_plain); @@ -583,9 +583,9 @@ /** * Strips HTML tags from a string. * - * @param str The string to strip HTML from. + * @str: The string to strip HTML from. * - * @return The new string without HTML. You must g_free this string + * Returns: The new string without HTML. You must g_free this string * when finished with it. */ char *purple_markup_strip_html(const char *str); @@ -593,9 +593,9 @@ /** * Adds the necessary HTML code to turn URIs into HTML links in a string. * - * @param str The string to linkify. + * @str: The string to linkify. * - * @return The new string with all URIs surrounded in standard + * Returns: The new string with all URIs surrounded in standard * HTML <a href="whatever"></a> tags. You must g_free this * string when finished with it. */ @@ -611,9 +611,9 @@ * * purple_unescape_html() is similar, but also converts "<br>" into "\n". * - * @param text The string in which to unescape any HTML entities + * @text: The string in which to unescape any HTML entities * - * @return The text with HTML entities literalized. You must g_free + * Returns: The text with HTML entities literalized. You must g_free * this string when finished with it. * * @see purple_unescape_html() @@ -624,9 +624,9 @@ * Unescapes HTML entities to their literal characters and converts * "<br>" to "\n". See purple_unescape_text() for more details. * - * @param html The string in which to unescape any HTML entities + * @html: The string in which to unescape any HTML entities * - * @return The text with HTML entities literalized. You must g_free + * Returns: The text with HTML entities literalized. You must g_free * this string when finished with it. * * @see purple_unescape_text() @@ -646,13 +646,13 @@ * when used with other UI's. libpurple users are encouraged to report and * work out any problems encountered. * - * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string. + * @str: The input NUL terminated, HTML, UTF-8 (or ASCII) string. * @param x The character offset into an unformatted version of str to * begin at. * @param y The character offset (into an unformatted vesion of str) of * one past the last character to include in the slice. * - * @return The HTML slice of string, with all formatting retained. + * Returns: The HTML slice of string, with all formatting retained. */ char *purple_markup_slice(const char *str, guint x, guint y); @@ -662,8 +662,8 @@ * a '>' sometime after that. If there is no '>' and the string is * not NUL terminated, this function can be expected to segfault. * - * @param tag The string starting a HTML tag. - * @return A string containing the name of the tag. + * @tag: The string starting a HTML tag. + * Returns: A string containing the name of the tag. */ char *purple_markup_get_tag_name(const char *tag); @@ -678,10 +678,10 @@ * the string for the entity, does not replace the entity, and does not * return a newly allocated string. * - * @param text A string containing an HTML entity. - * @param length If not @c NULL, the string length of the entity is stored in this location. + * @text: A string containing an HTML entity. + * @length: If not @c NULL, the string length of the entity is stored in this location. * - * @return A constant string containing the character representation of the given entity. + * Returns: A constant string containing the character representation of the given entity. */ const char * purple_markup_unescape_entity(const char *text, int *length); @@ -696,19 +696,19 @@ * On error or if the requested property was not found, the function returns * @c NULL. * - * @param style A string containing the inline CSS text. - * @param opt The requested CSS property. + * @style: A string containing the inline CSS text. + * @opt: The requested CSS property. * - * @return The value of the requested CSS property. + * Returns: The value of the requested CSS property. */ char * purple_markup_get_css_property(const gchar *style, const gchar *opt); /** * Check if the given HTML contains RTL text. * - * @param html The HTML text. + * @html: The HTML text. * - * @return TRUE if the text contains RTL text, FALSE otherwise. + * Returns: TRUE if the text contains RTL text, FALSE otherwise. */ gboolean purple_markup_is_rtl(const char *html); @@ -723,7 +723,7 @@ /** * Returns the user's home directory. * - * @return The user's home directory. + * Returns: The user's home directory. * * @see purple_user_dir() */ @@ -733,7 +733,7 @@ * Returns the purple settings directory in the user's home directory. * This is usually ~/.purple * - * @return The purple settings directory. + * Returns: The purple settings directory. * * @see purple_home_dir() */ @@ -741,7 +741,7 @@ /** * Define a custom purple settings directory, overriding the default (user's home directory/.purple) - * @param dir The custom settings directory + * @dir: The custom settings directory */ void purple_util_set_user_dir(const char *dir); @@ -749,11 +749,11 @@ * Builds a complete path from the root, making any directories along * the path which do not already exist. * - * @param path The path you wish to create. Note that it must start + * @path: The path you wish to create. Note that it must start * from the root or this function will fail. - * @param mode Unix-style permissions for this directory. + * @mode: Unix-style permissions for this directory. * - * @return 0 for success, nonzero on any error. + * Returns: 0 for success, nonzero on any error. */ int purple_build_dir(const char *path, int mode); @@ -765,12 +765,12 @@ * obtained using purple_xmlnode_to_formatted_str. However, this function * should work fine for saving binary files as well. * - * @param filename The basename of the file to write in the purple_user_dir. - * @param data A null-terminated string of data to write. - * @param size The size of the data to save. If data is + * @filename: The basename of the file to write in the purple_user_dir. + * @data: A null-terminated string of data to write. + * @size: The size of the data to save. If data is * null-terminated you can pass in -1. * - * @return TRUE if the file was written successfully. FALSE otherwise. + * Returns: TRUE if the file was written successfully. FALSE otherwise. */ gboolean purple_util_write_data_to_file(const char *filename, const char *data, gssize size); @@ -780,12 +780,12 @@ * * This exists for Glib backwards compatibility reasons. * - * @param filename_full Filename to write to - * @param data A null-terminated string of data to write. - * @param size The size of the data to save. If data is + * @filename_full: Filename to write to + * @data: A null-terminated string of data to write. + * @size: The size of the data to save. If data is * null-terminated you can pass in -1. * - * @return TRUE if the file was written successfully. FALSE otherwise. + * Returns: TRUE if the file was written successfully. FALSE otherwise. * * @todo Remove this function (use g_file_set_contents instead) when 3.0.0 * rolls around. @@ -800,13 +800,13 @@ * PurpleXmlNode tree structure. This is intended to be used to read * Purple's configuration xml files (prefs.xml, pounces.xml, etc.) * - * @param filename The basename of the file to open in the purple_user_dir. - * @param description A very short description of the contents of this + * @filename: The basename of the file to open in the purple_user_dir. + * @description: A very short description of the contents of this * file. This is used in error messages shown to the * user when the file can not be opened. For example, * "preferences," or "buddy pounces." * - * @return An PurpleXmlNode tree of the contents of the given file. Or NULL, if + * Returns: An PurpleXmlNode tree of the contents of the given file. Or NULL, if * the file does not exist or there was an error reading the file. */ PurpleXmlNode *purple_util_read_xml_from_file(const char *filename, @@ -823,26 +823,26 @@ * done, as well as freeing the space pointed to by @a path with * g_free(). * - * @param path The returned path to the temp file. - * @param binary Text or binary, for platforms where it matters. + * @path: The returned path to the temp file. + * @binary: Text or binary, for platforms where it matters. * - * @return A file pointer to the temporary file, or @c NULL on failure. + * Returns: A file pointer to the temporary file, or @c NULL on failure. */ FILE *purple_mkstemp(char **path, gboolean binary); /** * Returns an extension corresponding to the image data's file type. * - * @param data A pointer to the image data - * @param len The length of the image data + * @data: A pointer to the image data + * @len: The length of the image data * - * @return The appropriate extension, or "icon" if unknown. + * Returns: The appropriate extension, or "icon" if unknown. */ const char * purple_util_get_image_extension(gconstpointer data, size_t len); /** - * @return A hex encoded version of the SHA-1 hash of the data passed + * Returns: A hex encoded version of the SHA-1 hash of the data passed * in with the correct file extention appended. The file * extension is determined by calling * purple_util_get_image_extension(). This return value must @@ -861,48 +861,48 @@ /** * Checks if the given program name is valid and executable. * - * @param program The file name of the application. + * @program: The file name of the application. * - * @return TRUE if the program is runable. + * Returns: TRUE if the program is runable. */ gboolean purple_program_is_valid(const char *program); /** * Check if running GNOME. * - * @return TRUE if running GNOME, FALSE otherwise. + * Returns: TRUE if running GNOME, FALSE otherwise. */ gboolean purple_running_gnome(void); /** * Check if running KDE. * - * @return TRUE if running KDE, FALSE otherwise. + * Returns: TRUE if running KDE, FALSE otherwise. */ gboolean purple_running_kde(void); /** * Check if running OS X. * - * @return TRUE if running OS X, FALSE otherwise. + * Returns: TRUE if running OS X, FALSE otherwise. */ gboolean purple_running_osx(void); /** * Returns the IP address from a socket file descriptor. * - * @param fd The socket file descriptor. + * @fd: The socket file descriptor. * - * @return The IP address, or @c NULL on error. + * Returns: The IP address, or @c NULL on error. */ char *purple_fd_get_ip(int fd); /** * Returns the address family of a socket. * - * @param fd The socket file descriptor. + * @fd: The socket file descriptor. * - * @return The address family of the socket (AF_INET, AF_INET6, etc) or -1 + * Returns: The address family of the socket (AF_INET, AF_INET6, etc) or -1 * on error. */ int purple_socket_get_family(int fd); @@ -913,8 +913,8 @@ * This is the case for IPv4 sockets and, on some systems, IPv6 sockets * (due to the IPv4-mapped address functionality). * - * @param fd The socket file descriptor - * @return TRUE if a socket can speak IPv4. + * @fd: The socket file descriptor + * Returns: TRUE if a socket can speak IPv4. */ gboolean purple_socket_speaks_ipv4(int fd); @@ -932,10 +932,10 @@ * Unlike strcmp(), this function will not crash if one or both of the * strings are @c NULL. * - * @param left A string - * @param right A string to compare with left + * @left: A string + * @right: A string to compare with left * - * @return @c TRUE if the strings are the same, else @c FALSE. + * Returns: @c TRUE if the strings are the same, else @c FALSE. */ gboolean purple_strequal(const gchar *left, const gchar *right); @@ -947,14 +947,14 @@ * g_strdup() it. Also, calling normalize() twice in the same line * will lead to problems. * - * @param account The account the string belongs to, or NULL if you do + * @account: The account the string belongs to, or NULL if you do * not know the account. If you use NULL, the string * will still be normalized, but if the protocol uses a * custom normalization function then the string may * not be normalized correctly. - * @param str The string to normalize. + * @str: The string to normalize. * - * @return A pointer to the normalized version stored in a static buffer. + * Returns: A pointer to the normalized version stored in a static buffer. */ const char *purple_normalize(const PurpleAccount *account, const char *str); @@ -965,20 +965,20 @@ * function "normalize." It returns a lowercase and UTF-8 * normalized version of the string. * - * @param account The account the string belongs to. - * @param str The string to normalize. + * @account: The account the string belongs to. + * @str: The string to normalize. * - * @return A pointer to the normalized version stored in a static buffer. + * Returns: A pointer to the normalized version stored in a static buffer. */ const char *purple_normalize_nocase(const PurpleAccount *account, const char *str); /** * Checks, if a string is valid. * - * @param protocol The protocol the string belongs to. - * @param str The string to validate. + * @protocol: The protocol the string belongs to. + * @str: The string to validate. * - * @return TRUE, if string is valid, otherwise FALSE. + * Returns: TRUE, if string is valid, otherwise FALSE. */ gboolean purple_validate(const PurpleProtocol *protocol, const char *str); @@ -989,7 +989,7 @@ * @param s The string to check. * @param p The prefix in question. * - * @return TRUE if p is a prefix of s, otherwise FALSE. + * Returns: TRUE if p is a prefix of s, otherwise FALSE. */ gboolean purple_str_has_prefix(const char *s, const char *p); @@ -1000,7 +1000,7 @@ * @param s The string to check. * @param x The suffix in question. * - * @return TRUE if x is a a suffix of s, otherwise FALSE. + * Returns: TRUE if x is a a suffix of s, otherwise FALSE. */ gboolean purple_str_has_suffix(const char *s, const char *x); @@ -1008,18 +1008,18 @@ * Duplicates a string and replaces all newline characters from the * source string with HTML linebreaks. * - * @param src The source string. + * @src: The source string. * - * @return The new string. Must be g_free'd by the caller. + * Returns: The new string. Must be g_free'd by the caller. */ gchar *purple_strdup_withhtml(const gchar *src); /** * Ensures that all linefeeds have a matching carriage return. * - * @param str The source string. + * @str: The source string. * - * @return The string with carriage returns. + * Returns: The string with carriage returns. */ char *purple_str_add_cr(const char *str); @@ -1031,8 +1031,8 @@ * Example usage: * purple_str_strip_char(my_dumb_string, '\n'); * - * @param str The string to strip characters from. - * @param thechar The character to strip from the given string. + * @str: The string to strip characters from. + * @thechar: The character to strip from the given string. */ void purple_str_strip_char(char *str, char thechar); @@ -1041,9 +1041,9 @@ * with another. This happens inline (the original string IS * modified). * - * @param string The string from which to replace stuff. - * @param delimiter The character you want replaced. - * @param replacement The character you want inserted in place + * @string: The string from which to replace stuff. + * @delimiter: The character you want replaced. + * @replacement: The character you want inserted in place * of the delimiting character. */ void purple_util_chrreplace(char *string, char delimiter, @@ -1053,12 +1053,12 @@ * Given a string, this replaces one substring with another * and returns a newly allocated string. * - * @param string The string from which to replace stuff. - * @param delimiter The substring you want replaced. - * @param replacement The substring you want inserted in place + * @string: The string from which to replace stuff. + * @delimiter: The substring you want replaced. + * @replacement: The substring you want inserted in place * of the delimiting substring. * - * @return A new string, after performing the substitution. + * Returns: A new string, after performing the substitution. * free this with g_free(). */ gchar *purple_strreplace(const char *string, const char *delimiter, @@ -1070,9 +1070,9 @@ * the corresponding numerical character reference, and returns a newly * allocated string. * - * @param in The string which might contain utf-8 substrings + * @in: The string which might contain utf-8 substrings * - * @return A new string, with utf-8 replaced with numerical character + * Returns: A new string, with utf-8 replaced with numerical character * references, free this with g_free() */ char *purple_utf8_ncr_encode(const char *in); @@ -1083,9 +1083,9 @@ * in that string with the corresponding actual utf-8 substrings, * and returns a newly allocated string. * - * @param in The string which might contain numerical character references. + * @in: The string which might contain numerical character references. * - * @return A new string, with numerical character references + * Returns: A new string, with numerical character references * replaced with actual utf-8, free this with g_free(). */ char *purple_utf8_ncr_decode(const char *in); @@ -1095,12 +1095,12 @@ * Given a string, this replaces one substring with another * ignoring case and returns a newly allocated string. * - * @param string The string from which to replace stuff. - * @param delimiter The substring you want replaced. - * @param replacement The substring you want inserted in place + * @string: The string from which to replace stuff. + * @delimiter: The substring you want replaced. + * @replacement: The substring you want inserted in place * of the delimiting substring. * - * @return A new string, after performing the substitution. + * Returns: A new string, after performing the substitution. * free this with g_free(). */ gchar *purple_strcasereplace(const char *string, const char *delimiter, @@ -1110,10 +1110,10 @@ * This is like strstr, except that it ignores ASCII case in * searching for the substring. * - * @param haystack The string to search in. - * @param needle The substring to find. + * @haystack: The string to search in. + * @needle: The substring to find. * - * @return the location of the substring if found, or NULL if not + * Returns: the location of the substring if found, or NULL if not */ const char *purple_strcasestr(const char *haystack, const char *needle); @@ -1121,18 +1121,18 @@ * Returns a string representing a filesize in the appropriate * units (MB, KB, GB, etc.) * - * @param size The size + * @size: The size * - * @return The string in units form. This must be freed. + * Returns: The string in units form. This must be freed. */ char *purple_str_size_to_units(goffset size); /** * Converts seconds into a human-readable form. * - * @param sec The seconds. + * @sec: The seconds. * - * @return A human-readable form, containing days, hours, minutes, and + * Returns: A human-readable form, containing days, hours, minutes, and * seconds. */ char *purple_str_seconds_to_string(guint sec); @@ -1144,19 +1144,19 @@ * changed into two backslashes (\\\\). The returned, newly allocated * string can be outputted to the console, and must be g_free()d. * - * @param binary A string of random data, possibly with embedded NULs + * @binary: A string of random data, possibly with embedded NULs * and such. - * @param len The length in bytes of the input string. Must not be 0. + * @len: The length in bytes of the input string. Must not be 0. * - * @return A newly allocated ASCIIZ string. + * Returns: A newly allocated ASCIIZ string. */ char *purple_str_binary_to_ascii(const unsigned char *binary, guint len); /** * Calculates UTF-16 string size (in bytes). * - * @param str String to check. - * @return Number of bytes (including NUL character) that string occupies. + * @str: String to check. + * Returns: Number of bytes (including NUL character) that string occupies. */ size_t purple_utf16_size(const gunichar2 *str); @@ -1165,7 +1165,7 @@ * * It should be used to free sensitive data, like passwords. * - * @param str A NUL-terminated string to free, or a NULL-pointer. + * @str: A NUL-terminated string to free, or a NULL-pointer. */ void purple_str_wipe(gchar *str); @@ -1174,7 +1174,7 @@ * * It should be used to free sensitive data, like passwords. * - * @param str A NUL-terminated string to free, or a NULL-pointer. + * @str: A NUL-terminated string to free, or a NULL-pointer. */ void purple_utf16_wipe(gunichar2 *str); @@ -1193,9 +1193,9 @@ * * This will change hex codes and such to their ascii equivalents. * - * @param str The string to translate. + * @str: The string to translate. * - * @return The resulting string. + * Returns: The resulting string. */ const char *purple_url_decode(const char *str); @@ -1204,18 +1204,18 @@ * * This will change non-alphanumeric characters to hex codes. * - * @param str The string to translate. + * @str: The string to translate. * - * @return The resulting string. + * Returns: The resulting string. */ const char *purple_url_encode(const char *str); /** * Checks if the given email address is syntactically valid. * - * @param address The email address to validate. + * @address: The email address to validate. * - * @return True if the email address is syntactically correct. + * Returns: True if the email address is syntactically correct. */ gboolean purple_email_is_valid(const char *address); @@ -1226,27 +1226,27 @@ * purple_ipv4_address_is_valid(), or for an IPv6 address use * purple_ipv6_address_is_valid(). * - * @param ip The IP address to validate. + * @ip: The IP address to validate. * - * @return True if the IP address is syntactically correct. + * Returns: True if the IP address is syntactically correct. */ gboolean purple_ip_address_is_valid(const char *ip); /** * Checks if the given IP address is a syntactically valid IPv4 address. * - * @param ip The IP address to validate. + * @ip: The IP address to validate. * - * @return True if the IP address is syntactically correct. + * Returns: True if the IP address is syntactically correct. */ gboolean purple_ipv4_address_is_valid(const char *ip); /** * Checks if the given IP address is a syntactically valid IPv6 address. * - * @param ip The IP address to validate. + * @ip: The IP address to validate. * - * @return True if the IP address is syntactically correct. + * Returns: True if the IP address is syntactically correct. */ gboolean purple_ipv6_address_is_valid(const char *ip); @@ -1254,9 +1254,9 @@ * This function extracts a list of URIs from the a "text/uri-list" * string. It was "borrowed" from gnome_uri_list_extract_uris * - * @param uri_list An uri-list in the standard format. + * @uri_list: An uri-list in the standard format. * - * @return A GList containing strings allocated with g_malloc + * Returns: A GList containing strings allocated with g_malloc * that have been splitted from uri-list. */ GList *purple_uri_list_extract_uris(const gchar *uri_list); @@ -1266,9 +1266,9 @@ * "text/uri-list" string. It was "borrowed" from * gnome_uri_list_extract_filenames * - * @param uri_list A uri-list in the standard format. + * @uri_list: A uri-list in the standard format. * - * @return A GList containing strings allocated with g_malloc that + * Returns: A GList containing strings allocated with g_malloc that * contain the filenames in the uri-list. Note that unlike * purple_uri_list_extract_uris() function, this will discard * any non-file uri from the result value. @@ -1287,9 +1287,9 @@ * * This function checks the locale and tries sane defaults. * - * @param str The source string. + * @str: The source string. * - * @return The UTF-8 string, or @c NULL if it could not be converted. + * Returns: The UTF-8 string, or @c NULL if it could not be converted. */ gchar *purple_utf8_try_convert(const char *str); @@ -1298,9 +1298,9 @@ * invalid characters with a filler character (currently hardcoded to * '?'). * - * @param str The source string. + * @str: The source string. * - * @return A valid UTF-8 string. + * Returns: A valid UTF-8 string. */ gchar *purple_utf8_salvage(const char *str); @@ -1311,9 +1311,9 @@ * * The returned string must be freed by the caller. * - * @param str A valid UTF-8 string. + * @str: A valid UTF-8 string. * - * @return A newly allocated UTF-8 string without the unprintable characters. + * Returns: A newly allocated UTF-8 string without the unprintable characters. */ gchar *purple_utf8_strip_unprintables(const gchar *str); @@ -1322,9 +1322,9 @@ * then converts the result to UTF-8. This function is analogous to * g_strerror(). * - * @param errnum The error code. + * @errnum: The error code. * - * @return The UTF-8 error message. + * Returns: The UTF-8 error message. */ const gchar *purple_gai_strerror(gint errnum); @@ -1337,7 +1337,7 @@ * @param a The first string. * @param b The second string. * - * @return -1 if @a a is less than @a b. + * Returns: -1 if @a a is less than @a b. * 0 if @a a is equal to @a b. * 1 if @a a is greater than @a b. */ @@ -1348,10 +1348,10 @@ * must be contained in the haystack string and not be immediately * preceded or immediately followed by another alpha-numeric character. * - * @param haystack The string to search in. - * @param needle The substring to find. + * @haystack: The string to search in. + * @needle: The substring to find. * - * @return TRUE if haystack has the word, otherwise FALSE + * Returns: TRUE if haystack has the word, otherwise FALSE */ gboolean purple_utf8_has_word(const char *haystack, const char *needle); @@ -1360,18 +1360,18 @@ * tries to convert the UTF-8 message to user's locale. If this * is not possible, the original UTF-8 text will be printed. * - * @param filestream The file stream (e.g. STDOUT or STDERR) - * @param message The message to print. + * @filestream: The file stream (e.g. STDOUT or STDERR) + * @message: The message to print. */ void purple_print_utf8_to_console(FILE *filestream, char *message); /** * Checks for messages starting (post-HTML) with "/me ", including the space. * - * @param message The message to check - * @param len The message length, or -1 + * @message: The message to check + * @len: The message length, or -1 * - * @return TRUE if it starts with "/me ", and it has been removed, otherwise + * Returns: TRUE if it starts with "/me ", and it has been removed, otherwise * FALSE */ gboolean purple_message_meify(char *message, gssize len); @@ -1380,9 +1380,9 @@ * Removes the underscore characters from a string used identify the mnemonic * character. * - * @param in The string to strip + * @in: The string to strip * - * @return The stripped string + * Returns: The stripped string */ char *purple_text_strip_mnemonic(const char *in); @@ -1395,7 +1395,7 @@ * * @param x The number to add 8 to. * - * @return x + 8 + * Returns: x + 8 */ #define purple_add_eight(x) ((x)+8) @@ -1404,27 +1404,27 @@ * * This will change hex codes and such to their ascii equivalents. * - * @param str The string to translate. + * @str: The string to translate. * - * @return The resulting string. + * Returns: The resulting string. */ const char *purple_unescape_filename(const char *str); /** * Escapes filesystem-unfriendly characters from a filename * - * @param str The string to translate. + * @str: The string to translate. * - * @return The resulting string. + * Returns: The resulting string. */ const char *purple_escape_filename(const char *str); /** * Escapes javascript-unfriendly substrings from a string. * - * @param str The string to escape. + * @str: The string to escape. * - * @return The javascript-safe string (must be g_free'd after use). + * Returns: The javascript-safe string (must be g_free'd after use). */ gchar * purple_escape_js(const gchar *str); @@ -1439,14 +1439,14 @@ * Gets the host name of the machine. If it not possible to determine the * host name, "localhost" is returned * - * @constreturn The hostname + * Returns: (TODO const): The hostname */ const gchar *purple_get_host_name(void); /** * Returns a type 4 (random) UUID * - * @return A UUID, caller is responsible for freeing it + * Returns: A UUID, caller is responsible for freeing it */ gchar *purple_uuid_random(void); @@ -1455,32 +1455,32 @@ * * Function designed to be used as a GDestroyNotify callback. * - * @param data A pointer to variable, which should be set to NULL. + * @data: A pointer to variable, which should be set to NULL. */ void purple_callback_set_zero(gpointer data); /** * Creates a new GValue of the specified type. * - * @param type The type of data to be held by the GValue + * @type: The type of data to be held by the GValue * - * @return The created GValue + * Returns: The created GValue */ GValue *purple_value_new(GType type); /** * Duplicates a GValue. * - * @param value The GValue to duplicate + * @value: The GValue to duplicate * - * @return The duplicated GValue + * Returns: The duplicated GValue */ GValue *purple_value_dup(GValue *value); /** * Frees a GValue. * - * @param value The GValue to free. + * @value: The GValue to free. */ void purple_value_free(GValue *value); @@ -1489,14 +1489,14 @@ * * See RFC 2617 for more information. * - * @param algorithm The hash algorithm to use - * @param username The username provided by the user - * @param realm The authentication realm provided by the server - * @param password The password provided by the user - * @param nonce The nonce provided by the server - * @param client_nonce The nonce provided by the client + * @algorithm: The hash algorithm to use + * @username: The username provided by the user + * @realm: The authentication realm provided by the server + * @password: The password provided by the user + * @nonce: The nonce provided by the server + * @client_nonce: The nonce provided by the client * - * @return The session key, or @c NULL if an error occurred. + * Returns: The session key, or @c NULL if an error occurred. */ gchar *purple_http_digest_calculate_session_key( const gchar *algorithm, const gchar *username, @@ -1507,17 +1507,17 @@ * * See RFC 2617 for more information. * - * @param algorithm The hash algorithm to use - * @param method The HTTP method in use - * @param digest_uri The URI from the initial request - * @param qop The "quality of protection" - * @param entity The entity body - * @param nonce The nonce provided by the server - * @param nonce_count The nonce count - * @param client_nonce The nonce provided by the client - * @param session_key The session key from purple_cipher_http_digest_calculate_session_key() + * @algorithm: The hash algorithm to use + * @method: The HTTP method in use + * @digest_uri: The URI from the initial request + * @qop: The "quality of protection" + * @entity: The entity body + * @nonce: The nonce provided by the server + * @nonce_count: The nonce count + * @client_nonce: The nonce provided by the client + * @session_key: The session key from purple_cipher_http_digest_calculate_session_key() * - * @return The hashed response, or @c NULL if an error occurred. + * Returns: The hashed response, or @c NULL if an error occurred. */ gchar *purple_http_digest_calculate_response( const gchar *algorithm, const gchar *method,
--- a/libpurple/version.h.in Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/version.h.in Wed Jan 29 05:28:33 2014 +0530 @@ -43,11 +43,11 @@ * Checks that the libpurple version is compatible with the requested * version * - * @param required_major: the required major version. - * @param required_minor: the required minor version. - * @param required_micro: the required micro version. + * @required_major: the required major version. + * @required_minor: the required minor version. + * @required_micro: the required micro version. * - * @return NULL if the versions are compatible, or a string describing + * Returns: NULL if the versions are compatible, or a string describing * the version mismatch if not compatible. */ const char *purple_version_check(guint required_major, guint required_minor, guint required_micro);
--- a/libpurple/whiteboard.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/whiteboard.h Wed Jan 29 05:28:33 2014 +0530 @@ -127,231 +127,231 @@ /** * Sets the UI operations * - * @param ops The UI operations to set + * @ops: The UI operations to set */ void purple_whiteboard_set_ui_ops(PurpleWhiteboardUiOps *ops); /** * Sets the protocol operations for a whiteboard * - * @param wb The whiteboard for which to set the protocol operations - * @param ops The protocol operations to set + * @wb: The whiteboard for which to set the protocol operations + * @ops: The protocol operations to set */ void purple_whiteboard_set_protocol_ops(PurpleWhiteboard *wb, PurpleWhiteboardOps *ops); /** * Creates a new whiteboard * - * @param account The account. - * @param who Who you're drawing with. - * @param state The state. + * @account: The account. + * @who: Who you're drawing with. + * @state: The state. * - * @return The new whiteboard + * Returns: The new whiteboard */ PurpleWhiteboard *purple_whiteboard_new(PurpleAccount *account, const char *who, int state); /** * Returns the whiteboard's account. * - * @param wb The whiteboard. + * @wb: The whiteboard. * - * @return The whiteboard's account. + * Returns: The whiteboard's account. */ PurpleAccount *purple_whiteboard_get_account(const PurpleWhiteboard *wb); /** * Return who you're drawing with. * - * @param wb The whiteboard + * @wb: The whiteboard * - * @return Who you're drawing with. + * Returns: Who you're drawing with. */ const char *purple_whiteboard_get_who(const PurpleWhiteboard *wb); /** * Set the state of the whiteboard. * - * @param wb The whiteboard. - * @param state The state + * @wb: The whiteboard. + * @state: The state */ void purple_whiteboard_set_state(PurpleWhiteboard *wb, int state); /** * Return the state of the whiteboard. * - * @param wb The whiteboard. + * @wb: The whiteboard. * - * @return The state of the whiteboard. + * Returns: The state of the whiteboard. */ int purple_whiteboard_get_state(const PurpleWhiteboard *wb); /** * Starts a whiteboard * - * @param wb The whiteboard. + * @wb: The whiteboard. */ void purple_whiteboard_start(PurpleWhiteboard *wb); /** * Finds a whiteboard from an account and user. * - * @param account The account. - * @param who The user. + * @account: The account. + * @who: The user. * - * @return The whiteboard if found, otherwise @c NULL. + * Returns: The whiteboard if found, otherwise @c NULL. */ PurpleWhiteboard *purple_whiteboard_get_session(const PurpleAccount *account, const char *who); /** * Destorys a drawing list for a whiteboard * - * @param draw_list The drawing list. + * @draw_list: The drawing list. */ void purple_whiteboard_draw_list_destroy(GList *draw_list); /** * Gets the dimension of a whiteboard. * - * @param wb The whiteboard. - * @param width The width to be set. - * @param height The height to be set. + * @wb: The whiteboard. + * @width: The width to be set. + * @height: The height to be set. * - * @return TRUE if the values of width and height were set. + * Returns: TRUE if the values of width and height were set. */ gboolean purple_whiteboard_get_dimensions(const PurpleWhiteboard *wb, int *width, int *height); /** * Sets the dimensions for a whiteboard. * - * @param wb The whiteboard. - * @param width The width. - * @param height The height. + * @wb: The whiteboard. + * @width: The width. + * @height: The height. */ void purple_whiteboard_set_dimensions(PurpleWhiteboard *wb, int width, int height); /** * Draws a point on a whiteboard. * - * @param wb The whiteboard. + * @wb: The whiteboard. * @param x The x coordinate. * @param y The y coordinate. - * @param color The color to use. - * @param size The brush size. + * @color: The color to use. + * @size: The brush size. */ void purple_whiteboard_draw_point(PurpleWhiteboard *wb, int x, int y, int color, int size); /** * Send a list of points to draw to the buddy. * - * @param wb The whiteboard - * @param list A GList of points + * @wb: The whiteboard + * @list: A GList of points */ void purple_whiteboard_send_draw_list(PurpleWhiteboard *wb, GList *list); /** * Draws a line on a whiteboard * - * @param wb The whiteboard. - * @param x1 The top-left x coordinate. - * @param y1 The top-left y coordinate. - * @param x2 The bottom-right x coordinate. - * @param y2 The bottom-right y coordinate. - * @param color The color to use. - * @param size The brush size. + * @wb: The whiteboard. + * @x1: The top-left x coordinate. + * @y1: The top-left y coordinate. + * @x2: The bottom-right x coordinate. + * @y2: The bottom-right y coordinate. + * @color: The color to use. + * @size: The brush size. */ void purple_whiteboard_draw_line(PurpleWhiteboard *wb, int x1, int y1, int x2, int y2, int color, int size); /** * Clears a whiteboard * - * @param wb The whiteboard. + * @wb: The whiteboard. */ void purple_whiteboard_clear(PurpleWhiteboard *wb); /** * Sends a request to the buddy to clear the whiteboard. * - * @param wb The whiteboard + * @wb: The whiteboard */ void purple_whiteboard_send_clear(PurpleWhiteboard *wb); /** * Sends a request to change the size and color of the brush. * - * @param wb The whiteboard - * @param size The size of the brush - * @param color The color of the brush + * @wb: The whiteboard + * @size: The size of the brush + * @color: The color of the brush */ void purple_whiteboard_send_brush(PurpleWhiteboard *wb, int size, int color); /** * Gets the size and color of the brush. * - * @param wb The whiteboard - * @param size The size of the brush - * @param color The color of the brush + * @wb: The whiteboard + * @size: The size of the brush + * @color: The color of the brush * - * @return TRUE if the size and color were set. + * Returns: TRUE if the size and color were set. */ gboolean purple_whiteboard_get_brush(const PurpleWhiteboard *wb, int *size, int *color); /** * Sets the size and color of the brush. * - * @param wb The whiteboard - * @param size The size of the brush - * @param color The color of the brush + * @wb: The whiteboard + * @size: The size of the brush + * @color: The color of the brush */ void purple_whiteboard_set_brush(PurpleWhiteboard *wb, int size, int color); /** * Return the drawing list. * - * @param wb The whiteboard. + * @wb: The whiteboard. * - * @return The drawing list + * Returns: The drawing list */ GList *purple_whiteboard_get_draw_list(const PurpleWhiteboard *wb); /** * Set the drawing list. * - * @param wb The whiteboard - * @param draw_list The drawing list. + * @wb: The whiteboard + * @draw_list: The drawing list. */ void purple_whiteboard_set_draw_list(PurpleWhiteboard *wb, GList* draw_list); /** * Sets the protocol data for a whiteboard. * - * @param wb The whiteboard. - * @param proto_data The protocol data to set for the whiteboard. + * @wb: The whiteboard. + * @proto_data: The protocol data to set for the whiteboard. */ void purple_whiteboard_set_protocol_data(PurpleWhiteboard *wb, gpointer proto_data); /** * Gets the protocol data for a whiteboard. * - * @param wb The whiteboard. + * @wb: The whiteboard. * - * @return The protocol data for the whiteboard. + * Returns: The protocol data for the whiteboard. */ gpointer purple_whiteboard_get_protocol_data(const PurpleWhiteboard *wb); /** * Set the UI data associated with this whiteboard. * - * @param wb The whiteboard. - * @param ui_data A pointer to associate with this whiteboard. + * @wb: The whiteboard. + * @ui_data: A pointer to associate with this whiteboard. */ void purple_whiteboard_set_ui_data(PurpleWhiteboard *wb, gpointer ui_data); /** * Get the UI data associated with this whiteboard. * - * @param wb The whiteboard.. + * @wb: The whiteboard.. * - * @return The UI data associated with this whiteboard. This is a + * Returns: The UI data associated with this whiteboard. This is a * convenience field provided to the UIs--it is not * used by the libpurple core. */
--- a/libpurple/xfer.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/xfer.h Wed Jan 29 05:28:33 2014 +0530 @@ -91,11 +91,11 @@ * UI op to write data received from the protocol. The UI must deal with the * entire buffer and return size, or it is treated as an error. * - * @param xfer The file transfer structure - * @param buffer The buffer to write - * @param size The size of the buffer + * @xfer: The file transfer structure + * @buffer: The buffer to write + * @size: The size of the buffer * - * @return size if the write was successful, or a value between 0 and + * Returns: size if the write was successful, or a value between 0 and * size on error. */ gssize (*ui_write)(PurpleXfer *xfer, const guchar *buffer, gssize size); @@ -103,12 +103,12 @@ /** * UI op to read data to send to the protocol for a file transfer. * - * @param xfer The file transfer structure - * @param buffer A pointer to a buffer. The UI must allocate this buffer. + * @xfer: The file transfer structure + * @buffer: A pointer to a buffer. The UI must allocate this buffer. * libpurple will free the data. - * @param size The maximum amount of data to put in the buffer. + * @size: The maximum amount of data to put in the buffer. * - * @returns The amount of data in the buffer, 0 if nothing is available, + * Returns:s The amount of data in the buffer, 0 if nothing is available, * and a negative value if an error occurred and the transfer * should be cancelled (libpurple will cancel). */ @@ -120,16 +120,16 @@ * * This MUST be implemented if read and write are implemented. * - * @param xfer The file transfer structure - * @param buffer A pointer to the beginning of the unwritten data. - * @param size The amount of unwritten data. + * @xfer: The file transfer structure + * @buffer: A pointer to the beginning of the unwritten data. + * @size: The amount of unwritten data. */ void (*data_not_sent)(PurpleXfer *xfer, const guchar *buffer, gsize size); /** * Op to create a thumbnail image for a file transfer * - * @param xfer The file transfer structure + * @xfer: The file transfer structure */ void (*add_thumbnail)(PurpleXfer *xfer, const gchar *formats); } PurpleXferUiOps; @@ -175,11 +175,11 @@ * Creates a new file transfer handle. * This is called by protocols. * - * @param account The account sending or receiving the file. - * @param type The type of file transfer. - * @param who The name of the remote user. + * @account: The account sending or receiving the file. + * @type: The type of file transfer. + * @who: The name of the remote user. * - * @return A file transfer handle. + * Returns: A file transfer handle. */ PurpleXfer *purple_xfer_new(PurpleAccount *account, PurpleXferType type, const char *who); @@ -191,147 +191,147 @@ * to accept the file transfer. In this case protocol must call this function * again once the filename is available. * - * @param xfer The file transfer to request confirmation on. + * @xfer: The file transfer to request confirmation on. */ void purple_xfer_request(PurpleXfer *xfer); /** * Called if the user accepts the file transfer request. * - * @param xfer The file transfer. - * @param filename The filename. + * @xfer: The file transfer. + * @filename: The filename. */ void purple_xfer_request_accepted(PurpleXfer *xfer, const char *filename); /** * Called if the user rejects the file transfer request. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void purple_xfer_request_denied(PurpleXfer *xfer); /** * Returns the socket file descriptor. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The socket file descriptor. + * Returns: The socket file descriptor. */ int purple_xfer_get_fd(PurpleXfer *xfer); /** * Returns the Watcher for the transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The watcher. + * Returns: The watcher. */ int purple_xfer_get_watcher(PurpleXfer *xfer); /** * Returns the type of file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The type of the file transfer. + * Returns: The type of the file transfer. */ PurpleXferType purple_xfer_get_xfer_type(const PurpleXfer *xfer); /** * Returns the account the file transfer is using. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The account. + * Returns: The account. */ PurpleAccount *purple_xfer_get_account(const PurpleXfer *xfer); /** * Sets the name of the remote user. * - * @param xfer The file transfer. - * @param who The name of the remote user. + * @xfer: The file transfer. + * @who: The name of the remote user. */ void purple_xfer_set_remote_user(PurpleXfer *xfer, const char *who); /** * Returns the name of the remote user. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The name of the remote user. + * Returns: The name of the remote user. */ const char *purple_xfer_get_remote_user(const PurpleXfer *xfer); /** * Returns the status of the xfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The status. + * Returns: The status. */ PurpleXferStatus purple_xfer_get_status(const PurpleXfer *xfer); /** * Returns true if the file transfer was cancelled. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return Whether or not the transfer was cancelled. + * Returns: Whether or not the transfer was cancelled. */ gboolean purple_xfer_is_cancelled(const PurpleXfer *xfer); /** * Returns the completed state for a file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The completed state. + * Returns: The completed state. */ gboolean purple_xfer_is_completed(const PurpleXfer *xfer); /** * Returns the name of the file being sent or received. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The filename. + * Returns: The filename. */ const char *purple_xfer_get_filename(const PurpleXfer *xfer); /** * Returns the file's destination filename, * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The destination filename. + * Returns: The destination filename. */ const char *purple_xfer_get_local_filename(const PurpleXfer *xfer); /** * Returns the number of bytes sent (or received) so far. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The number of bytes sent. + * Returns: The number of bytes sent. */ goffset purple_xfer_get_bytes_sent(const PurpleXfer *xfer); /** * Returns the number of bytes remaining to send or receive. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The number of bytes remaining. + * Returns: The number of bytes remaining. */ goffset purple_xfer_get_bytes_remaining(const PurpleXfer *xfer); /** * Returns the size of the file being sent or received. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The total size of the file. + * Returns: The total size of the file. */ goffset purple_xfer_get_size(const PurpleXfer *xfer); @@ -340,135 +340,135 @@ * * This is a number between 0 (0%) and 1 (100%). * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The percentage complete. + * Returns: The percentage complete. */ double purple_xfer_get_progress(const PurpleXfer *xfer); /** * Returns the local port number in the file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The port number on this end. + * Returns: The port number on this end. */ guint16 purple_xfer_get_local_port(const PurpleXfer *xfer); /** * Returns the remote IP address in the file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The IP address on the other end. + * Returns: The IP address on the other end. */ const char *purple_xfer_get_remote_ip(const PurpleXfer *xfer); /** * Returns the remote port number in the file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The port number on the other end. + * Returns: The port number on the other end. */ guint16 purple_xfer_get_remote_port(const PurpleXfer *xfer); /** * Returns the time the transfer of a file started. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The time when the transfer started. + * Returns: The time when the transfer started. */ time_t purple_xfer_get_start_time(const PurpleXfer *xfer); /** * Returns the time the transfer of a file ended. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The time when the transfer ended. + * Returns: The time when the transfer ended. */ time_t purple_xfer_get_end_time(const PurpleXfer *xfer); /** * Sets the socket file descriptor. * - * @param xfer The file transfer. - * @param fd The file descriptor. + * @xfer: The file transfer. + * @fd: The file descriptor. */ void purple_xfer_set_fd(PurpleXfer *xfer, int fd); /** * Sets the watcher for the file transfer. * - * @param xfer The file transfer. - * @param watcher The watcher. + * @xfer: The file transfer. + * @watcher: The watcher. */ void purple_xfer_set_watcher(PurpleXfer *xfer, int watcher); /** * Sets the completed state for the file transfer. * - * @param xfer The file transfer. - * @param completed The completed state. + * @xfer: The file transfer. + * @completed: The completed state. */ void purple_xfer_set_completed(PurpleXfer *xfer, gboolean completed); /** * Sets the current status for the file transfer. * - * @param xfer The file transfer. - * @param status The current status. + * @xfer: The file transfer. + * @status: The current status. */ void purple_xfer_set_status(PurpleXfer *xfer, PurpleXferStatus status); /** * Sets the message for the file transfer. * - * @param xfer The file transfer. - * @param message The message. + * @xfer: The file transfer. + * @message: The message. */ void purple_xfer_set_message(PurpleXfer *xfer, const char *message); /** * Returns the message for the file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The message. + * Returns: The message. */ const char *purple_xfer_get_message(const PurpleXfer *xfer); /** * Sets the filename for the file transfer. * - * @param xfer The file transfer. - * @param filename The filename. + * @xfer: The file transfer. + * @filename: The filename. */ void purple_xfer_set_filename(PurpleXfer *xfer, const char *filename); /** * Sets the local filename for the file transfer. * - * @param xfer The file transfer. - * @param filename The filename + * @xfer: The file transfer. + * @filename: The filename */ void purple_xfer_set_local_filename(PurpleXfer *xfer, const char *filename); /** * Sets the size of the file in a file transfer. * - * @param xfer The file transfer. - * @param size The size of the file. + * @xfer: The file transfer. + * @size: The size of the file. */ void purple_xfer_set_size(PurpleXfer *xfer, goffset size); /** * Sets the local port of the file transfer. * - * @param xfer The file transfer. - * @param local_port The local port. + * @xfer: The file transfer. + * @local_port: The local port. */ void purple_xfer_set_local_port(PurpleXfer *xfer, guint16 local_port); @@ -479,8 +479,8 @@ * * It's used for pausing and resuming an oscar file transfer. * - * @param xfer The file transfer. - * @param bytes_sent The new current position in the file. If we're + * @xfer: The file transfer. + * @bytes_sent: The new current position in the file. If we're * sending a file then this is the byte that we will * send. If we're receiving a file, this is the * next byte that we expect to receive. @@ -490,17 +490,17 @@ /** * Returns the UI operations structure for a file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleXferUiOps *purple_xfer_get_ui_ops(const PurpleXfer *xfer); /** * Sets the read function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The read function. + * @xfer: The file transfer. + * @fnc: The read function. */ void purple_xfer_set_read_fnc(PurpleXfer *xfer, gssize (*fnc)(guchar **, size_t, PurpleXfer *)); @@ -508,8 +508,8 @@ /** * Sets the write function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The write function. + * @xfer: The file transfer. + * @fnc: The write function. */ void purple_xfer_set_write_fnc(PurpleXfer *xfer, gssize (*fnc)(const guchar *, size_t, PurpleXfer *)); @@ -517,8 +517,8 @@ /** * Sets the acknowledge function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The acknowledge function. + * @xfer: The file transfer. + * @fnc: The acknowledge function. */ void purple_xfer_set_ack_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *, const guchar *, size_t)); @@ -526,8 +526,8 @@ /** * Sets the function to be called if the request is denied. * - * @param xfer The file transfer. - * @param fnc The request denied protocol callback. + * @xfer: The file transfer. + * @fnc: The request denied protocol callback. */ void purple_xfer_set_request_denied_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); @@ -538,72 +538,72 @@ * the necessary parameters. This will be called if the file transfer * is accepted by the user. * - * @param xfer The file transfer. - * @param fnc The transfer initialization function. + * @xfer: The file transfer. + * @fnc: The transfer initialization function. */ void purple_xfer_set_init_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); /** * Sets the start transfer function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The start transfer function. + * @xfer: The file transfer. + * @fnc: The start transfer function. */ void purple_xfer_set_start_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); /** * Sets the end transfer function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The end transfer function. + * @xfer: The file transfer. + * @fnc: The end transfer function. */ void purple_xfer_set_end_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); /** * Sets the cancel send function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The cancel send function. + * @xfer: The file transfer. + * @fnc: The cancel send function. */ void purple_xfer_set_cancel_send_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); /** * Sets the cancel receive function for the file transfer. * - * @param xfer The file transfer. - * @param fnc The cancel receive function. + * @xfer: The file transfer. + * @fnc: The cancel receive function. */ void purple_xfer_set_cancel_recv_fnc(PurpleXfer *xfer, void (*fnc)(PurpleXfer *)); /** * Reads in data from a file transfer stream. * - * @param xfer The file transfer. - * @param buffer The buffer that will be created to contain the data. + * @xfer: The file transfer. + * @buffer: The buffer that will be created to contain the data. * - * @return The number of bytes read, or -1. + * Returns: The number of bytes read, or -1. */ gssize purple_xfer_read(PurpleXfer *xfer, guchar **buffer); /** * Writes data to a file transfer stream. * - * @param xfer The file transfer. - * @param buffer The buffer to read the data from. - * @param size The number of bytes to write. + * @xfer: The file transfer. + * @buffer: The buffer to read the data from. + * @size: The number of bytes to write. * - * @return The number of bytes written, or -1. + * Returns: The number of bytes written, or -1. */ gssize purple_xfer_write(PurpleXfer *xfer, const guchar *buffer, gsize size); /** * Writes chunk of received file. * - * @param xfer The file transfer. - * @param buffer The buffer to read the data from. - * @param size The number of bytes to write. + * @xfer: The file transfer. + * @buffer: The buffer to read the data from. + * @size: The number of bytes to write. * - * @return TRUE on success, FALSE otherwise. + * Returns: TRUE on success, FALSE otherwise. */ gboolean purple_xfer_write_file(PurpleXfer *xfer, const guchar *buffer, gsize size); @@ -611,11 +611,11 @@ /** * Writes chunk of file being sent. * - * @param xfer The file transfer. - * @param buffer The buffer to write the data to. - * @param size The size of buffer. + * @xfer: The file transfer. + * @buffer: The buffer to write the data to. + * @size: The size of buffer. * - * @return Number of bytes written (0 means, the device is busy), or -1 on + * Returns: Number of bytes written (0 means, the device is busy), or -1 on * failure. */ gssize @@ -631,17 +631,17 @@ * Passing @a fd as '-1' is a special-case and indicates to the * protocol to facilitate the file transfer itself. * - * @param xfer The file transfer. - * @param fd The file descriptor for the socket. - * @param ip The IP address to connect to. - * @param port The port to connect to. + * @xfer: The file transfer. + * @fd: The file descriptor for the socket. + * @ip: The IP address to connect to. + * @port: The port to connect to. */ void purple_xfer_start(PurpleXfer *xfer, int fd, const char *ip, guint16 port); /** * Ends a file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void purple_xfer_end(PurpleXfer *xfer); @@ -649,21 +649,21 @@ * Adds a new file transfer to the list of file transfers. Call this only * if you are not using purple_xfer_start. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void purple_xfer_add(PurpleXfer *xfer); /** * Cancels a file transfer on the local end. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void purple_xfer_cancel_local(PurpleXfer *xfer); /** * Cancels a file transfer from the remote end. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void purple_xfer_cancel_remote(PurpleXfer *xfer); @@ -674,17 +674,17 @@ * specifies a title ("File transfer to <i>user</i> failed" or * "File Transfer from <i>user</i> failed"). * - * @param type The type of file transfer. - * @param account The account sending or receiving the file. - * @param who The user on the other end of the transfer. - * @param msg The message to display. + * @type: The type of file transfer. + * @account: The account sending or receiving the file. + * @who: The user on the other end of the transfer. + * @msg: The message to display. */ void purple_xfer_error(PurpleXferType type, PurpleAccount *account, const char *who, const char *msg); /** * Updates file transfer progress. * - * @param xfer The file transfer. + * @xfer: The file transfer. */ void purple_xfer_update_progress(PurpleXfer *xfer); @@ -693,9 +693,9 @@ * * This is a wrapper around purple_conversation_write * - * @param xfer The file transfer to which this message relates. - * @param message The message to display. - * @param is_error Is this an error message?. + * @xfer: The file transfer to which this message relates. + * @message: The message to display. + * @is_error: Is this an error message?. */ void purple_xfer_conversation_write(PurpleXfer *xfer, const gchar *message, gboolean is_error); @@ -704,7 +704,7 @@ * the direction of the file transfer. Used when the UI is providing * read/write/data_not_sent UI ops. * - * @param xfer The file transfer which is ready. + * @xfer: The file transfer which is ready. */ void purple_xfer_ui_ready(PurpleXfer *xfer); @@ -713,25 +713,25 @@ * the direction of the file transfer. Used when the protocol provides read/write * ops and cannot/does not provide a raw fd to the core. * - * @param xfer The file transfer which is ready. + * @xfer: The file transfer which is ready. */ void purple_xfer_protocol_ready(PurpleXfer *xfer); /** * Gets the thumbnail data for a transfer * - * @param xfer The file transfer to get the thumbnail for - * @param len If not @c NULL, the length of the thumbnail data returned + * @xfer: The file transfer to get the thumbnail for + * @len: If not @c NULL, the length of the thumbnail data returned * will be set in the location pointed to by this. - * @return The thumbnail data, or NULL if there is no thumbnail + * Returns: The thumbnail data, or NULL if there is no thumbnail */ gconstpointer purple_xfer_get_thumbnail(const PurpleXfer *xfer, gsize *len); /** * Gets the mimetype of the thumbnail preview for a transfer * - * @param xfer The file transfer to get the mimetype for - * @return The mimetype of the thumbnail, or @c NULL if not thumbnail is set + * @xfer: The file transfer to get the mimetype for + * Returns: The mimetype of the thumbnail, or @c NULL if not thumbnail is set */ const gchar *purple_xfer_get_thumbnail_mimetype(const PurpleXfer *xfer); @@ -739,10 +739,10 @@ /** * Sets the thumbnail data for a transfer * - * @param xfer The file transfer to set the data for - * @param thumbnail A pointer to the thumbnail data, this will be copied - * @param size The size in bytes of the passed in thumbnail data - * @param mimetype The mimetype of the generated thumbnail + * @xfer: The file transfer to set the data for + * @thumbnail: A pointer to the thumbnail data, this will be copied + * @size: The size in bytes of the passed in thumbnail data + * @mimetype: The mimetype of the generated thumbnail */ void purple_xfer_set_thumbnail(PurpleXfer *xfer, gconstpointer thumbnail, gsize size, const gchar *mimetype); @@ -751,8 +751,8 @@ * Prepare a thumbnail for a transfer (if the UI supports it) * will be no-op in case the UI doesn't implement thumbnail creation * - * @param xfer The file transfer to create a thumbnail for - * @param formats A comma-separated list of mimetypes for image formats + * @xfer: The file transfer to create a thumbnail for + * @formats: A comma-separated list of mimetypes for image formats * the protocols can use for thumbnails. */ void purple_xfer_prepare_thumbnail(PurpleXfer *xfer, const gchar *formats); @@ -760,34 +760,34 @@ /** * Sets the protocol data for a file transfer. * - * @param xfer The file transfer. - * @param proto_data The protocol data to set for the file transfer. + * @xfer: The file transfer. + * @proto_data: The protocol data to set for the file transfer. */ void purple_xfer_set_protocol_data(PurpleXfer *xfer, gpointer proto_data); /** * Gets the protocol data for a file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The protocol data for the file transfer. + * Returns: The protocol data for the file transfer. */ gpointer purple_xfer_get_protocol_data(const PurpleXfer *xfer); /** * Set the UI data associated with this file transfer. * - * @param xfer The file transfer. - * @param ui_data A pointer to associate with this file transfer. + * @xfer: The file transfer. + * @ui_data: A pointer to associate with this file transfer. */ void purple_xfer_set_ui_data(PurpleXfer *xfer, gpointer ui_data); /** * Get the UI data associated with this file transfer. * - * @param xfer The file transfer. + * @xfer: The file transfer. * - * @return The UI data associated with this file transfer. This is a + * Returns: The UI data associated with this file transfer. This is a * convenience field provided to the UIs--it is not * used by the libpurple core. */ @@ -803,14 +803,14 @@ /** * Returns all xfers * - * @return all current xfers with refs + * Returns: all current xfers with refs */ GList *purple_xfers_get_all(void); /** * Returns the handle to the file transfer subsystem * - * @return The handle + * Returns: The handle */ void *purple_xfers_get_handle(void); @@ -827,14 +827,14 @@ /** * Sets the UI operations structure to be used in all purple file transfers. * - * @param ops The UI operations structure. + * @ops: The UI operations structure. */ void purple_xfers_set_ui_ops(PurpleXferUiOps *ops); /** * Returns the UI operations structure to be used in all purple file transfers. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleXferUiOps *purple_xfers_get_ui_ops(void);
--- a/libpurple/xmlnode.h Wed Jan 29 00:28:08 2014 +0530 +++ b/libpurple/xmlnode.h Wed Jan 29 05:28:33 2014 +0530 @@ -70,66 +70,66 @@ /** * Creates a new PurpleXmlNode. * - * @param name The name of the node. + * @name: The name of the node. * - * @return The new node. + * Returns: The new node. */ PurpleXmlNode *purple_xmlnode_new(const char *name); /** * Creates a new PurpleXmlNode child. * - * @param parent The parent node. - * @param name The name of the child node. + * @parent: The parent node. + * @name: The name of the child node. * - * @return The new child node. + * Returns: The new child node. */ PurpleXmlNode *purple_xmlnode_new_child(PurpleXmlNode *parent, const char *name); /** * Inserts a node into a node as a child. * - * @param parent The parent node to insert child into. - * @param child The child node to insert into parent. + * @parent: The parent node to insert child into. + * @child: The child node to insert into parent. */ void purple_xmlnode_insert_child(PurpleXmlNode *parent, PurpleXmlNode *child); /** * Gets a child node named name. * - * @param parent The parent node. - * @param name The child's name. + * @parent: The parent node. + * @name: The child's name. * - * @return The child or NULL. + * Returns: The child or NULL. */ PurpleXmlNode *purple_xmlnode_get_child(const PurpleXmlNode *parent, const char *name); /** * Gets a child node named name in a namespace. * - * @param parent The parent node. - * @param name The child's name. - * @param xmlns The namespace. + * @parent: The parent node. + * @name: The child's name. + * @xmlns: The namespace. * - * @return The child or NULL. + * Returns: The child or NULL. */ PurpleXmlNode *purple_xmlnode_get_child_with_namespace(const PurpleXmlNode *parent, const char *name, const char *xmlns); /** * Gets the next node with the same name as node. * - * @param node The node of a twin to find. + * @node: The node of a twin to find. * - * @return The twin of node or NULL. + * Returns: The twin of node or NULL. */ PurpleXmlNode *purple_xmlnode_get_next_twin(PurpleXmlNode *node); /** * Inserts data into a node. * - * @param node The node to insert data into. - * @param data The data to insert. - * @param size The size of the data to insert. If data is + * @node: The node to insert data into. + * @data: The data to insert. + * @size: The size of the data to insert. If data is * null-terminated you can pass in -1. */ void purple_xmlnode_insert_data(PurpleXmlNode *node, const char *data, gssize size); @@ -137,9 +137,9 @@ /** * Gets (escaped) data from a node. * - * @param node The node to get data from. + * @node: The node to get data from. * - * @return The data from the node or NULL. This data is in raw escaped format. + * Returns: The data from the node or NULL. This data is in raw escaped format. * You must g_free this string when finished using it. */ char *purple_xmlnode_get_data(const PurpleXmlNode *node); @@ -147,9 +147,9 @@ /** * Gets unescaped data from a node. * - * @param node The node to get data from. + * @node: The node to get data from. * - * @return The data from the node, in unescaped form. You must g_free + * Returns: The data from the node, in unescaped form. You must g_free * this string when finished using it. */ char *purple_xmlnode_get_data_unescaped(const PurpleXmlNode *node); @@ -157,20 +157,20 @@ /** * Sets an attribute for a node. * - * @param node The node to set an attribute for. - * @param attr The name of the attribute. - * @param value The value of the attribute. + * @node: The node to set an attribute for. + * @attr: The name of the attribute. + * @value: The value of the attribute. */ void purple_xmlnode_set_attrib(PurpleXmlNode *node, const char *attr, const char *value); /** * Sets a namespaced attribute for a node * - * @param node The node to set an attribute for. - * @param attr The name of the attribute to set - * @param xmlns The namespace of the attribute to set - * @param prefix The prefix of the attribute to set - * @param value The value of the attribute + * @node: The node to set an attribute for. + * @attr: The name of the attribute to set + * @xmlns: The namespace of the attribute to set + * @prefix: The prefix of the attribute to set + * @value: The value of the attribute */ void purple_xmlnode_set_attrib_full(PurpleXmlNode *node, const char *attr, const char *xmlns, const char *prefix, const char *value); @@ -178,54 +178,54 @@ /** * Gets an attribute from a node. * - * @param node The node to get an attribute from. - * @param attr The attribute to get. + * @node: The node to get an attribute from. + * @attr: The attribute to get. * - * @return The value of the attribute. + * Returns: The value of the attribute. */ const char *purple_xmlnode_get_attrib(const PurpleXmlNode *node, const char *attr); /** * Gets a namespaced attribute from a node * - * @param node The node to get an attribute from. - * @param attr The attribute to get - * @param xmlns The namespace of the attribute to get + * @node: The node to get an attribute from. + * @attr: The attribute to get + * @xmlns: The namespace of the attribute to get * - * @return The value of the attribute/ + * Returns: The value of the attribute/ */ const char *purple_xmlnode_get_attrib_with_namespace(const PurpleXmlNode *node, const char *attr, const char *xmlns); /** * Removes an attribute from a node. * - * @param node The node to remove an attribute from. - * @param attr The attribute to remove. + * @node: The node to remove an attribute from. + * @attr: The attribute to remove. */ void purple_xmlnode_remove_attrib(PurpleXmlNode *node, const char *attr); /** * Removes a namespaced attribute from a node * - * @param node The node to remove an attribute from - * @param attr The attribute to remove - * @param xmlns The namespace of the attribute to remove + * @node: The node to remove an attribute from + * @attr: The attribute to remove + * @xmlns: The namespace of the attribute to remove */ void purple_xmlnode_remove_attrib_with_namespace(PurpleXmlNode *node, const char *attr, const char *xmlns); /** * Sets the namespace of a node * - * @param node The node to qualify - * @param xmlns The namespace of the node + * @node: The node to qualify + * @xmlns: The namespace of the node */ void purple_xmlnode_set_namespace(PurpleXmlNode *node, const char *xmlns); /** * Returns the namespace of a node * - * @param node The node to get the namepsace from - * @return The namespace of this node + * @node: The node to get the namepsace from + * Returns: The namespace of this node */ const char *purple_xmlnode_get_namespace(const PurpleXmlNode *node); @@ -245,33 +245,33 @@ * The default namespace of all nodes (including 'child1') is "jabber:client", * though the namespace for 'element' is "http://example.org/ns1". * - * @param node The node for which to return the default namespace - * @return The default namespace of this node + * @node: The node for which to return the default namespace + * Returns: The default namespace of this node */ const char *purple_xmlnode_get_default_namespace(const PurpleXmlNode *node); /** * Returns the defined namespace for a prefix. * - * @param node The node from which to start the search. - * @param prefix The prefix for which to return the associated namespace. - * @return The namespace for this prefix. + * @node: The node from which to start the search. + * @prefix: The prefix for which to return the associated namespace. + * Returns: The namespace for this prefix. */ const char *purple_xmlnode_get_prefix_namespace(const PurpleXmlNode *node, const char *prefix); /** * Sets the prefix of a node * - * @param node The node to qualify - * @param prefix The prefix of the node + * @node: The node to qualify + * @prefix: The prefix of the node */ void purple_xmlnode_set_prefix(PurpleXmlNode *node, const char *prefix); /** * Returns the prefix of a node * - * @param node The node to get the prefix from - * @return The prefix of this node + * @node: The node to get the prefix from + * Returns: The prefix of this node */ const char *purple_xmlnode_get_prefix(const PurpleXmlNode *node); @@ -284,26 +284,26 @@ * break some applications (SOAP / XPath apparently often rely on * the prefixes having the same name. * - * @param node The node from which to strip prefixes + * @node: The node from which to strip prefixes */ void purple_xmlnode_strip_prefixes(PurpleXmlNode *node); /** * Gets the parent node. * - * @param child The child node. + * @child: The child node. * - * @return The parent or NULL. + * Returns: The parent or NULL. */ PurpleXmlNode *purple_xmlnode_get_parent(const PurpleXmlNode *child); /** * Returns the node in a string of xml. * - * @param node The starting node to output. - * @param len Address for the size of the string. + * @node: The starting node to output. + * @len: Address for the size of the string. * - * @return The node represented as a string. You must + * Returns: The node represented as a string. You must * g_free this string when finished using it. */ char *purple_xmlnode_to_str(const PurpleXmlNode *node, int *len); @@ -311,10 +311,10 @@ /** * Returns the node in a string of human readable xml. * - * @param node The starting node to output. - * @param len Address for the size of the string. + * @node: The starting node to output. + * @len: Address for the size of the string. * - * @return The node as human readable string including + * Returns: The node as human readable string including * tab and new line characters. You must * g_free this string when finished using it. */ @@ -325,27 +325,27 @@ * root node of an XML document will parse the entire document * into a tree of nodes, and return the PurpleXmlNode of the root. * - * @param str The string of xml. - * @param size The size of the string, or -1 if @a str is + * @str: The string of xml. + * @size: The size of the string, or -1 if @a str is * NUL-terminated. * - * @return The new node. + * Returns: The new node. */ PurpleXmlNode *purple_xmlnode_from_str(const char *str, gssize size); /** * Creates a new node from the source node. * - * @param src The node to copy. + * @src: The node to copy. * - * @return A new copy of the src node. + * Returns: A new copy of the src node. */ PurpleXmlNode *purple_xmlnode_copy(const PurpleXmlNode *src); /** * Frees a node and all of its children. * - * @param node The node to free. + * @node: The node to free. */ void purple_xmlnode_free(PurpleXmlNode *node); @@ -354,14 +354,14 @@ * root node of an XML document will parse the entire document * into a tree of nodes, and return the PurpleXmlNode of the root. * - * @param dir The directory where the file is located - * @param filename The filename - * @param description A description of the file being parsed. Displayed to + * @dir: The directory where the file is located + * @filename: The filename + * @description: A description of the file being parsed. Displayed to * the user if the file cannot be read. - * @param process The subsystem that is calling purple_xmlnode_from_file. Used as + * @process: The subsystem that is calling purple_xmlnode_from_file. Used as * the category for debugging. * - * @return The new node or NULL if an error occurred. + * Returns: The new node or NULL if an error occurred. */ PurpleXmlNode *purple_xmlnode_from_file(const char *dir, const char *filename, const char *description, const char *process);
--- a/pidgin/gtkaccount.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkaccount.h Wed Jan 29 05:28:33 2014 +0530 @@ -52,8 +52,8 @@ /** * Shows an add/modify account dialog. * - * @param type The type of dialog. - * @param account The associated account, or @c NULL for an Add dialog. + * @type: The type of dialog. + * @account: The associated account, or @c NULL for an Add dialog. */ void pidgin_account_dialog_show(PidginAccountDialogType type, PurpleAccount *account); @@ -61,14 +61,14 @@ /** * Returns the GTK+ account UI ops * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleAccountUiOps *pidgin_accounts_get_ui_ops(void); /** * Returns the gtkaccounts handle * - * @return The handle to the GTK+ account system + * Returns: The handle to the GTK+ account system */ void *pidgin_accounts_get_handle(void);
--- a/pidgin/gtkblist-theme.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkblist-theme.h Wed Jan 29 05:28:33 2014 +0530 @@ -88,60 +88,60 @@ /** * Create a new PidginThemeFont. * - * @param face The font face - * @param color The color of the font + * @face: The font face + * @color: The color of the font * - * @return A newly created PidginThemeFont + * Returns: A newly created PidginThemeFont */ PidginThemeFont * pidgin_theme_font_new(const gchar *face, GdkColor *color); /** * Frees a font and color pair * - * @param font The theme font + * @font: The theme font */ void pidgin_theme_font_free(PidginThemeFont *font); /** * Set the font-face of a PidginThemeFont. * - * @param font The PidginThemeFont - * @param face The font-face + * @font: The PidginThemeFont + * @face: The font-face */ void pidgin_theme_font_set_font_face(PidginThemeFont *font, const gchar *face); /** * Set the color of a PidginThemeFont. * - * @param font The PidginThemeFont - * @param color The color + * @font: The PidginThemeFont + * @color: The color */ void pidgin_theme_font_set_color(PidginThemeFont *font, const GdkColor *color); /** * Get the font-face of a PidginThemeFont. * - * @param font The PidginThemeFont + * @font: The PidginThemeFont * - * @return The font-face, or NULL if none is set. + * Returns: The font-face, or NULL if none is set. */ const gchar * pidgin_theme_font_get_font_face(PidginThemeFont *font); /** * Get the color of a PidginThemeFont as a GdkColor object. * - * @param font The PidginThemeFont + * @font: The PidginThemeFont * - * @return The color, or NULL if none is set. + * Returns: The color, or NULL if none is set. */ const GdkColor * pidgin_theme_font_get_color(PidginThemeFont *font); /** * Get the color of a PidginThemeFont. * - * @param font The PidginThemeFont + * @font: The PidginThemeFont * - * @return The color, or NULL if none is set. + * Returns: The color, or NULL if none is set. */ const gchar * pidgin_theme_font_get_color_describe(PidginThemeFont *font); @@ -160,9 +160,9 @@ /** * Returns the background color of the buddy list. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A gdk color. + * Returns:s A gdk color. */ GdkColor *pidgin_blist_theme_get_background_color(PidginBlistTheme *theme); @@ -170,117 +170,117 @@ * Returns the opacity of the buddy list window * (0.0 or clear to 1.0 fully opaque). * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns The opacity + * Returns:s The opacity */ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme); /** * Returns the layout to be used with the buddy list. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns The buddy list layout. + * Returns:s The buddy list layout. */ PidginBlistLayout *pidgin_blist_theme_get_layout(PidginBlistTheme *theme); /** * Returns the background color to be used with expanded groups. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A gdk color. + * Returns:s A gdk color. */ GdkColor *pidgin_blist_theme_get_expanded_background_color(PidginBlistTheme *theme); /** * Returns the text font and color to be used with expanded groups. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_expanded_text_info(PidginBlistTheme *theme); /** * Returns the background color to be used with collapsed groups. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A gdk color. + * Returns:s A gdk color. */ GdkColor *pidgin_blist_theme_get_collapsed_background_color(PidginBlistTheme *theme); /** * Returns the text font and color to be used with collapsed groups. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_collapsed_text_info(PidginBlistTheme *theme); /** * Returns the colors to be used for contacts and chats. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A gdkcolor for contacts and chats. + * Returns:s A gdkcolor for contacts and chats. */ GdkColor *pidgin_blist_theme_get_contact_color(PidginBlistTheme *theme); /** * Returns the text font and color to be used for expanded contacts. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_contact_text_info(PidginBlistTheme *theme); /** * Returns the text font and color to be used for online buddies. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_online_text_info(PidginBlistTheme *theme); /** * Returns the text font and color to be used for away and idle buddies. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_away_text_info(PidginBlistTheme *theme); /** * Returns the text font and color to be used for offline buddies. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_offline_text_info(PidginBlistTheme *theme); /** * Returns the text font and color to be used for idle buddies. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_idle_text_info(PidginBlistTheme *theme); /** * Returns the text font and color to be used for buddies with unread messages. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_unread_message_text_info(PidginBlistTheme *theme); @@ -288,18 +288,18 @@ * Returns the text font and color to be used for chats with unread messages * that mention your nick. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_unread_message_nick_said_text_info(PidginBlistTheme *theme); /** * Returns the text font and color to be used for a buddy's status message. * - * @param theme The PidginBlist theme. + * @theme: The PidginBlist theme. * - * @returns A font and color pair. + * Returns:s A font and color pair. */ PidginThemeFont *pidgin_blist_theme_get_status_text_info(PidginBlistTheme *theme); @@ -308,112 +308,112 @@ /** * Sets the background color to be used for this buddy list theme. * - * @param theme The PidginBlist theme. - * @param color The new background color. + * @theme: The PidginBlist theme. + * @color: The new background color. */ void pidgin_blist_theme_set_background_color(PidginBlistTheme *theme, const GdkColor *color); /** * Sets the opacity to be used for this buddy list theme. * - * @param theme The PidginBlist theme. - * @param opacity The new opacity setting. + * @theme: The PidginBlist theme. + * @opacity: The new opacity setting. */ void pidgin_blist_theme_set_opacity(PidginBlistTheme *theme, gdouble opacity); /** * Sets the buddy list layout to be used for this buddy list theme. * - * @param theme The PidginBlist theme. - * @param layout The new layout. + * @theme: The PidginBlist theme. + * @layout: The new layout. */ void pidgin_blist_theme_set_layout(PidginBlistTheme *theme, const PidginBlistLayout *layout); /** * Sets the background color to be used for expanded groups. * - * @param theme The PidginBlist theme. - * @param color The new background color. + * @theme: The PidginBlist theme. + * @color: The new background color. */ void pidgin_blist_theme_set_expanded_background_color(PidginBlistTheme *theme, const GdkColor *color); /** * Sets the text color and font to be used for expanded groups. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_expanded_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the background color to be used for collapsed groups. * - * @param theme The PidginBlist theme. - * @param color The new background color. + * @theme: The PidginBlist theme. + * @color: The new background color. */ void pidgin_blist_theme_set_collapsed_background_color(PidginBlistTheme *theme, const GdkColor *color); /** * Sets the text color and font to be used for expanded groups. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_collapsed_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the background color to be used for contacts and chats. * - * @param theme The PidginBlist theme. - * @param color The color to use for contacts and chats. + * @theme: The PidginBlist theme. + * @color: The color to use for contacts and chats. */ void pidgin_blist_theme_set_contact_color(PidginBlistTheme *theme, const GdkColor *color); /** * Sets the text color and font to be used for expanded contacts. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_contact_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the text color and font to be used for online buddies. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_online_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the text color and font to be used for away and idle buddies. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_away_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the text color and font to be used for offline buddies. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_offline_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the text color and font to be used for idle buddies. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_idle_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the text color and font to be used for buddies with unread messages. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_unread_message_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); @@ -421,16 +421,16 @@ * Sets the text color and font to be used for a chat with unread messages * that mention your nick. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_unread_message_nick_said_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair); /** * Sets the text color and font to be used for buddy status messages. * - * @param theme The PidginBlist theme. - * @param pair The new text font and color pair. + * @theme: The PidginBlist theme. + * @pair: The new text font and color pair. */ void pidgin_blist_theme_set_status_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
--- a/pidgin/gtkblist.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkblist.h Wed Jan 29 05:28:33 2014 +0530 @@ -130,7 +130,7 @@ /** * Get the handle for the GTK+ blist system. * - * @return the handle to the blist system + * Returns: the handle to the blist system */ void *pidgin_blist_get_handle(void); @@ -147,7 +147,7 @@ /** * Returns the UI operations structure for the buddy list. * - * @return The GTK+ list operations structure. + * Returns: The GTK+ list operations structure. */ PurpleBlistUiOps *pidgin_blist_get_ui_ops(void); @@ -158,16 +158,16 @@ * returns the PidginBuddyList we're most likely wanting to work with. This is slightly * cleaner than an externed global. * - * @return The default GTK+ buddy list + * Returns: The default GTK+ buddy list */ PidginBuddyList *pidgin_blist_get_default_gtk_blist(void); /** * Populates a menu with the items shown on the buddy list for a buddy. * - * @param menu The menu to populate - * @param buddy The buddy whose menu to get - * @param sub TRUE if this is a sub-menu, FALSE otherwise + * @menu: The menu to populate + * @buddy: The buddy whose menu to get + * @sub: TRUE if this is a sub-menu, FALSE otherwise */ void pidgin_blist_make_buddy_menu(GtkWidget *menu, PurpleBuddy *buddy, gboolean sub); @@ -175,7 +175,7 @@ * Refreshes all the nodes of the buddy list. * This should only be called when something changes to affect most of the nodes (such as a ui preference changing) * - * @param list This is the core list that gets updated from + * @list: This is the core list that gets updated from */ void pidgin_blist_refresh(PurpleBuddyList *list); @@ -188,9 +188,9 @@ * This may be an existing pixbuf that has been given an additional ref, * so it shouldn't be modified. * - * @param node The node to return an emblem for + * @node: The node to return an emblem for * - * @return A GdkPixbuf for the emblem to show, or NULL + * Returns: A GdkPixbuf for the emblem to show, or NULL */ GdkPixbuf * pidgin_blist_get_emblem(PurpleBlistNode *node); @@ -207,8 +207,8 @@ * This only makes sense for contact and buddy nodes. @c FALSE is returned * for other types of nodes. * - * @param node The node in question. - * @return A boolean indicating if @a node is part of an expanded contact. + * @node: The node in question. + * Returns: A boolean indicating if @a node is part of an expanded contact. */ gboolean pidgin_blist_node_is_contact_expanded(PurpleBlistNode *node); @@ -238,21 +238,21 @@ /** * Adds a mini-alert to the blist scrollbook * - * @param widget The widget to add + * @widget: The widget to add */ void pidgin_blist_add_alert(GtkWidget *widget); /** * Sets the current theme for Pidgin to use * - * @param theme the new theme to use + * @theme: the new theme to use */ void pidgin_blist_set_theme(PidginBlistTheme *theme); /** * Gets Pidgin's current buddy list theme * - * @returns the current theme + * Returns:s the current theme */ PidginBlistTheme *pidgin_blist_get_theme(void); @@ -265,7 +265,7 @@ /** * Gets the current list of sort methods. * - * @return A GSlist of sort methods + * Returns: A GSlist of sort methods */ GList *pidgin_blist_get_sort_methods(void); @@ -280,9 +280,9 @@ /** * Registers a buddy list sorting method. * - * @param id The unique ID of the sorting method - * @param name The method's name. - * @param func A pointer to the function. + * @id: The unique ID of the sorting method + * @name: The method's name. + * @func: A pointer to the function. * */ void pidgin_blist_sort_method_reg(const char *id, const char *name, pidgin_blist_sort_function func); @@ -290,14 +290,14 @@ /** * Unregisters a buddy list sorting method. * - * @param id The method's id + * @id: The method's id */ void pidgin_blist_sort_method_unreg(const char *id); /** * Sets a buddy list sorting method. * - * @param id The method's id. + * @id: The method's id. */ void pidgin_blist_sort_method_set(const char *id); @@ -324,7 +324,7 @@ /** * Determines if showing the join chat dialog is a valid action. * - * @return Returns TRUE if there are accounts online capable of + * Returns: Returns TRUE if there are accounts online capable of * joining chat rooms. Otherwise returns FALSE. */ gboolean pidgin_blist_joinchat_is_showable(void); @@ -358,11 +358,11 @@ * This is currently used for mail notification, but could theoretically be used for anything. * Only the most recent headline will be shown. * - * @param text Pango Markup for the label text - * @param pixbuf The GdkPixbuf for the icon - * @param callback The callback to call when headline is clicked - * @param user_data The userdata to include in the callback - * @param destroy The callback to call when headline is closed or replaced by another headline. + * @text: Pango Markup for the label text + * @pixbuf: The GdkPixbuf for the icon + * @callback: The callback to call when headline is clicked + * @user_data: The userdata to include in the callback + * @destroy: The callback to call when headline is closed or replaced by another headline. */ void pidgin_blist_set_headline(const char *text, GdkPixbuf *pixbuf, GCallback callback, gpointer user_data, GDestroyNotify destroy); @@ -370,10 +370,10 @@ /** * Returns a buddy's Pango markup appropriate for setting in a GtkCellRenderer. * - * @param buddy The buddy to return markup from - * @param selected Whether this buddy is selected. If TRUE, the markup will not change the color. - * @param aliased TRUE to return the appropriate alias of this buddy, FALSE to return its username and status information - * @return The markup for this buddy + * @buddy: The buddy to return markup from + * @selected: Whether this buddy is selected. If TRUE, the markup will not change the color. + * @aliased: TRUE to return the appropriate alias of this buddy, FALSE to return its username and status information + * Returns: The markup for this buddy */ gchar *pidgin_blist_get_name_markup(PurpleBuddy *buddy, gboolean selected, gboolean aliased); @@ -383,8 +383,8 @@ * This tooltip will be destroyed the next time this function is called, or when XXXX * is called * - * @param node The buddy list node to show a tooltip for - * @param widget The widget to draw the tooltip on + * @node: The buddy list node to show a tooltip for + * @widget: The widget to draw the tooltip on */ void pidgin_blist_draw_tooltip(PurpleBlistNode *node, GtkWidget *widget);
--- a/pidgin/gtkconn.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkconn.h Wed Jan 29 05:28:33 2014 +0530 @@ -35,7 +35,7 @@ /** * Gets GTK+ Connection UI ops * - * @return UI operations struct + * Returns: UI operations struct */ PurpleConnectionUiOps *pidgin_connections_get_ui_ops(void); @@ -44,7 +44,7 @@ /** * Returns the GTK+ connection handle. * - * @return The handle to the GTK+ connection system. + * Returns: The handle to the GTK+ connection system. */ void *pidgin_connection_get_handle(void);
--- a/pidgin/gtkconv-theme.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkconv-theme.h Wed Jan 29 05:28:33 2014 +0530 @@ -91,9 +91,9 @@ /** * Get the Info.plist hash table from a conversation theme. * - * @param theme The conversation theme + * @theme: The conversation theme * - * @return The hash table. Keys are strings as outlined for message styles, + * Returns: The hash table. Keys are strings as outlined for message styles, * values are GValue*s. This is an internal structure. Take a ref if * necessary, but don't destroy it yourself. */ @@ -102,8 +102,8 @@ /** * Set the Info.plist hash table for a conversation theme. * - * @param theme The conversation theme - * @param info The new hash table. The theme will take ownership of this hash + * @theme: The conversation theme + * @info: The new hash table. The theme will take ownership of this hash * table. Do not use it yourself afterwards with holding a ref. * For key and value specifications, @see pidgin_conversation_theme_get_info. * @@ -113,11 +113,11 @@ /** * Lookup a key in a theme * - * @param theme The conversation theme - * @param key The key to find - * @param specific Whether to search variant-specific keys + * @theme: The conversation theme + * @key: The key to find + * @specific: Whether to search variant-specific keys * - * @return The key information. If @a specific is @c TRUE, then keys are first + * Returns: The key information. If @a specific is @c TRUE, then keys are first * searched by variant, then by general ones. Otherwise, only general * key values are returned. */ @@ -126,10 +126,10 @@ /** * Get the template data from a conversation theme. * - * @param theme The conversation theme - * @param type The type of template data + * @theme: The conversation theme + * @type: The type of template data * - * @return The template data requested. Fallback is made as required by styles. + * Returns: The template data requested. Fallback is made as required by styles. * Subsequent calls to this function will return cached values. */ const char *pidgin_conversation_theme_get_template(PidginConvTheme *theme, PidginConvThemeTemplateType type); @@ -137,8 +137,8 @@ /** * Add an available variant name to a conversation theme. * - * @param theme The conversation theme - * @param variant The name of the variant + * @theme: The conversation theme + * @variant: The name of the variant * * @Note The conversation theme will take ownership of the variant name string. * This function should normally only be called by the theme loader. @@ -148,17 +148,17 @@ /** * Get the currently set variant name for a conversation theme. * - * @param theme The conversation theme + * @theme: The conversation theme * - * @return The current variant name. + * Returns: The current variant name. */ const char *pidgin_conversation_theme_get_variant(PidginConvTheme *theme); /** * Set the variant name for a conversation theme. * - * @param theme The conversation theme - * @param variant The name of the variant + * @theme: The conversation theme + * @variant: The name of the variant * */ void pidgin_conversation_theme_set_variant(PidginConvTheme *theme, const char *variant); @@ -166,9 +166,9 @@ /** * Get a list of available variants for a conversation theme. * - * @param theme The conversation theme + * @theme: The conversation theme * - * @return The list of variants. This GList and the string data are owned by + * Returns: The list of variants. This GList and the string data are owned by * the theme and should not be freed by the caller. */ const GList *pidgin_conversation_theme_get_variants(PidginConvTheme *theme); @@ -176,27 +176,27 @@ /** * Get the path to the template HTML file. * - * @param theme The conversation theme + * @theme: The conversation theme * - * @return The path to the HTML file. + * Returns: The path to the HTML file. */ char *pidgin_conversation_theme_get_template_path(PidginConvTheme *theme); /** * Get the path to the current variant CSS file. * - * @param theme The conversation theme + * @theme: The conversation theme * - * @return The path to the CSS file. + * Returns: The path to the CSS file. */ char *pidgin_conversation_theme_get_css_path(PidginConvTheme *theme); /** * Get (and reference) the array of nick colors * - * @param theme The conversation theme + * @theme: The conversation theme * - * @return Pointer to GArray of nick colors, or NULL if no colors in theme + * Returns: Pointer to GArray of nick colors, or NULL if no colors in theme */ GArray *pidgin_conversation_theme_get_nick_colors(PidginConvTheme *theme);
--- a/pidgin/gtkconv.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkconv.h Wed Jan 29 05:28:33 2014 +0530 @@ -156,35 +156,35 @@ /** * Returns the UI operations structure for GTK+ conversations. * - * @return The GTK+ conversation operations structure. + * Returns: The GTK+ conversation operations structure. */ PurpleConversationUiOps *pidgin_conversations_get_conv_ui_ops(void); /** * Returns the default theme for GTK+ conversations. * - * @return The default GTK+ conversation theme. + * Returns: The default GTK+ conversation theme. */ PurpleTheme *pidgin_conversations_get_default_theme(void); /** * Updates the buddy icon on a conversation. * - * @param conv The conversation. + * @conv: The conversation. */ void pidgin_conv_update_buddy_icon(PurpleIMConversation *im); /** * Sets the active conversation within a GTK-conversation. * - * @param conv The conversation + * @conv: The conversation */ void pidgin_conv_switch_active_conversation(PurpleConversation *conv); /** * Updates conversation buttons by protocol. * - * @param conv The conversation. + * @conv: The conversation. */ void pidgin_conv_update_buttons_by_protocol(PurpleConversation *conv); @@ -196,11 +196,11 @@ * converations returned if greater than zero. The returned list should * be freed by the caller. * - * @param min_state The minimum unseen state. - * @param hidden_only If TRUE, only consider hidden conversations. - * @param max_count Maximum number of conversations to return, or 0 for + * @min_state: The minimum unseen state. + * @hidden_only: If TRUE, only consider hidden conversations. + * @max_count: Maximum number of conversations to return, or 0 for * no maximum. - * @return List of PurpleConversation matching criteria, or NULL. + * Returns: List of PurpleConversation matching criteria, or NULL. */ GList * pidgin_conversations_get_unseen_all(PidginUnseenState min_state, @@ -215,11 +215,11 @@ * returned if greater than zero. The returned list should be freed by the * caller. * - * @param min_state The minimum unseen state. - * @param hidden_only If TRUE, only consider hidden conversations. - * @param max_count Maximum number of conversations to return, or 0 for + * @min_state: The minimum unseen state. + * @hidden_only: If TRUE, only consider hidden conversations. + * @max_count: Maximum number of conversations to return, or 0 for * no maximum. - * @return List of PurpleIMConversation matching criteria, + * Returns: List of PurpleIMConversation matching criteria, * or NULL. */ GList * @@ -235,11 +235,11 @@ * returned if greater than zero. The returned list should be freed by the * caller. * - * @param min_state The minimum unseen state. - * @param hidden_only If TRUE, only consider hidden conversations. - * @param max_count Maximum number of conversations to return, or 0 for + * @min_state: The minimum unseen state. + * @hidden_only: If TRUE, only consider hidden conversations. + * @max_count: Maximum number of conversations to return, or 0 for * no maximum. - * @return List of PurpleChatConversation matching criteria, + * Returns: List of PurpleChatConversation matching criteria, * or NULL. */ GList * @@ -251,9 +251,9 @@ * Fill a menu with a list of conversations. Clicking the conversation * menu item will present that conversation to the user. * - * @param menu Menu widget to add items to. - * @param convs List of PurpleConversation to add to menu. - * @return Number of conversations added to menu. + * @menu: Menu widget to add items to. + * @convs: List of PurpleConversation to add to menu. + * Returns: Number of conversations added to menu. */ guint pidgin_conversations_fill_menu(GtkWidget *menu, GList *convs); @@ -261,16 +261,16 @@ /** * Presents a purple conversation to the user. * - * @param conv The conversation. + * @conv: The conversation. */ void pidgin_conv_present_conversation(PurpleConversation *conv); /** * Reattach Pidgin UI to a conversation. * - * @param conv The conversation. + * @conv: The conversation. * - * @return Wheter Pidgin UI was successfully attached. + * Returns: Wheter Pidgin UI was successfully attached. */ gboolean pidgin_conv_attach_to_conversation(PurpleConversation *conv); @@ -289,7 +289,7 @@ /** * Returns the gtk conversations subsystem handle. * - * @return The conversations subsystem handle. + * Returns: The conversations subsystem handle. */ void *pidgin_conversations_get_handle(void);
--- a/pidgin/gtkdebug.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkdebug.h Wed Jan 29 05:28:33 2014 +0530 @@ -43,7 +43,7 @@ /** * Get the handle for the GTK+ debug system. * - * @return the handle to the debug system + * Returns: the handle to the debug system */ void *pidgin_debug_get_handle(void); @@ -60,7 +60,7 @@ /** * Returns the UI operations structure for GTK+ debug output. * - * @return The GTK+ UI debug operations structure. + * Returns: The GTK+ UI debug operations structure. */ PurpleDebugUiOps *pidgin_debug_get_ui_ops(void);
--- a/pidgin/gtkdnd-hints.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkdnd-hints.h Wed Jan 29 05:28:33 2014 +0530 @@ -57,7 +57,7 @@ /** * Shows a drag-and-drop hint at the specified location. * - * @param id The ID of the hint to show. + * @id: The ID of the hint to show. * @param x The X location to show it at. * @param y The Y location to show it at. */ @@ -66,7 +66,7 @@ /** * Hides the specified drag-and-drop hint. * - * @param id The ID of the hint to hide. + * @id: The ID of the hint to hide. */ void dnd_hints_hide(DndHintWindowId id); @@ -78,10 +78,10 @@ /** * Shows a drag-and-drop hint relative to a widget. * - * @param id The ID of the hint. - * @param widget The widget that the hint is relative to. - * @param horiz The horizontal relative position. - * @param vert The vertical relative position. + * @id: The ID of the hint. + * @widget: The widget that the hint is relative to. + * @horiz: The horizontal relative position. + * @vert: The vertical relative position. */ void dnd_hints_show_relative(DndHintWindowId id, GtkWidget *widget, DndHintPosition horiz, DndHintPosition vert);
--- a/pidgin/gtkeventloop.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkeventloop.h Wed Jan 29 05:28:33 2014 +0530 @@ -33,7 +33,7 @@ /** * Returns the GTK+ event loop UI operations structure. * - * @return The GTK+ event loop UI operations structure. + * Returns: The GTK+ event loop UI operations structure. */ PurpleEventLoopUiOps *pidgin_eventloop_get_ui_ops(void);
--- a/pidgin/gtkicon-theme.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkicon-theme.h Wed Jan 29 05:28:33 2014 +0530 @@ -71,10 +71,10 @@ /** * Returns a copy of the filename for the icon event or NULL if it is not set * - * @param theme the theme - * @param event the pidgin icon event to look up + * @theme: the theme + * @event: the pidgin icon event to look up * - * @returns the filename of the icon event + * Returns:s the filename of the icon event */ const gchar *pidgin_icon_theme_get_icon(PidginIconTheme *theme, const gchar *event); @@ -82,9 +82,9 @@ /** * Sets the filename for a given icon id, setting the icon to NULL will remove the icon from the theme * - * @param theme the theme - * @param icon_id a string representing what the icon is to be used for - * @param filename the name of the file to be used for the given id + * @theme: the theme + * @icon_id: a string representing what the icon is to be used for + * @filename: the name of the file to be used for the given id */ void pidgin_icon_theme_set_icon(PidginIconTheme *theme, const gchar *icon_id,
--- a/pidgin/gtkidle.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkidle.h Wed Jan 29 05:28:33 2014 +0530 @@ -38,7 +38,7 @@ /** * Returns the GTK+ idle UI ops. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleIdleUiOps *pidgin_idle_get_ui_ops(void);
--- a/pidgin/gtkimhtml.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkimhtml.h Wed Jan 29 05:28:33 2014 +0530 @@ -222,23 +222,23 @@ /** * Returns the GType object for an IM/HTML widget. * - * @return The GType for an IM/HTML widget. + * Returns: The GType for an IM/HTML widget. */ GType gtk_imhtml_get_type(void); /** * Creates and returns a new GTK+ IM/HTML widget. * - * @return The GTK+ IM/HTML widget created. + * Returns: The GTK+ IM/HTML widget created. */ GtkWidget *gtk_imhtml_new(void *, void *); /** * Returns the smiley object associated with the text. * - * @param imhtml The GTK+ IM/HTML. - * @param sml The name of the smiley category. - * @param text The text associated with the smiley. + * @imhtml: The GTK+ IM/HTML. + * @sml: The name of the smiley category. + * @text: The text associated with the smiley. */ GtkIMHtmlSmiley *gtk_imhtml_smiley_get(GtkIMHtml * imhtml, @@ -248,23 +248,23 @@ /** * Associates a smiley with a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param sml The name of the smiley category. - * @param smiley The GtkIMSmiley to associate. + * @imhtml: The GTK+ IM/HTML. + * @sml: The name of the smiley category. + * @smiley: The GtkIMSmiley to associate. */ void gtk_imhtml_associate_smiley(GtkIMHtml *imhtml, const gchar *sml, GtkIMHtmlSmiley *smiley); /** * Removes all smileys associated with a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_remove_smileys(GtkIMHtml *imhtml); /** * Sets the function callbacks to use with a GTK+ IM/HTML instance. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * @param f The GtkIMHTMLFuncs struct containing the functions to use. */ void gtk_imhtml_set_funcs(GtkIMHtml *imhtml, GtkIMHtmlFuncs *f); @@ -272,32 +272,32 @@ /** * Enables or disables showing the contents of HTML comments in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param show @c TRUE if comments should be shown, or @c FALSE otherwise. + * @imhtml: The GTK+ IM/HTML. + * @show: @c TRUE if comments should be shown, or @c FALSE otherwise. */ void gtk_imhtml_show_comments(GtkIMHtml *imhtml, gboolean show); /** * Gets the protocol name associated with this GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML + * @imhtml: The GTK+ IM/HTML */ const char *gtk_imhtml_get_protocol_name(GtkIMHtml *imhtml); /** * Associates a protocol name with a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param protocol_name The protocol name to associate with the IM/HTML. + * @imhtml: The GTK+ IM/HTML. + * @protocol_name: The protocol name to associate with the IM/HTML. */ void gtk_imhtml_set_protocol_name(GtkIMHtml *imhtml, const gchar *protocol_name); /** * Appends HTML formatted text to a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param text The formatted text to append. - * @param options A GtkIMHtmlOptions object indicating insert behavior. + * @imhtml: The GTK+ IM/HTML. + * @text: The formatted text to append. + * @options: A GtkIMHtmlOptions object indicating insert behavior. */ #define gtk_imhtml_append_text(imhtml, text, options) \ gtk_imhtml_append_text_with_images(imhtml, text, options, NULL) @@ -305,10 +305,10 @@ /** * Appends HTML formatted text to a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param text The formatted text to append. - * @param options A GtkIMHtmlOptions object indicating insert behavior. - * @param unused Use @c NULL value. + * @imhtml: The GTK+ IM/HTML. + * @text: The formatted text to append. + * @options: A GtkIMHtmlOptions object indicating insert behavior. + * @unused: Use @c NULL value. */ void gtk_imhtml_append_text_with_images(GtkIMHtml *imhtml, const gchar *text, @@ -318,10 +318,10 @@ /** * Inserts HTML formatted text to a GTK+ IM/HTML at a given iter. * - * @param imhtml The GTK+ IM/HTML. - * @param text The formatted text to append. - * @param options A GtkIMHtmlOptions object indicating insert behavior. - * @param iter A GtkTextIter in the GTK+ IM/HTML at which to insert text. + * @imhtml: The GTK+ IM/HTML. + * @text: The formatted text to append. + * @options: A GtkIMHtmlOptions object indicating insert behavior. + * @iter: A GtkTextIter in the GTK+ IM/HTML at which to insert text. */ void gtk_imhtml_insert_html_at_iter(GtkIMHtml *imhtml, const gchar *text, @@ -331,24 +331,24 @@ /** * Scrolls a GTK+ IM/HTML to the end of its contents. * - * @param imhtml The GTK+ IM/HTML. - * @param smooth A boolean indicating if smooth scrolling should be used. + * @imhtml: The GTK+ IM/HTML. + * @smooth: A boolean indicating if smooth scrolling should be used. */ void gtk_imhtml_scroll_to_end(GtkIMHtml *imhtml, gboolean smooth); /** * Delete the contents of a GTK+ IM/HTML between start and end. * - * @param imhtml The GTK+ IM/HTML. - * @param start a postition in the imhtml's buffer - * @param end another postition in the imhtml's buffer + * @imhtml: The GTK+ IM/HTML. + * @start: a postition in the imhtml's buffer + * @end: another postition in the imhtml's buffer */ void gtk_imhtml_delete(GtkIMHtml *imhtml, GtkTextIter *start, GtkTextIter *end); /** * Purges the contents from a GTK+ IM/HTML and resets formatting. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ #define gtk_imhtml_clear(imhtml) \ gtk_imhtml_delete(imhtml, NULL, NULL) @@ -356,44 +356,44 @@ /** * Scrolls a GTK+ IM/HTML up by one page. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_page_up(GtkIMHtml *imhtml); /** * Scrolls a GTK+ IM/HTML down by one page. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_page_down(GtkIMHtml *imhtml); /** * Creates and returns an new GTK+ IM/HTML scalable object. * - * @return A new IM/HTML Scalable object. + * Returns: A new IM/HTML Scalable object. */ GtkIMHtmlScalable *gtk_imhtml_scalable_new(void); /** * Creates and returns an new GTK+ IM/HTML scalable with a horizontal rule. * - * @return A new IM/HTML Scalable object with an image. + * Returns: A new IM/HTML Scalable object with an image. */ GtkIMHtmlScalable *gtk_imhtml_hr_new(void); /** * Destroys and frees a GTK+ IM/HTML scalable horizontal rule. * - * @param scale The GTK+ IM/HTML scalable. + * @scale: The GTK+ IM/HTML scalable. */ void gtk_imhtml_hr_free(GtkIMHtmlScalable *scale); /** * Rescales a GTK+ IM/HTML scalable horizontal rule to a given size. * - * @param scale The GTK+ IM/HTML scalable. - * @param width The new width. - * @param height The new height. + * @scale: The GTK+ IM/HTML scalable. + * @width: The new width. + * @height: The new height. */ void gtk_imhtml_hr_scale(GtkIMHtmlScalable *scale, int width, int height); @@ -401,34 +401,34 @@ * Adds a GTK+ IM/HTML scalable horizontal rule to a given GTK+ IM/HTML at * a given iter. * - * @param scale The GTK+ IM/HTML scalable. - * @param imhtml The GTK+ IM/HTML. - * @param iter The GtkTextIter at which to add the scalable. + * @scale: The GTK+ IM/HTML scalable. + * @imhtml: The GTK+ IM/HTML. + * @iter: The GtkTextIter at which to add the scalable. */ void gtk_imhtml_hr_add_to(GtkIMHtmlScalable *scale, GtkIMHtml *imhtml, GtkTextIter *iter); /** * Finds and highlights a given string in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param text The string to search for. + * @imhtml: The GTK+ IM/HTML. + * @text: The string to search for. * - * @return @c TRUE if a search was performed, or @c FALSE if not. + * Returns: @c TRUE if a search was performed, or @c FALSE if not. */ gboolean gtk_imhtml_search_find(GtkIMHtml *imhtml, const gchar *text); /** * Clears the highlighting from a prior search in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_search_clear(GtkIMHtml *imhtml); /** * Enables or disables editing in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param editable @c TRUE to make the widget editable, or @c FALSE otherwise. + * @imhtml: The GTK+ IM/HTML. + * @editable: @c TRUE to make the widget editable, or @c FALSE otherwise. */ void gtk_imhtml_set_editable(GtkIMHtml *imhtml, gboolean editable); @@ -437,25 +437,25 @@ * In this mode formatting options to the buffer take effect for the entire * buffer instead of specific text. * - * @param imhtml The GTK+ IM/HTML. - * @param wbfo @c TRUE to enable the mode, or @c FALSE otherwise. + * @imhtml: The GTK+ IM/HTML. + * @wbfo: @c TRUE to enable the mode, or @c FALSE otherwise. */ void gtk_imhtml_set_whole_buffer_formatting_only(GtkIMHtml *imhtml, gboolean wbfo); /** * Indicates which formatting functions to enable and disable in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param buttons A GtkIMHtmlButtons bitmask indicating which functions to use. + * @imhtml: The GTK+ IM/HTML. + * @buttons: A GtkIMHtmlButtons bitmask indicating which functions to use. */ void gtk_imhtml_set_format_functions(GtkIMHtml *imhtml, GtkIMHtmlButtons buttons); /** * Returns which formatting functions are enabled in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A GtkIMHtmlButtons bitmask indicating which functions to are enabled. + * Returns: A GtkIMHtmlButtons bitmask indicating which functions to are enabled. */ GtkIMHtmlButtons gtk_imhtml_get_format_functions(GtkIMHtml *imhtml); @@ -463,10 +463,10 @@ * Sets each boolean to @c TRUE or @c FALSE to indicate if that formatting option * is enabled at the current position in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param bold The boolean to set for bold or @c NULL. - * @param italic The boolean to set for italic or @c NULL. - * @param underline The boolean to set for underline or @c NULL. + * @imhtml: The GTK+ IM/HTML. + * @bold: The boolean to set for bold or @c NULL. + * @italic: The boolean to set for italic or @c NULL. + * @underline: The boolean to set for underline or @c NULL. */ void gtk_imhtml_get_current_format(GtkIMHtml *imhtml, gboolean *bold, gboolean *italic, gboolean *underline); @@ -474,9 +474,9 @@ * Returns a string containing the selected font face at the current position * in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A string containg the font face or @c NULL if none is set. + * Returns: A string containg the font face or @c NULL if none is set. */ char *gtk_imhtml_get_current_fontface(GtkIMHtml *imhtml); @@ -484,9 +484,9 @@ * Returns a string containing the selected foreground color at the current * position in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A string containg the foreground color or @c NULL if none is set. + * Returns: A string containg the foreground color or @c NULL if none is set. */ char *gtk_imhtml_get_current_forecolor(GtkIMHtml *imhtml); @@ -494,9 +494,9 @@ * Returns a string containing the selected font background color at the current * position in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A string containg the font background color or @c NULL if none is set. + * Returns: A string containg the font background color or @c NULL if none is set. */ char *gtk_imhtml_get_current_backcolor(GtkIMHtml *imhtml); @@ -504,9 +504,9 @@ * Returns a string containing the selected background color at the current * position in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A string containg the background color or @c NULL if none is set. + * Returns: A string containg the background color or @c NULL if none is set. */ char *gtk_imhtml_get_current_background(GtkIMHtml *imhtml); @@ -514,53 +514,53 @@ * Returns a integer containing the selected HTML font size at the current * position in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return The HTML font size. + * Returns: The HTML font size. */ gint gtk_imhtml_get_current_fontsize(GtkIMHtml *imhtml); /** * Checks whether a GTK+ IM/HTML is marked as editable. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return @c TRUE if the IM/HTML is editable, or @c FALSE otherwise. + * Returns: @c TRUE if the IM/HTML is editable, or @c FALSE otherwise. */ gboolean gtk_imhtml_get_editable(GtkIMHtml *imhtml); /** * Clear all the formatting on a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_clear_formatting(GtkIMHtml *imhtml); /** * Toggles bold at the cursor location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_toggle_bold(GtkIMHtml *imhtml); /** * Toggles italic at the cursor location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_toggle_italic(GtkIMHtml *imhtml); /** * Toggles underline at the cursor location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_toggle_underline(GtkIMHtml *imhtml); /** * Toggles strikethrough at the cursor location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_toggle_strike(GtkIMHtml *imhtml); @@ -568,10 +568,10 @@ * Toggles a foreground color at the current location or selection in a GTK * IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param color The HTML-style color, or @c NULL or "" to clear the color. + * @imhtml: The GTK+ IM/HTML. + * @color: The HTML-style color, or @c NULL or "" to clear the color. * - * @return @c TRUE if a color was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a color was set, or @c FALSE if it was cleared. */ gboolean gtk_imhtml_toggle_forecolor(GtkIMHtml *imhtml, const char *color); @@ -579,10 +579,10 @@ * Toggles a background color at the current location or selection in a GTK * IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param color The HTML-style color, or @c NULL or "" to clear the color. + * @imhtml: The GTK+ IM/HTML. + * @color: The HTML-style color, or @c NULL or "" to clear the color. * - * @return @c TRUE if a color was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a color was set, or @c FALSE if it was cleared. */ gboolean gtk_imhtml_toggle_backcolor(GtkIMHtml *imhtml, const char *color); @@ -590,20 +590,20 @@ * Toggles a background color at the current location or selection in a GTK * IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param color The HTML-style color, or @c NULL or "" to clear the color. + * @imhtml: The GTK+ IM/HTML. + * @color: The HTML-style color, or @c NULL or "" to clear the color. * - * @return @c TRUE if a color was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a color was set, or @c FALSE if it was cleared. */ gboolean gtk_imhtml_toggle_background(GtkIMHtml *imhtml, const char *color); /** * Toggles a font face at the current location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param face The font face name, or @c NULL or "" to clear the font. + * @imhtml: The GTK+ IM/HTML. + * @face: The font face name, or @c NULL or "" to clear the font. * - * @return @c TRUE if a font name was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a font name was set, or @c FALSE if it was cleared. */ gboolean gtk_imhtml_toggle_fontface(GtkIMHtml *imhtml, const char *face); @@ -611,36 +611,36 @@ * Toggles a link tag with the given URL at the current location or selection * in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param url The URL for the link or @c NULL to terminate the link. + * @imhtml: The GTK+ IM/HTML. + * @url: The URL for the link or @c NULL to terminate the link. */ void gtk_imhtml_toggle_link(GtkIMHtml *imhtml, const char *url); /** * Inserts a link to the given url at the given GtkTextMark in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param mark The GtkTextMark to insert the link at. - * @param url The URL for the link. - * @param text The string to use for the link description. + * @imhtml: The GTK+ IM/HTML. + * @mark: The GtkTextMark to insert the link at. + * @url: The URL for the link. + * @text: The string to use for the link description. */ void gtk_imhtml_insert_link(GtkIMHtml *imhtml, GtkTextMark *mark, const char *url, const char *text); /** * Inserts a smiley at the current location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param sml The category of the smiley. - * @param smiley The text of the smiley to insert. + * @imhtml: The GTK+ IM/HTML. + * @sml: The category of the smiley. + * @smiley: The text of the smiley to insert. */ void gtk_imhtml_insert_smiley(GtkIMHtml *imhtml, const char *sml, char *smiley); /** * Inserts a smiley at the given iter in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param sml The category of the smiley. - * @param smiley The text of the smiley to insert. - * @param iter The GtkTextIter in the IM/HTML to insert the smiley at. + * @imhtml: The GTK+ IM/HTML. + * @sml: The category of the smiley. + * @smiley: The text of the smiley to insert. + * @iter: The GtkTextIter in the IM/HTML to insert the smiley at. */ void gtk_imhtml_insert_smiley_at_iter(GtkIMHtml *imhtml, const char *sml, char *smiley, GtkTextIter *iter); @@ -648,17 +648,17 @@ * Inserts the IM/HTML scalable image with the given id at the given iter in a * GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param id The id of the IM/HTML scalable. - * @param iter The GtkTextIter in the IM/HTML to insert the image at. + * @imhtml: The GTK+ IM/HTML. + * @id: The id of the IM/HTML scalable. + * @iter: The GtkTextIter in the IM/HTML to insert the image at. */ void gtk_imhtml_insert_image_at_iter(GtkIMHtml *imhtml, int id, GtkTextIter *iter); /** * Sets the font size at the current location or selection in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param size The HTML font size to use. + * @imhtml: The GTK+ IM/HTML. + * @size: The HTML font size to use. */ void gtk_imhtml_font_set_size(GtkIMHtml *imhtml, gint size); @@ -666,7 +666,7 @@ * Decreases the font size by 1 at the current location or selection in a GTK * IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_font_shrink(GtkIMHtml *imhtml); @@ -674,27 +674,27 @@ * Increases the font size by 1 at the current location or selection in a GTK * IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. */ void gtk_imhtml_font_grow(GtkIMHtml *imhtml); /** * Returns the HTML formatted contents between two iters in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param start The GtkTextIter indicating the start point in the IM/HTML. - * @param end The GtkTextIter indicating the end point in the IM/HTML. + * @imhtml: The GTK+ IM/HTML. + * @start: The GtkTextIter indicating the start point in the IM/HTML. + * @end: The GtkTextIter indicating the end point in the IM/HTML. * - * @return A string containing the HTML formatted text. + * Returns: A string containing the HTML formatted text. */ char *gtk_imhtml_get_markup_range(GtkIMHtml *imhtml, GtkTextIter *start, GtkTextIter *end); /** * Returns the entire HTML formatted contents of a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A string containing the HTML formatted text. + * Returns: A string containing the HTML formatted text. */ char *gtk_imhtml_get_markup(GtkIMHtml *imhtml); @@ -702,9 +702,9 @@ * Returns a null terminated array of pointers to null terminated strings, each * string for each line. g_strfreev() should be called to free it when done. * - * @param imhtml The GTK+ IM/HTML. + * @imhtml: The GTK+ IM/HTML. * - * @return A null terminated array of null terminated HTML formatted strings. + * Returns: A null terminated array of null terminated HTML formatted strings. */ char **gtk_imhtml_get_markup_lines(GtkIMHtml *imhtml); @@ -712,31 +712,31 @@ * Returns the entire unformatted (plain text) contents of a GTK+ IM/HTML * between two iters in a GTK+ IM/HTML. * - * @param imhtml The GTK+ IM/HTML. - * @param start The GtkTextIter indicating the start point in the IM/HTML. - * @param stop The GtkTextIter indicating the end point in the IM/HTML. + * @imhtml: The GTK+ IM/HTML. + * @start: The GtkTextIter indicating the start point in the IM/HTML. + * @stop: The GtkTextIter indicating the end point in the IM/HTML. * - * @return A string containing the unformatted text. + * Returns: A string containing the unformatted text. */ char *gtk_imhtml_get_text(GtkIMHtml *imhtml, GtkTextIter *start, GtkTextIter *stop); /** * Setup formatting for an imhtml depending on the flags specified. * - * @param imhtml The GTK+ IM/HTML. - * @param flags The connection flag which describes the allowed types of formatting. + * @imhtml: The GTK+ IM/HTML. + * @flags: The connection flag which describes the allowed types of formatting. */ void gtk_imhtml_setup_entry(GtkIMHtml *imhtml, PurpleConnectionFlags flags); /** * Create a new GtkIMHtmlSmiley. * - * @param file The image file for the smiley - * @param shortcut The key shortcut for the smiley - * @param hide @c TRUE if the smiley should be hidden in the smiley dialog, @c FALSE otherwise - * @param flags The smiley flags + * @file: The image file for the smiley + * @shortcut: The key shortcut for the smiley + * @hide: @c TRUE if the smiley should be hidden in the smiley dialog, @c FALSE otherwise + * @flags: The smiley flags * - * @return The newly created smiley + * Returns: The newly created smiley */ GtkIMHtmlSmiley *gtk_imhtml_smiley_create(const char *file, const char *shortcut, gboolean hide, GtkIMHtmlSmileyFlags flags); @@ -744,14 +744,14 @@ /** * Reload the image data for the smiley. * - * @param smiley The smiley to reload + * @smiley: The smiley to reload */ void gtk_imhtml_smiley_reload(GtkIMHtmlSmiley *smiley); /** * Destroy a GtkIMHtmlSmiley. * - * @param smiley The smiley to destroy + * @smiley: The smiley to destroy */ void gtk_imhtml_smiley_destroy(GtkIMHtmlSmiley *smiley); @@ -759,17 +759,17 @@ * Register a protocol with the GtkIMHtml widget. Registering a protocol would * allow certain text to be clickable. * - * @param name The name of the protocol (e.g. http://) - * @param activate The callback to trigger when the protocol text is clicked. + * @name: The name of the protocol (e.g. http://) + * @activate: The callback to trigger when the protocol text is clicked. * Removes any current protocol definition if @c NULL. The * callback should return @c TRUE if the link was activated * properly, @c FALSE otherwise. - * @param context_menu The callback to trigger when the context menu is popped + * @context_menu: The callback to trigger when the context menu is popped * up on the protocol text. The callback should return * @c TRUE if the request for context menu was processed * successfully, @c FALSE otherwise. * - * @return @c TRUE if the protocol was successfully registered (or unregistered, when \a activate is @c NULL) + * Returns: @c TRUE if the protocol was successfully registered (or unregistered, when \a activate is @c NULL) */ gboolean gtk_imhtml_class_register_protocol(const char *name, gboolean (*activate)(GtkIMHtml *imhtml, GtkIMHtmlLink *link), @@ -778,18 +778,18 @@ /** * Get the URL associated with a link. This should be used by the IMHtml protocol-callbacks. * - * @param link The GtkIMHtmlLink object sent to the callback functions + * @link: The GtkIMHtmlLink object sent to the callback functions * - * @return The URL + * Returns: The URL */ const char *gtk_imhtml_link_get_url(GtkIMHtmlLink *link); /** * Get the GtkTextTag object (if any) associated with a particular link. * - * @param link The GtkIMHtmlLink object sent to the callback functions + * @link: The GtkIMHtmlLink object sent to the callback functions * - * @return The GtkTextTag object, or @c NULL + * Returns: The GtkTextTag object, or @c NULL */ const GtkTextTag *gtk_imhtml_link_get_text_tag(GtkIMHtmlLink *link); @@ -797,9 +797,9 @@ * Activates a GtkIMHtmlLink object. This triggers the 'url-clicked' signal, marks the * link as visited (when possible). * - * @param link The GtkIMHtmlLink object sent to the callback functions + * @link: The GtkIMHtmlLink object sent to the callback functions * - * @return @c TRUE if 'url-clicked' signal was emitted, @c FALSE otherwise. + * Returns: @c TRUE if 'url-clicked' signal was emitted, @c FALSE otherwise. */ gboolean gtk_imhtml_link_activate(GtkIMHtmlLink *link); @@ -809,7 +809,7 @@ * behavior, and you want the standard GtkTextView behavior of * inserting a newline into the buffer, then call this function. * - * @param imhtml The GtkIMHtml where you want the "return" key to add + * @imhtml: The GtkIMHtml where you want the "return" key to add * newline and not emit the "message_send" signal. */ void gtk_imhtml_set_return_inserts_newline(GtkIMHtml *imhtml); @@ -819,8 +819,8 @@ * text (as you would expect). For scenarios (e.g. select-on-focus) where this * would be problematic, this function can disable the PRIMARY population. * - * @param imhtml The GtkIMHtml to enable/disable populating PRIMARY - * @param populate enable/disable PRIMARY population + * @imhtml: The GtkIMHtml to enable/disable populating PRIMARY + * @populate: enable/disable PRIMARY population */ void gtk_imhtml_set_populate_primary_clipboard(GtkIMHtml *imhtml, gboolean populate);
--- a/pidgin/gtklog.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtklog.h Wed Jan 29 05:28:33 2014 +0530 @@ -72,7 +72,7 @@ /** * Returns the GTK+ log subsystem handle. * - * @return The GTK+ log subsystem handle. + * Returns: The GTK+ log subsystem handle. */ void *pidgin_log_get_handle(void);
--- a/pidgin/gtkmenutray.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkmenutray.h Wed Jan 29 05:28:33 2014 +0530 @@ -53,50 +53,50 @@ * Registers the PidginMenuTray class if necessary and returns the * type ID assigned to it. * - * @return The PidginMenuTray type ID + * Returns: The PidginMenuTray type ID */ GType pidgin_menu_tray_get_type(void); /** * Creates a new PidginMenuTray * - * @return A new PidginMenuTray + * Returns: A new PidginMenuTray */ GtkWidget *pidgin_menu_tray_new(void); /** * Gets the box for the PidginMenuTray * - * @param menu_tray The PidginMenuTray + * @menu_tray: The PidginMenuTray * - * @return The box that this menu tray is using + * Returns: The box that this menu tray is using */ GtkWidget *pidgin_menu_tray_get_box(PidginMenuTray *menu_tray); /** * Appends a widget into the tray * - * @param menu_tray The tray - * @param widget The widget - * @param tooltip The tooltip for this widget (widget requires its own X-window) + * @menu_tray: The tray + * @widget: The widget + * @tooltip: The tooltip for this widget (widget requires its own X-window) */ void pidgin_menu_tray_append(PidginMenuTray *menu_tray, GtkWidget *widget, const char *tooltip); /** * Prepends a widget into the tray * - * @param menu_tray The tray - * @param widget The widget - * @param tooltip The tooltip for this widget (widget requires its own X-window) + * @menu_tray: The tray + * @widget: The widget + * @tooltip: The tooltip for this widget (widget requires its own X-window) */ void pidgin_menu_tray_prepend(PidginMenuTray *menu_tray, GtkWidget *widget, const char *tooltip); /** * Set the tooltip for a widget * - * @param menu_tray The tray - * @param widget The widget - * @param tooltip The tooltip to set for the widget (widget requires its own X-window) + * @menu_tray: The tray + * @widget: The widget + * @tooltip: The tooltip to set for the widget (widget requires its own X-window) */ void pidgin_menu_tray_set_tooltip(PidginMenuTray *menu_tray, GtkWidget *widget, const char *tooltip);
--- a/pidgin/gtknotify.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtknotify.h Wed Jan 29 05:28:33 2014 +0530 @@ -34,12 +34,12 @@ /** * Adds a buddy pounce to the buddy pounce dialog * - * @param account The account - * @param pounce The pounce - * @param alias The buddy alias - * @param event Event description - * @param message Pounce message - * @param date Pounce date + * @account: The account + * @pounce: The pounce + * @alias: The buddy alias + * @event: Event description + * @message: Pounce message + * @date: Pounce date */ void pidgin_notify_pounce_add(PurpleAccount *account, PurplePounce *pounce, const char *alias, const char *event, const char *message, const char *date); @@ -47,7 +47,7 @@ /** * Returns the UI operations structure for GTK+ notification functions. * - * @return The GTK+ UI notify operations structure. + * Returns: The GTK+ UI notify operations structure. */ PurpleNotifyUiOps *pidgin_notify_get_ui_ops(void); @@ -66,14 +66,14 @@ /** * Returns TRUE if there are unseen emails, FALSE otherwise. * - * @return TRUE if there are unseen emails, FALSE otherwise. + * Returns: TRUE if there are unseen emails, FALSE otherwise. */ gboolean pidgin_notify_emails_pending(void); /** * Presents mail dialog to the user. * - * @return void. + * Returns: void. */ void pidgin_notify_emails_present(void *data);
--- a/pidgin/gtkplugin.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkplugin.h Wed Jan 29 05:28:33 2014 +0530 @@ -82,11 +82,11 @@ * which should be a callback that returns a GtkWidget for the plugin's * configuration (see PidginPluginConfigFrameCb). * - * @param first_property The first property name - * @param ... The value of the first property, followed optionally by more + * @first_property: The first property name + * @...: The value of the first property, followed optionally by more * name/value pairs, followed by @c NULL * - * @return A new #PidginPluginInfo instance. + * Returns: A new #PidginPluginInfo instance. * * @see purple_plugin_info_new() */
--- a/pidgin/gtkpluginpref.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkpluginpref.h Wed Jan 29 05:28:33 2014 +0530 @@ -36,8 +36,8 @@ /** * Creates a Gtk Preference frame for a PurplePluginPrefFrame * - * @param frame PurplePluginPrefFrame - * @return The gtk preference frame + * @frame: PurplePluginPrefFrame + * Returns: The gtk preference frame */ GtkWidget *pidgin_plugin_pref_create_frame(PurplePluginPrefFrame *frame);
--- a/pidgin/gtkpounce.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkpounce.h Wed Jan 29 05:28:33 2014 +0530 @@ -33,9 +33,9 @@ /** * Displays a New Buddy Pounce or Edit Buddy Pounce dialog. * - * @param account The optional account to use. - * @param name The optional name to pounce on. - * @param cur_pounce The current buddy pounce, if editing an existing one. + * @account: The optional account to use. + * @name: The optional name to pounce on. + * @cur_pounce: The current buddy pounce, if editing an existing one. */ void pidgin_pounce_editor_show(PurpleAccount *account, const char *name, PurplePounce *cur_pounce); @@ -53,7 +53,7 @@ /** * Returns the gtkpounces handle * - * @return The handle to the GTK+ pounces system + * Returns: The handle to the GTK+ pounces system */ void *pidgin_pounces_get_handle(void);
--- a/pidgin/gtkprefs.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkprefs.h Wed Jan 29 05:28:33 2014 +0530 @@ -44,9 +44,9 @@ /** * Add a new checkbox for a boolean preference * - * @param title The text to be displayed as the checkbox label - * @param key The key of the purple bool pref that will be represented by the checkbox - * @param page The page to which the new checkbox will be added + * @title: The text to be displayed as the checkbox label + * @key: The key of the purple bool pref that will be represented by the checkbox + * @page: The page to which the new checkbox will be added */ GtkWidget *pidgin_prefs_checkbox(const char *title, const char *key, GtkWidget *page); @@ -54,13 +54,13 @@ /** * Add a new spin button representing an int preference * - * @param page The page to which the spin button will be added - * @param title The text to be displayed as the spin button label - * @param key The key of the int pref that will be represented by the spin button - * @param min The minimum value of the spin button - * @param max The maximum value of the spin button - * @param sg If not NULL, the size group to which the spin button will be added - * @return An hbox containing both the label and the spinner. Can be + * @page: The page to which the spin button will be added + * @title: The text to be displayed as the spin button label + * @key: The key of the int pref that will be represented by the spin button + * @min: The minimum value of the spin button + * @max: The maximum value of the spin button + * @sg: If not NULL, the size group to which the spin button will be added + * Returns: An hbox containing both the label and the spinner. Can be * used to set the widgets to sensitive or insensitive based on the * value of a checkbox. */ @@ -70,12 +70,12 @@ /** * Add a new entry representing a string preference * - * @param page The page to which the entry will be added - * @param title The text to be displayed as the entry label - * @param key The key of the string pref that will be represented by the entry - * @param sg If not NULL, the size group to which the entry will be added + * @page: The page to which the entry will be added + * @title: The text to be displayed as the entry label + * @key: The key of the string pref that will be represented by the entry + * @sg: If not NULL, the size group to which the entry will be added * - * @return An hbox containing both the label and the entry. Can be used to set + * Returns: An hbox containing both the label and the entry. Can be used to set * the widgets to sensitive or insensitive based on the value of a * checkbox. */ @@ -86,12 +86,12 @@ * Add a new entry representing a password (string) preference * The entry will use a password-style text entry (the text is substituded) * - * @param page The page to which the entry will be added - * @param title The text to be displayed as the entry label - * @param key The key of the string pref that will be represented by the entry - * @param sg If not NULL, the size group to which the entry will be added + * @page: The page to which the entry will be added + * @title: The text to be displayed as the entry label + * @key: The key of the string pref that will be represented by the entry + * @sg: If not NULL, the size group to which the entry will be added * - * @return An hbox containing both the label and the entry. Can be used to set + * Returns: An hbox containing both the label and the entry. Can be used to set * the widgets to sensitive or insensitive based on the value of a * checkbox. */ @@ -101,11 +101,11 @@ /** * Add a new dropdown representing a preference of the specified type * - * @param page The page to which the dropdown will be added - * @param title The text to be displayed as the dropdown label - * @param type The type of preference to be stored in the generated dropdown - * @param key The key of the pref that will be represented by the dropdown - * @param ... The choices to be added to the dropdown, choices should be + * @page: The page to which the dropdown will be added + * @title: The text to be displayed as the dropdown label + * @type: The type of preference to be stored in the generated dropdown + * @key: The key of the pref that will be represented by the dropdown + * @...: The choices to be added to the dropdown, choices should be * paired as label/value */ GtkWidget *pidgin_prefs_dropdown(GtkWidget *page, const gchar *title, @@ -114,11 +114,11 @@ /** * Add a new dropdown representing a preference of the specified type * - * @param page The page to which the dropdown will be added - * @param title The text to be displayed as the dropdown label - * @param type The type of preference to be stored in the dropdown - * @param key The key of the pref that will be represented by the dropdown - * @param menuitems The choices to be added to the dropdown, choices should + * @page: The page to which the dropdown will be added + * @title: The text to be displayed as the dropdown label + * @type: The type of preference to be stored in the dropdown + * @key: The key of the pref that will be represented by the dropdown + * @menuitems: The choices to be added to the dropdown, choices should * be paired as label/value */ GtkWidget *pidgin_prefs_dropdown_from_list(GtkWidget *page,
--- a/pidgin/gtkprivacy.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkprivacy.h Wed Jan 29 05:28:33 2014 +0530 @@ -51,8 +51,8 @@ * * If @a name is not specified, an input dialog will be presented. * - * @param account The account. - * @param name The name of the user to add. + * @account: The account. + * @name: The name of the user to add. */ void pidgin_request_add_permit(PurpleAccount *account, const char *name); @@ -62,8 +62,8 @@ * * If @a name is not specified, an input dialog will be presented. * - * @param account The account. - * @param name The name of the user to add. + * @account: The account. + * @name: The name of the user to add. */ void pidgin_request_add_block(PurpleAccount *account, const char *name);
--- a/pidgin/gtkrequest.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkrequest.h Wed Jan 29 05:28:33 2014 +0530 @@ -33,16 +33,16 @@ /** * Returns the UI operations structure for GTK+ request functions. * - * @return The GTK+ UI request operations structure. + * Returns: The GTK+ UI request operations structure. */ PurpleRequestUiOps *pidgin_request_get_ui_ops(void); /** * Gets dialog window for specified libpurple request. * - * @param ui_handle The UI handle. + * @ui_handle: The UI handle. * - * @return The dialog window. + * Returns: The dialog window. */ GtkWindow * pidgin_request_get_dialog_window(void *ui_handle); @@ -55,7 +55,7 @@ /** * Returns the gtk requests subsystem handle. * - * @return The requests subsystem handle. + * Returns: The requests subsystem handle. */ void *pidgin_request_get_handle(void);
--- a/pidgin/gtkroomlist.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkroomlist.h Wed Jan 29 05:28:33 2014 +0530 @@ -38,7 +38,7 @@ /** * Determines if showing the room list dialog is a valid action. * - * @return TRUE if there are accounts online that support listing + * Returns: TRUE if there are accounts online that support listing * chat rooms. Otherwise return FALSE. */ gboolean pidgin_roomlist_is_showable(void); @@ -51,7 +51,7 @@ /** * Shows a new room list dialog and fetches the list for the specified account. * - * @param account The account to use. + * @account: The account to use. */ void pidgin_roomlist_dialog_show_with_account(PurpleAccount *account);
--- a/pidgin/gtksavedstatuses.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtksavedstatuses.h Wed Jan 29 05:28:33 2014 +0530 @@ -45,14 +45,14 @@ * Shows a status editor (used for adding a new saved status or * editing an already existing saved status). * - * @param edit TRUE if we want to edit an existing saved + * @edit: TRUE if we want to edit an existing saved * status or FALSE to create a new one. You * can not edit transient statuses--they don't * have titles. If you want to edit a transient * status, set this to FALSE and seed the dialog * with the transient status using the status * parameter to this function. - * @param status If edit is TRUE then this should be a + * @status: If edit is TRUE then this should be a * pointer to the PurpleSavedStatus to edit. * If edit is FALSE then this can be NULL, * or you can pass in a saved status to @@ -64,16 +64,16 @@ * Creates a dropdown menu of saved statuses and calls a callback * when one is selected * - * @param status The default saved_status to show as 'selected' - * @param callback The callback to call when the selection changes - * @return The menu widget + * @status: The default saved_status to show as 'selected' + * @callback: The callback to call when the selection changes + * Returns: The menu widget */ GtkWidget *pidgin_status_menu(PurpleSavedStatus *status, GCallback callback); /** * Returns the GTK+ status handle. * - * @return The handle to the GTK+ status system. + * Returns: The handle to the GTK+ status system. */ void *pidgin_status_get_handle(void);
--- a/pidgin/gtksession.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtksession.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,10 +37,10 @@ * Register this instance of Pidgin with the user's current session * manager. * - * @param argv0 The first argument passed into the program. This + * @argv0: The first argument passed into the program. This * will be the name of the executable, e.g. 'purple' - * @param previous_id An optional session ID to use. This can be NULL. - * @param config_dir The path to the configuration directory used by + * @previous_id: An optional session ID to use. This can be NULL. + * @config_dir: The path to the configuration directory used by * this instance of this program, e.g. '/home/user/.purple' */ void pidgin_session_init(gchar *argv0, gchar *previous_id, gchar *config_dir);
--- a/pidgin/gtksmiley.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtksmiley.h Wed Jan 29 05:28:33 2014 +0530 @@ -37,14 +37,14 @@ * Add a PurpleSmiley to the GtkIMHtmlSmiley's list to be able to use it * in pidgin * - * @param smiley The smiley to be added. + * @smiley: The smiley to be added. */ void pidgin_smiley_add_to_list(PurpleSmiley *smiley); /** * Delete a PurpleSmiley from the GtkIMHtmlSmiley's list * - * @param smiley The smiley to be deleted. + * @smiley: The smiley to be deleted. */ void pidgin_smiley_del_from_list(PurpleSmiley *smiley); @@ -61,7 +61,7 @@ /** * Returns a GSList with the GtkIMHtmlSmiley of each custom smiley * - * @constreturn A GtkIMHmlSmiley list + * Returns: (TODO const): A GtkIMHmlSmiley list */ GSList *pidgin_smileys_get_all(void); @@ -76,9 +76,9 @@ /** * Shows an editor for a smiley. * - * @param widget The parent widget to be linked or @c NULL - * @param smiley The PurpleSmiley to be edited, or @c NULL for a new smiley - * @return The smiley add dialog + * @widget: The parent widget to be linked or @c NULL + * @smiley: The PurpleSmiley to be edited, or @c NULL for a new smiley + * Returns: The smiley add dialog * * @see pidgin_smiley_editor_set_shortcut * @see pidgin_smiley_editor_set_image @@ -88,25 +88,25 @@ /** * Set the shortcut in a smiley add dialog * - * @param editor A smiley editor dialog (created by pidgin_smiley_edit) - * @param shortcut The shortcut to set + * @editor: A smiley editor dialog (created by pidgin_smiley_edit) + * @shortcut: The shortcut to set */ void pidgin_smiley_editor_set_shortcut(PidginSmiley *editor, const gchar *shortcut); /** * Set the image in a smiley add dialog * - * @param editor A smiley editor dialog - * @param image A GdkPixbuf image + * @editor: A smiley editor dialog + * @image: A GdkPixbuf image */ void pidgin_smiley_editor_set_image(PidginSmiley *editor, GdkPixbuf *image); /** * Sets the image data in a smiley add dialog * - * @param editor A smiley editor dialog - * @param data A pointer to smiley's data - * @param datasize The size of smiley's data + * @editor: A smiley editor dialog + * @data: A pointer to smiley's data + * @datasize: The size of smiley's data */ void pidgin_smiley_editor_set_data(PidginSmiley *editor, gpointer data, gsize datasize);
--- a/pidgin/gtksound.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtksound.h Wed Jan 29 05:28:33 2014 +0530 @@ -38,37 +38,37 @@ /** * Get the prefs option for an event. * - * @param event The event. - * @return The option. + * @event: The event. + * Returns: The option. */ const char *pidgin_sound_get_event_option(PurpleSoundEventID event); /** * Get the label for an event. * - * @param event The event. - * @return The label. + * @event: The event. + * Returns: The label. */ const char *pidgin_sound_get_event_label(PurpleSoundEventID event); /** * Gets GTK+ sound UI ops. * - * @return The UI operations structure. + * Returns: The UI operations structure. */ PurpleSoundUiOps *pidgin_sound_get_ui_ops(void); /** * Get the handle for the GTK+ sound system. * - * @return The handle to the sound system + * Returns: The handle to the sound system */ void *pidgin_sound_get_handle(void); /** * Returns true Pidgin is using customized sounds * - * @return TRUE if non default sounds are used. + * Returns: TRUE if non default sounds are used. */ gboolean pidgin_sound_is_customized(void);
--- a/pidgin/gtkutils.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkutils.h Wed Jan 29 05:28:33 2014 +0530 @@ -82,7 +82,7 @@ * Sets up a gtkwebview widget, loads it with smileys, and sets the * default signal handlers. * - * @param webview The gtkwebview widget to setup. + * @webview: The gtkwebview widget to setup. */ void pidgin_setup_webview(GtkWidget *webview); @@ -91,74 +91,74 @@ * function puts both widgets in a nice GtkFrame. They're separated by an * attractive GtkSeparator. * - * @param editable @c TRUE if this webview should be editable. If this is + * @editable: @c TRUE if this webview should be editable. If this is * @c FALSE, then the toolbar will NOT be created. If this webview * should be read-only at first, but may become editable later, then * pass in @c TRUE here and then manually call gtk_webview_set_editable() * later. - * @param webview_ret A pointer to a pointer to a GtkWidget. This pointer + * @webview_ret: A pointer to a pointer to a GtkWidget. This pointer * will be set to the webview when this function exits. - * @param sw_ret This will be filled with a pointer to the scrolled window + * @sw_ret: This will be filled with a pointer to the scrolled window * widget which contains the webview. * - * @return The GtkFrame containing the toolbar and webview. + * Returns: The GtkFrame containing the toolbar and webview. */ GtkWidget *pidgin_create_webview(gboolean editable, GtkWidget **webview_ret, GtkWidget **sw_ret); /** * Creates a small button * - * @param image A button image. + * @image: A button image. * - * @return A GtkButton created from the image. + * Returns: A GtkButton created from the image. */ GtkWidget *pidgin_create_small_button(GtkWidget *image); /** * Creates a new window * - * @param title The window title, or @c NULL - * @param border_width The window's desired border width - * @param role A string indicating what the window is responsible for doing, or @c NULL - * @param resizable Whether the window should be resizable (@c TRUE) or not (@c FALSE) + * @title: The window title, or @c NULL + * @border_width: The window's desired border width + * @role: A string indicating what the window is responsible for doing, or @c NULL + * @resizable: Whether the window should be resizable (@c TRUE) or not (@c FALSE) */ GtkWidget *pidgin_create_window(const char *title, guint border_width, const char *role, gboolean resizable); /** * Creates a new dialog window * - * @param title The window title, or @c NULL - * @param border_width The window's desired border width - * @param role A string indicating what the window is responsible for doing, or @c NULL - * @param resizable Whether the window should be resizable (@c TRUE) or not (@c FALSE) + * @title: The window title, or @c NULL + * @border_width: The window's desired border width + * @role: A string indicating what the window is responsible for doing, or @c NULL + * @resizable: Whether the window should be resizable (@c TRUE) or not (@c FALSE) */ GtkWidget *pidgin_create_dialog(const char *title, guint border_width, const char *role, gboolean resizable); /** * Retrieves the main content box (vbox) from a pidgin dialog window * - * @param dialog The dialog window - * @param homogeneous TRUE if all children are to be given equal space allotments. - * @param spacing the number of pixels to place by default between children + * @dialog: The dialog window + * @homogeneous: TRUE if all children are to be given equal space allotments. + * @spacing: the number of pixels to place by default between children */ GtkWidget *pidgin_dialog_get_vbox_with_properties(GtkDialog *dialog, gboolean homogeneous, gint spacing); /** * Retrieves the main content box (vbox) from a pidgin dialog window * - * @param dialog The dialog window + * @dialog: The dialog window */ GtkWidget *pidgin_dialog_get_vbox(GtkDialog *dialog); /** * Add a button to a dialog created by #pidgin_create_dialog. * - * @param dialog The dialog window - * @param label The stock-id or the label for the button - * @param callback The callback function for the button - * @param callbackdata The user data for the callback function + * @dialog: The dialog window + * @label: The stock-id or the label for the button + * @callback: The callback function for the button + * @callbackdata: The user data for the callback function * - * @return The created button. + * Returns: The created button. */ GtkWidget *pidgin_dialog_add_button(GtkDialog *dialog, const char *label, GCallback callback, gpointer callbackdata); @@ -166,15 +166,15 @@ /** * Retrieves the action area (button box) from a pidgin dialog window * - * @param dialog The dialog window + * @dialog: The dialog window */ GtkWidget *pidgin_dialog_get_action_area(GtkDialog *dialog); /** * Toggles the sensitivity of a widget. * - * @param widget @c NULL. Used for signal handlers. - * @param to_toggle The widget to toggle. + * @widget: @c NULL. Used for signal handlers. + * @to_toggle: The widget to toggle. */ void pidgin_toggle_sensitive(GtkWidget *widget, GtkWidget *to_toggle); @@ -183,8 +183,8 @@ * so, the GTK_RESPONSE_OK on the given dialog is set to TRUE. * Otherwise GTK_RESPONSE_OK is set to FALSE. * - * @param entry The text entry widget. - * @param dialog The dialog containing the text entry widget. + * @entry: The text entry widget. + * @dialog: The dialog containing the text entry widget. */ void pidgin_set_sensitive_if_input(GtkWidget *entry, GtkWidget *dialog); @@ -192,47 +192,47 @@ * Toggles the sensitivity of all widgets in a pointer array. * * @param w @c NULL. Used for signal handlers. - * @param data The array containing the widgets to toggle. + * @data: The array containing the widgets to toggle. */ void pidgin_toggle_sensitive_array(GtkWidget *w, GPtrArray *data); /** * Toggles the visibility of a widget. * - * @param widget @c NULL. Used for signal handlers. - * @param to_toggle The widget to toggle. + * @widget: @c NULL. Used for signal handlers. + * @to_toggle: The widget to toggle. */ void pidgin_toggle_showhide(GtkWidget *widget, GtkWidget *to_toggle); /** * Adds a separator to a menu. * - * @param menu The menu to add a separator to. + * @menu: The menu to add a separator to. * - * @return The separator. + * Returns: The separator. */ GtkWidget *pidgin_separator(GtkWidget *menu); /** * Creates a menu item. * - * @param menu The menu to which to append the menu item. - * @param str The title to use for the newly created menu item. + * @menu: The menu to which to append the menu item. + * @str: The title to use for the newly created menu item. * - * @return The newly created menu item. + * Returns: The newly created menu item. */ GtkWidget *pidgin_new_item(GtkWidget *menu, const char *str); /** * Creates a check menu item. * - * @param menu The menu to which to append the check menu item. - * @param str The title to use for the newly created menu item. - * @param cb A function to call when the menu item is activated. - * @param data Data to pass to the signal function. - * @param checked The initial state of the check item + * @menu: The menu to which to append the check menu item. + * @str: The title to use for the newly created menu item. + * @cb: A function to call when the menu item is activated. + * @data: Data to pass to the signal function. + * @checked: The initial state of the check item * - * @return The newly created menu item. + * Returns: The newly created menu item. */ GtkWidget *pidgin_new_check_item(GtkWidget *menu, const char *str, GCallback cb, gpointer data, gboolean checked); @@ -240,17 +240,17 @@ /** * Creates a menu item. * - * @param menu The menu to which to append the menu item. - * @param str The title for the menu item. - * @param icon An icon to place to the left of the menu item, + * @menu: The menu to which to append the menu item. + * @str: The title for the menu item. + * @icon: An icon to place to the left of the menu item, * or @c NULL for no icon. - * @param cb A function to call when the menu item is activated. - * @param data Data to pass to the signal function. - * @param accel_key Something. - * @param accel_mods Something. - * @param mod Something. + * @cb: A function to call when the menu item is activated. + * @data: Data to pass to the signal function. + * @accel_key: Something. + * @accel_mods: Something. + * @mod: Something. * - * @return The newly created menu item. + * Returns: The newly created menu item. */ GtkWidget *pidgin_new_item_from_stock(GtkWidget *menu, const char *str, const char *icon, GCallback cb, @@ -260,11 +260,11 @@ /** * Creates a button with the specified text and stock icon. * - * @param text The text for the button. - * @param icon The stock icon name. - * @param style The orientation of the button. + * @text: The text for the button. + * @icon: The stock icon name. + * @style: The orientation of the button. * - * @return The button. + * Returns: The button. */ GtkWidget *pidgin_pixbuf_button_from_stock(const char *text, const char *icon, PidginButtonOrientation style); @@ -272,30 +272,30 @@ /** * Creates a toolbar button with the stock icon. * - * @param stock The stock icon name. + * @stock: The stock icon name. * - * @return The button. + * Returns: The button. */ GtkWidget *pidgin_pixbuf_toolbar_button_from_stock(const char *stock); /** * Creates a HIG preferences frame. * - * @param parent The widget to put the frame into. - * @param title The title for the frame. + * @parent: The widget to put the frame into. + * @title: The title for the frame. * - * @return The vbox to put things into. + * Returns: The vbox to put things into. */ GtkWidget *pidgin_make_frame(GtkWidget *parent, const char *title); /** * Creates a drop-down option menu filled with protocols. * - * @param id The protocol to select by default. - * @param cb The callback to call when a protocol is selected. - * @param user_data Data to pass to the callback function. + * @id: The protocol to select by default. + * @cb: The callback to call when a protocol is selected. + * @user_data: Data to pass to the callback function. * - * @return The drop-down option menu. + * Returns: The drop-down option menu. */ GtkWidget *pidgin_protocol_option_menu_new(const char *id, GCallback cb, @@ -304,24 +304,24 @@ /** * Gets the currently selected protocol from a protocol drop down box. * - * @param optmenu The drop-down option menu created by + * @optmenu: The drop-down option menu created by * pidgin_account_option_menu_new. - * @return Returns the protocol ID that is currently selected. + * Returns: Returns the protocol ID that is currently selected. */ const char *pidgin_protocol_option_menu_get_selected(GtkWidget *optmenu); /** * Creates a drop-down option menu filled with accounts. * - * @param default_account The account to select by default. - * @param show_all Whether or not to show all accounts, or just + * @default_account: The account to select by default. + * @show_all: Whether or not to show all accounts, or just * active accounts. - * @param cb The callback to call when an account is selected. - * @param filter_func A function for checking if an account should + * @cb: The callback to call when an account is selected. + * @filter_func: A function for checking if an account should * be shown. This can be NULL. - * @param user_data Data to pass to the callback function. + * @user_data: Data to pass to the callback function. * - * @return The drop-down option menu. + * Returns: The drop-down option menu. */ GtkWidget *pidgin_account_option_menu_new(PurpleAccount *default_account, gboolean show_all, GCallback cb, @@ -330,41 +330,41 @@ /** * Gets the currently selected account from an account drop down box. * - * @param optmenu The drop-down option menu created by + * @optmenu: The drop-down option menu created by * pidgin_account_option_menu_new. - * @return Returns the PurpleAccount that is currently selected. + * Returns: Returns the PurpleAccount that is currently selected. */ PurpleAccount *pidgin_account_option_menu_get_selected(GtkWidget *optmenu); /** * Sets the currently selected account for an account drop down box. * - * @param optmenu The GtkOptionMenu created by + * @optmenu: The GtkOptionMenu created by * pidgin_account_option_menu_new. - * @param account The PurpleAccount to select. + * @account: The PurpleAccount to select. */ void pidgin_account_option_menu_set_selected(GtkWidget *optmenu, PurpleAccount *account); /** * Add autocompletion of screenames to an entry, supporting a filtering function. * - * @param entry The GtkEntry on which to setup autocomplete. - * @param optmenu A menu for accounts, returned by pidgin_account_option_menu_new(). + * @entry: The GtkEntry on which to setup autocomplete. + * @optmenu: A menu for accounts, returned by pidgin_account_option_menu_new(). * If @a optmenu is not @c NULL, it'll be updated when a username is chosen * from the autocomplete list. - * @param filter_func A function for checking if an autocomplete entry + * @filter_func: A function for checking if an autocomplete entry * should be shown. This can be @c NULL. - * @param user_data The data to be passed to the filter_func function. + * @user_data: The data to be passed to the filter_func function. */ void pidgin_setup_screenname_autocomplete(GtkWidget *entry, GtkWidget *optmenu, PidginFilterBuddyCompletionEntryFunc filter_func, gpointer user_data); /** * The default filter function for username autocomplete. * - * @param completion_entry The completion entry to filter. - * @param all_accounts If this is @c FALSE, only the autocompletion entries + * @completion_entry: The completion entry to filter. + * @all_accounts: If this is @c FALSE, only the autocompletion entries * which belong to an online account will be filtered. - * @return Returns @c TRUE if the autocompletion entry is filtered. + * Returns: Returns @c TRUE if the autocompletion entry is filtered. */ gboolean pidgin_screenname_autocomplete_default_filter(const PidginBuddyCompletionEntry *completion_entry, gpointer all_accounts); @@ -374,7 +374,7 @@ * * This does nothing if Pidgin is not compiled with GtkSpell support. * - * @param textview The textview widget to setup spellchecking for. + * @textview: The textview widget to setup spellchecking for. */ void pidgin_setup_gtkspell(GtkTextView *textview); @@ -398,17 +398,17 @@ /** * Get information about a user. Show immediate feedback. * - * @param conn The connection to get information from. - * @param name The user to get information about. + * @conn: The connection to get information from. + * @name: The user to get information about. */ void pidgin_retrieve_user_info(PurpleConnection *conn, const char *name); /** * Get information about a user in a chat. Show immediate feedback. * - * @param conn The connection to get information from. - * @param name The user to get information about. - * @param chatid The chat id. + * @conn: The connection to get information from. + * @name: The user to get information about. + * @chatid: The chat id. */ void pidgin_retrieve_user_info_in_chat(PurpleConnection *conn, const char *name, int chatid); @@ -416,16 +416,16 @@ * Parses an application/x-im-contact MIME message and returns the * data inside. * - * @param msg The MIME message. - * @param all_accounts If TRUE, check all compatible accounts, online or + * @msg: The MIME message. + * @all_accounts: If TRUE, check all compatible accounts, online or * offline. If FALSE, check only online accounts. - * @param ret_account The best guess at a compatible protocol, + * @ret_account: The best guess at a compatible protocol, * based on ret_protocol. If NULL, no account was found. - * @param ret_protocol The returned protocol type. - * @param ret_username The returned username. - * @param ret_alias The returned alias. + * @ret_protocol: The returned protocol type. + * @ret_username: The returned username. + * @ret_alias: The returned alias. * - * @return TRUE if the message was parsed for the minimum necessary data. + * Returns: TRUE if the message was parsed for the minimum necessary data. * FALSE otherwise. */ gboolean pidgin_parse_x_im_contact(const char *msg, gboolean all_accounts, @@ -454,13 +454,13 @@ * A helper function for GtkMenuPositionFuncs. This ensures the menu will * be kept on screen if possible. * - * @param menu The menu we are positioning. + * @menu: The menu we are positioning. * @param x Address of the gint representing the horizontal position * where the menu shall be drawn. This is an output parameter. * @param y Address of the gint representing the vertical position * where the menu shall be drawn. This is an output parameter. - * @param push_in This is an output parameter? - * @param data Not used by this particular position function. + * @push_in: This is an output parameter? + * @data: Not used by this particular position function. */ void pidgin_menu_position_func_helper(GtkMenu *menu, gint *x, gint *y, gboolean *push_in, gpointer data); @@ -472,13 +472,13 @@ * then you should just use GTK's built-in position function, * because it does a better job of positioning the menu. * - * @param menu The menu we are positioning. + * @menu: The menu we are positioning. * @param x Address of the gint representing the horizontal position * where the menu shall be drawn. This is an output parameter. * @param y Address of the gint representing the vertical position * where the menu shall be drawn. This is an output parameter. - * @param push_in This is an output parameter? - * @param user_data Not used by this particular position function. + * @push_in: This is an output parameter? + * @user_data: Not used by this particular position function. */ void pidgin_treeview_popup_menu_position_func(GtkMenu *menu, gint *x, @@ -489,9 +489,9 @@ /** * Manages drag'n'drop of files. * - * @param sd GtkSelectionData for managing drag'n'drop - * @param account Account to be used (may be NULL if conv is not NULL) - * @param who Buddy name (may be NULL if conv is not NULL) + * @sd: GtkSelectionData for managing drag'n'drop + * @account: Account to be used (may be NULL if conv is not NULL) + * @who: Buddy name (may be NULL if conv is not NULL) */ void pidgin_dnd_file_manage(GtkSelectionData *sd, PurpleAccount *account, const char *who); @@ -504,10 +504,10 @@ * Returns the base image to represent the account, based on * the currently selected theme. * - * @param account The account. - * @param size The size of the icon to return. + * @account: The account. + * @size: The size of the icon to return. * - * @return A newly-created pixbuf with a reference count of 1, + * Returns: A newly-created pixbuf with a reference count of 1, * or NULL if any of several error conditions occurred: * the file could not be opened, there was no loader * for the file's format, there was not enough memory @@ -519,39 +519,39 @@ /** * Creates a status icon for a given primitve * - * @param primitive The status primitive + * @primitive: The status primitive * @param w The widget to render this - * @param size The icon size to render at - * @return A GdkPixbuf, created from stock + * @size: The icon size to render at + * Returns: A GdkPixbuf, created from stock */ GdkPixbuf * pidgin_create_status_icon(PurpleStatusPrimitive primitive, GtkWidget *w, const char *size); /** * Returns an appropriate stock-id for a status primitive. * - * @param prim The status primitive + * @prim: The status primitive * - * @return The stock-id + * Returns: The stock-id */ const char *pidgin_stock_id_from_status_primitive(PurpleStatusPrimitive prim); /** * Returns an appropriate stock-id for a PurplePresence. * - * @param presence The presence. + * @presence: The presence. * - * @return The stock-id + * Returns: The stock-id */ const char *pidgin_stock_id_from_presence(PurplePresence *presence); /** * Append a PurpleMenuAction to a menu. * - * @param menu The menu to append to. - * @param act The PurpleMenuAction to append. - * @param gobject The object to be passed to the action callback. + * @menu: The menu to append to. + * @act: The PurpleMenuAction to append. + * @gobject: The object to be passed to the action callback. * - * @return The menuitem added. + * Returns: The menuitem added. */ GtkWidget *pidgin_append_menu_action(GtkWidget *menu, PurpleMenuAction *act, gpointer gobject); @@ -564,8 +564,8 @@ * * If the window for @a widget is @c NULL, this function simply returns. * - * @param widget The widget for which to set the mouse pointer - * @param cursor_type The type of cursor to set + * @widget: The widget for which to set the mouse pointer + * @cursor_type: The type of cursor to set */ void pidgin_set_cursor(GtkWidget *widget, GdkCursorType cursor_type); @@ -583,21 +583,21 @@ /** * Creates a File Selection widget for choosing a buddy icon * - * @param parent The parent window - * @param callback The callback to call when the window is closed. If the user chose an icon, the char* argument will point to its path - * @param data Data to pass to @a callback - * @return The file dialog + * @parent: The parent window + * @callback: The callback to call when the window is closed. If the user chose an icon, the char* argument will point to its path + * @data: Data to pass to @a callback + * Returns: The file dialog */ GtkWidget *pidgin_buddy_icon_chooser_new(GtkWindow *parent, void(*callback)(const char*,gpointer), gpointer data); /** * Converts a buddy icon to the required size and format * - * @param protocol The protocol to convert the icon - * @param path The path of a file to convert - * @param len If not @c NULL, the length of the returned data will be set here. + * @protocol: The protocol to convert the icon + * @path: The path of a file to convert + * @len: If not @c NULL, the length of the returned data will be set here. * - * @return The converted image data, or @c NULL if an error occurred. + * Returns: The converted image data, or @c NULL if an error occurred. */ gpointer pidgin_convert_buddy_icon(PurpleProtocol *protocol, const char *path, size_t *len); @@ -605,8 +605,8 @@ * Converts "->" and "<-" in strings to Unicode arrow characters, for use in referencing * menu items. * - * @param str The text to convert - * @return A newly allocated string with unicode arrow characters + * @str: The text to convert + * Returns: A newly allocated string with unicode arrow characters */ char *pidgin_make_pretty_arrows(const char *str); @@ -619,16 +619,16 @@ * Creates a #PidginMiniDialog, tied to a #PurpleConnection, suitable for * embedding in the buddy list scrollbook with pidgin_blist_add_alert(). * - * @param handle The #PurpleConnection to which this mini-dialog + * @handle: The #PurpleConnection to which this mini-dialog * refers, or @c NULL if it does not refer to a * connection. If @a handle is supplied, the mini-dialog * will be automatically removed and destroyed when the * connection signs off. - * @param stock_id The ID of a stock image to use in the mini dialog. - * @param primary The primary text - * @param secondary The secondary text, or @c NULL for no description. - * @param user_data Data to pass to the callbacks - * @param ... a <tt>NULL</tt>-terminated list of button labels + * @stock_id: The ID of a stock image to use in the mini dialog. + * @primary: The primary text + * @secondary: The secondary text, or @c NULL for no description. + * @user_data: Data to pass to the callbacks + * @...: a <tt>NULL</tt>-terminated list of button labels * (<tt>char *</tt>) and callbacks * (#PidginUtilMiniDialogCallback). @a user_data will be * passed as the first argument. (Callbacks may lack a @@ -636,7 +636,7 @@ * the corresponding button is pressed.) When a button is * pressed, the callback (if any) will be called; when * the callback returns the dialog will be destroyed. - * @return A #PidginMiniDialog, suitable for passing to + * Returns: A #PidginMiniDialog, suitable for passing to * pidgin_blist_add_alert(). * @see pidginstock.h */ @@ -670,8 +670,8 @@ * Sets or resets a window to 'urgent,' by setting the URGENT hint in X * or blinking in the win32 taskbar * - * @param window The window to draw attention to - * @param urgent Whether to set the urgent hint or not + * @window: The window to draw attention to + * @urgent: Whether to set the urgent hint or not */ void pidgin_set_urgent(GtkWindow *window, gboolean urgent); @@ -679,15 +679,15 @@ * Returns TRUE if the GdkPixbuf is opaque, as determined by no * alpha at any of the edge pixels. * - * @param pixbuf The pixbug - * @return TRUE if the pixbuf is opaque around the edges, FALSE otherwise + * @pixbuf: The pixbug + * Returns: TRUE if the pixbuf is opaque around the edges, FALSE otherwise */ gboolean pidgin_gdk_pixbuf_is_opaque(GdkPixbuf *pixbuf); /** * Rounds the corners of a 32x32 GdkPixbuf in place * - * @param pixbuf The buddy icon to transform + * @pixbuf: The buddy icon to transform */ void pidgin_gdk_pixbuf_make_round(GdkPixbuf *pixbuf); @@ -695,18 +695,18 @@ * Returns an HTML-style color string for use as a dim grey * string * - * @param widget The widget to return dim grey for - * @return The dim grey string + * @widget: The widget to return dim grey for + * Returns: The dim grey string */ const char *pidgin_get_dim_grey_string(GtkWidget *widget); /** * Create a simple text GtkComboBoxEntry equivalent * - * @param default_item Initial contents of GtkEntry - * @param items GList containing strings to add to GtkComboBox + * @default_item: Initial contents of GtkEntry + * @items: GList containing strings to add to GtkComboBox * - * @return A newly created text GtkComboBox containing a GtkEntry + * Returns: A newly created text GtkComboBox containing a GtkEntry * child. */ GtkWidget *pidgin_text_combo_box_entry_new(const char *default_item, GList *items); @@ -714,50 +714,50 @@ /** * Retrieve the text from the entry of the simple text GtkComboBoxEntry equivalent * - * @param widget The simple text GtkComboBoxEntry equivalent widget + * @widget: The simple text GtkComboBoxEntry equivalent widget * - * @return The text in the widget's entry. It must not be freed + * Returns: The text in the widget's entry. It must not be freed */ const char *pidgin_text_combo_box_entry_get_text(GtkWidget *widget); /** * Set the text in the entry of the simple text GtkComboBoxEntry equivalent * - * @param widget The simple text GtkComboBoxEntry equivalent widget - * @param text The text to set + * @widget: The simple text GtkComboBoxEntry equivalent widget + * @text: The text to set */ void pidgin_text_combo_box_entry_set_text(GtkWidget *widget, const char *text); /** * Automatically make a window transient to a suitable parent window. * - * @param window The window to make transient. + * @window: The window to make transient. * - * @return Whether the window was made transient or not. + * Returns: Whether the window was made transient or not. */ gboolean pidgin_auto_parent_window(GtkWidget *window); /** * Add a labelled widget to a GtkVBox * - * @param vbox The GtkVBox to add the widget to. - * @param widget_label The label to give the widget, can be @c NULL. - * @param sg The GtkSizeGroup to add the label to, can be @c NULL. - * @param widget The GtkWidget to add. - * @param expand Whether to expand the widget horizontally. - * @param p_label Place to store a pointer to the GtkLabel, or @c NULL if you don't care. + * @vbox: The GtkVBox to add the widget to. + * @widget_label: The label to give the widget, can be @c NULL. + * @sg: The GtkSizeGroup to add the label to, can be @c NULL. + * @widget: The GtkWidget to add. + * @expand: Whether to expand the widget horizontally. + * @p_label: Place to store a pointer to the GtkLabel, or @c NULL if you don't care. * - * @return A GtkHBox already added to the GtkVBox containing the GtkLabel and the GtkWidget. + * Returns: A GtkHBox already added to the GtkVBox containing the GtkLabel and the GtkWidget. */ GtkWidget *pidgin_add_widget_to_vbox(GtkBox *vbox, const char *widget_label, GtkSizeGroup *sg, GtkWidget *widget, gboolean expand, GtkWidget **p_label); /** * Create a GdkPixbuf from a chunk of image data. * - * @param buf The raw binary image data. - * @param count The length of buf in bytes. + * @buf: The raw binary image data. + * @count: The length of buf in bytes. * - * @return A GdkPixbuf created from the image data, or NULL if + * Returns: A GdkPixbuf created from the image data, or NULL if * there was an error parsing the data. */ GdkPixbuf *pidgin_pixbuf_from_data(const guchar *buf, gsize count); @@ -765,10 +765,10 @@ /** * Create a GdkPixbufAnimation from a chunk of image data. * - * @param buf The raw binary image data. - * @param count The length of buf in bytes. + * @buf: The raw binary image data. + * @count: The length of buf in bytes. * - * @return A GdkPixbufAnimation created from the image data, or NULL if + * Returns: A GdkPixbufAnimation created from the image data, or NULL if * there was an error parsing the data. */ GdkPixbufAnimation *pidgin_pixbuf_anim_from_data(const guchar *buf, gsize count); @@ -776,9 +776,9 @@ /** * Create a GdkPixbuf from a PurpleStoredImage. * - * @param image A PurpleStoredImage. + * @image: A PurpleStoredImage. * - * @return A GdkPixbuf created from the stored image. + * Returns: A GdkPixbuf created from the stored image. */ GdkPixbuf *pidgin_pixbuf_from_imgstore(PurpleStoredImage *image); @@ -798,9 +798,9 @@ * gdk-pixbuf where the aforementioned bug is fixed. However, it might be * nice to keep this function around for the debug message that it logs. * - * @param filename Name of file to load, in the GLib file name encoding + * @filename: Name of file to load, in the GLib file name encoding * - * @return The GdkPixbuf if successful. Otherwise NULL is returned and + * Returns: The GdkPixbuf if successful. Otherwise NULL is returned and * a warning is logged. */ GdkPixbuf *pidgin_pixbuf_new_from_file(const char *filename); @@ -821,11 +821,11 @@ * gdk-pixbuf where the aforementioned bug is fixed. However, it might be * nice to keep this function around for the debug message that it logs. * - * @param filename Name of file to load, in the GLib file name encoding - * @param width The width the image should have or -1 to not constrain the width - * @param height The height the image should have or -1 to not constrain the height + * @filename: Name of file to load, in the GLib file name encoding + * @width: The width the image should have or -1 to not constrain the width + * @height: The height the image should have or -1 to not constrain the height * - * @return The GdkPixbuf if successful. Otherwise NULL is returned and + * Returns: The GdkPixbuf if successful. Otherwise NULL is returned and * a warning is logged. */ GdkPixbuf *pidgin_pixbuf_new_from_file_at_size(const char *filename, int width, int height); @@ -846,24 +846,24 @@ * gdk-pixbuf where the aforementioned bug is fixed. However, it might be * nice to keep this function around for the debug message that it logs. * - * @param filename Name of file to load, in the GLib file name encoding - * @param width The width the image should have or -1 to not constrain the width - * @param height The height the image should have or -1 to not constrain the height - * @param preserve_aspect_ratio TRUE to preserve the image's aspect ratio + * @filename: Name of file to load, in the GLib file name encoding + * @width: The width the image should have or -1 to not constrain the width + * @height: The height the image should have or -1 to not constrain the height + * @preserve_aspect_ratio: TRUE to preserve the image's aspect ratio * - * @return The GdkPixbuf if successful. Otherwise NULL is returned and + * Returns: The GdkPixbuf if successful. Otherwise NULL is returned and * a warning is logged. */ GdkPixbuf *pidgin_pixbuf_new_from_file_at_scale(const char *filename, int width, int height, gboolean preserve_aspect_ratio); /** * Add scrollbars to a widget - * @param child The child widget - * @param hscrollbar_policy Horizontal scrolling policy - * @param vscrollbar_policy Vertical scrolling policy - * @param shadow_type Shadow type - * @param width Desired widget width, or -1 for default - * @param height Desired widget height, or -1 for default + * @child: The child widget + * @hscrollbar_policy: Horizontal scrolling policy + * @vscrollbar_policy: Vertical scrolling policy + * @shadow_type: Shadow type + * @width: Desired widget width, or -1 for default + * @height: Desired widget height, or -1 for default */ GtkWidget *pidgin_make_scrollable(GtkWidget *child, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy, GtkShadowType shadow_type, int width, int height);
--- a/pidgin/gtkwebview.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkwebview.h Wed Jan 29 05:28:33 2014 +0530 @@ -111,16 +111,16 @@ /** * Returns the GType for a GtkWebView widget * - * @return The GType for GtkWebView widget + * Returns: The GType for GtkWebView widget */ GType gtk_webview_get_type(void); /** * Create a new GtkWebView object * - * @param editable Whether this GtkWebView will be user-editable + * @editable: Whether this GtkWebView will be user-editable * - * @return A GtkWidget corresponding to the GtkWebView object + * Returns: A GtkWidget corresponding to the GtkWebView object */ GtkWidget *gtk_webview_new(gboolean editable); @@ -128,16 +128,16 @@ * A very basic routine to append html, which can be considered * equivalent to a "document.write" using JavaScript. * - * @param webview The GtkWebView object - * @param markup The html markup to append + * @webview: The GtkWebView object + * @markup: The html markup to append */ void gtk_webview_append_html(GtkWebView *webview, const char *markup); /** * Requests loading of the given content. * - * @param webview The GtkWebView object - * @param html The HTML content to load + * @webview: The GtkWebView object + * @html: The HTML content to load */ void gtk_webview_load_html_string(GtkWebView *webview, const char *html); @@ -147,8 +147,8 @@ * used to set the selection. This tag is then removed so that querying the * WebView's HTML contents will no longer return it. * - * @param webview The GtkWebView object - * @param html The HTML content to load + * @webview: The GtkWebView object + * @html: The HTML content to load */ void gtk_webview_load_html_string_with_selection(GtkWebView *webview, const char *html); @@ -159,8 +159,8 @@ * conditions when calling JS functions immediately after opening the * page. * - * @param webview The GtkWebView object - * @param script The script to execute + * @webview: The GtkWebView object + * @script: The script to execute */ void gtk_webview_safe_execute_script(GtkWebView *webview, const char *script); @@ -168,25 +168,25 @@ * A convenience routine to quote a string for use as a JavaScript * string. For instance, "hello 'world'" becomes "'hello \\'world\\''" * - * @param str The string to escape and quote + * @str: The string to escape and quote * - * @return The quoted string + * Returns: The quoted string */ char *gtk_webview_quote_js_string(const char *str); /** * Set the vertical adjustment for the GtkWebView. * - * @param webview The GtkWebView object - * @param vadj The GtkAdjustment that control the webview + * @webview: The GtkWebView object + * @vadj: The GtkAdjustment that control the webview */ void gtk_webview_set_vadjustment(GtkWebView *webview, GtkAdjustment *vadj); /** * Scrolls the Webview to the end of its contents. * - * @param webview The GtkWebView object - * @param smooth A boolean indicating if smooth scrolling should be used + * @webview: The GtkWebView object + * @smooth: A boolean indicating if smooth scrolling should be used */ void gtk_webview_scroll_to_end(GtkWebView *webview, gboolean smooth); @@ -194,8 +194,8 @@ * Set whether the GtkWebView stays at its end when HTML content is appended. If * not already at the end before appending, then scrolling will not occur. * - * @param webview The GtkWebView object - * @param scroll Whether to automatically scroll + * @webview: The GtkWebView object + * @scroll: Whether to automatically scroll */ void gtk_webview_set_autoscroll(GtkWebView *webview, gboolean scroll); @@ -203,39 +203,39 @@ * Set whether the GtkWebView stays at its end when HTML content is appended. If * not already at the end before appending, then scrolling will not occur. * - * @param webview The GtkWebView object + * @webview: The GtkWebView object * - * @return Whether to automatically scroll + * Returns: Whether to automatically scroll */ gboolean gtk_webview_get_autoscroll(GtkWebView *webview); /** * Scrolls a GtkWebView up by one page. * - * @param webview The GtkWebView. + * @webview: The GtkWebView. */ void gtk_webview_page_up(GtkWebView *webview); /** * Scrolls a GtkWebView down by one page. * - * @param webview The GtkWebView. + * @webview: The GtkWebView. */ void gtk_webview_page_down(GtkWebView *webview); /** * Setup formatting for a GtkWebView depending on the flags specified. * - * @param webview The GtkWebView. - * @param flags The connection flags describing the allowed formatting. + * @webview: The GtkWebView. + * @flags: The connection flags describing the allowed formatting. */ void gtk_webview_setup_entry(GtkWebView *webview, PurpleConnectionFlags flags); /** * Setup spell-checking on a GtkWebView. * - * @param webview The GtkWebView. - * @param enable Whether to enable or disable spell-checking. + * @webview: The GtkWebView. + * @enable: Whether to enable or disable spell-checking. */ void pidgin_webview_set_spellcheck(GtkWebView *webview, gboolean enable); @@ -244,8 +244,8 @@ * In this mode formatting options to the buffer take effect for the entire * buffer instead of specific text. * - * @param webview The GtkWebView - * @param wbfo @c TRUE to enable the mode, or @c FALSE otherwise. + * @webview: The GtkWebView + * @wbfo: @c TRUE to enable the mode, or @c FALSE otherwise. */ void gtk_webview_set_whole_buffer_formatting_only(GtkWebView *webview, gboolean wbfo); @@ -253,8 +253,8 @@ /** * Indicates which formatting functions to enable and disable in a GtkWebView. * - * @param webview The GtkWebView - * @param buttons A GtkWebViewButtons bitmask indicating which functions to use + * @webview: The GtkWebView + * @buttons: A GtkWebViewButtons bitmask indicating which functions to use */ void gtk_webview_set_format_functions(GtkWebView *webview, GtkWebViewButtons buttons); @@ -263,7 +263,7 @@ * Activates a WebKitDOMHTMLAnchorElement object. This triggers the navigation * signals, and marks the link as visited (when possible). * - * @param link The WebKitDOMHTMLAnchorElement object + * @link: The WebKitDOMHTMLAnchorElement object * */ void gtk_webview_activate_anchor(WebKitDOMHTMLAnchorElement *link); @@ -272,17 +272,17 @@ * Register a protocol with the GtkWebView widget. Registering a protocol would * allow certain text to be clickable. * - * @param name The name of the protocol (e.g. http://) - * @param activate The callback to trigger when the protocol text is clicked. + * @name: The name of the protocol (e.g. http://) + * @activate: The callback to trigger when the protocol text is clicked. * Removes any current protocol definition if @c NULL. The * callback should return @c TRUE if the link was activated * properly, @c FALSE otherwise. - * @param context_menu The callback to trigger when the context menu is popped + * @context_menu: The callback to trigger when the context menu is popped * up on the protocol text. The callback should return * @c TRUE if the request for context menu was processed * successfully, @c FALSE otherwise. * - * @return @c TRUE if the protocol was successfully registered + * Returns: @c TRUE if the protocol was successfully registered * (or unregistered, when \a activate is @c NULL) */ gboolean gtk_webview_class_register_protocol(const char *name, @@ -292,9 +292,9 @@ /** * Returns which formatting functions are enabled in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return A GtkWebViewButtons bitmask indicating which functions to are enabled + * Returns: A GtkWebViewButtons bitmask indicating which functions to are enabled */ GtkWebViewButtons gtk_webview_get_format_functions(GtkWebView *webview); @@ -302,11 +302,11 @@ * Sets each boolean to @c TRUE or @c FALSE to indicate if that formatting * option is enabled at the current position in a GtkWebView. * - * @param webview The GtkWebView - * @param bold The boolean to set for bold or @c NULL. - * @param italic The boolean to set for italic or @c NULL. - * @param underline The boolean to set for underline or @c NULL. - * @param strikethrough The boolean to set for strikethrough or @c NULL. + * @webview: The GtkWebView + * @bold: The boolean to set for bold or @c NULL. + * @italic: The boolean to set for italic or @c NULL. + * @underline: The boolean to set for underline or @c NULL. + * @strikethrough: The boolean to set for strikethrough or @c NULL. */ void gtk_webview_get_current_format(GtkWebView *webview, gboolean *bold, gboolean *italic, gboolean *underline, @@ -316,9 +316,9 @@ * Returns a string containing the selected font face at the current position * in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return A string containing the font face or @c NULL if none is set. + * Returns: A string containing the font face or @c NULL if none is set. */ char *gtk_webview_get_current_fontface(GtkWebView *webview); @@ -326,9 +326,9 @@ * Returns a string containing the selected foreground color at the current * position in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return A string containing the foreground color or @c NULL if none is set. + * Returns: A string containing the foreground color or @c NULL if none is set. */ char *gtk_webview_get_current_forecolor(GtkWebView *webview); @@ -336,9 +336,9 @@ * Returns a string containing the selected font background color at the current * position in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return A string containing the background color or @c NULL if none is set. + * Returns: A string containing the background color or @c NULL if none is set. */ char *gtk_webview_get_current_backcolor(GtkWebView *webview); @@ -346,45 +346,45 @@ * Returns a integer containing the selected HTML font size at the current * position in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return The HTML font size. + * Returns: The HTML font size. */ gint gtk_webview_get_current_fontsize(GtkWebView *webview); /** * Gets the content of the head element of a GtkWebView as HTML. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return The HTML from the head element. + * Returns: The HTML from the head element. */ gchar *gtk_webview_get_head_html(GtkWebView *webview); /** * Gets the HTML content of a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return The HTML that is currently displayed. + * Returns: The HTML that is currently displayed. */ gchar *gtk_webview_get_body_html(GtkWebView *webview); /** * Gets the text content of a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return The HTML-free text that is currently displayed. + * Returns: The HTML-free text that is currently displayed. */ gchar *gtk_webview_get_body_text(GtkWebView *webview); /** * Gets the selected text of a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView * - * @return The HTML-free text that is currently selected, or NULL if nothing is + * Returns: The HTML-free text that is currently selected, or NULL if nothing is * currently selected. */ gchar *gtk_webview_get_selected_text(GtkWebView *webview); @@ -393,11 +393,11 @@ * Gets the container of the caret, along with its position in the container * from a GtkWebView. * - * @param webview The GtkWebView - * @param container_ret A pointer to a pointer to a WebKitDOMNode. This pointer + * @webview: The GtkWebView + * @container_ret: A pointer to a pointer to a WebKitDOMNode. This pointer * will be set to the container the caret is in. Set to * @c NULL if a range is selected. - * @param pos_ret A pointer to a glong. This value will be set to the + * @pos_ret: A pointer to a glong. This value will be set to the * position of the caret in the container. Set to -1 if a * range is selected. */ @@ -407,9 +407,9 @@ /** * Sets the caret position in container, in a GtkWebView. * - * @param webview The GtkWebView - * @param container The WebKitDOMNode to set the caret in - * @param pos The position of the caret in the container + * @webview: The GtkWebView + * @container: The WebKitDOMNode to set the caret in + * @pos: The position of the caret in the container */ void gtk_webview_set_caret(GtkWebView *webview, WebKitDOMNode *container, glong pos); @@ -417,35 +417,35 @@ /** * Clear all the formatting on a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_clear_formatting(GtkWebView *webview); /** * Toggles bold at the cursor location or selection in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_toggle_bold(GtkWebView *webview); /** * Toggles italic at the cursor location or selection in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_toggle_italic(GtkWebView *webview); /** * Toggles underline at the cursor location or selection in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_toggle_underline(GtkWebView *webview); /** * Toggles strikethrough at the cursor location or selection in a GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_toggle_strike(GtkWebView *webview); @@ -453,10 +453,10 @@ * Toggles a foreground color at the current location or selection in a * GtkWebView. * - * @param webview The GtkWebView - * @param color The HTML-style color, or @c NULL or "" to clear the color. + * @webview: The GtkWebView + * @color: The HTML-style color, or @c NULL or "" to clear the color. * - * @return @c TRUE if a color was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a color was set, or @c FALSE if it was cleared. */ gboolean gtk_webview_toggle_forecolor(GtkWebView *webview, const char *color); @@ -464,28 +464,28 @@ * Toggles a background color at the current location or selection in a * GtkWebView. * - * @param webview The GtkWebView - * @param color The HTML-style color, or @c NULL or "" to clear the color. + * @webview: The GtkWebView + * @color: The HTML-style color, or @c NULL or "" to clear the color. * - * @return @c TRUE if a color was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a color was set, or @c FALSE if it was cleared. */ gboolean gtk_webview_toggle_backcolor(GtkWebView *webview, const char *color); /** * Toggles a font face at the current location or selection in a GtkWebView. * - * @param webview The GtkWebView - * @param face The font face name, or @c NULL or "" to clear the font. + * @webview: The GtkWebView + * @face: The font face name, or @c NULL or "" to clear the font. * - * @return @c TRUE if a font name was set, or @c FALSE if it was cleared. + * Returns: @c TRUE if a font name was set, or @c FALSE if it was cleared. */ gboolean gtk_webview_toggle_fontface(GtkWebView *webview, const char *face); /** * Sets the font size at the current location or selection in a GtkWebView. * - * @param webview The GtkWebView - * @param size The HTML font size to use. + * @webview: The GtkWebView + * @size: The HTML font size to use. */ void gtk_webview_font_set_size(GtkWebView *webview, gint size); @@ -493,7 +493,7 @@ * Decreases the font size by 1 at the current location or selection in a * GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_font_shrink(GtkWebView *webview); @@ -501,7 +501,7 @@ * Increases the font size by 1 at the current location or selection in a * GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_font_grow(GtkWebView *webview); @@ -509,16 +509,16 @@ * Inserts a horizontal rule at the current location or selection in a * GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ void gtk_webview_insert_hr(GtkWebView *webview); /** * Inserts a link at the current location or selection in a GtkWebView. * - * @param webview The GtkWebView - * @param url The URL of the link - * @param desc The text description of the link. If not supplied, the URL is + * @webview: The GtkWebView + * @url: The URL of the link + * @desc: The text description of the link. If not supplied, the URL is * used instead. */ void gtk_webview_insert_link(GtkWebView *webview, const char *url, const char *desc); @@ -526,36 +526,36 @@ /** * Inserts an image at the current location or selection in a GtkWebView. * - * @param webview The GtkWebView - * @param id The PurpleStoredImage id + * @webview: The GtkWebView + * @id: The PurpleStoredImage id */ void gtk_webview_insert_image(GtkWebView *webview, int id); /** * Gets the protocol name associated with this GtkWebView. * - * @param webview The GtkWebView + * @webview: The GtkWebView */ const char *gtk_webview_get_protocol_name(GtkWebView *webview); /** * Associates a protocol name with a GtkWebView. * - * @param webview The GtkWebView - * @param protocol_name The protocol name to associate with the GtkWebView + * @webview: The GtkWebView + * @protocol_name: The protocol name to associate with the GtkWebView */ void gtk_webview_set_protocol_name(GtkWebView *webview, const char *protocol_name); /** * Create a new GtkWebViewSmiley. * - * @param file The image file for the smiley - * @param shortcut The key shortcut for the smiley - * @param hide @c TRUE if the smiley should be hidden in the smiley dialog, + * @file: The image file for the smiley + * @shortcut: The key shortcut for the smiley + * @hide: @c TRUE if the smiley should be hidden in the smiley dialog, * @c FALSE otherwise - * @param flags The smiley flags + * @flags: The smiley flags * - * @return The newly created smiley + * Returns: The newly created smiley */ GtkWebViewSmiley *gtk_webview_smiley_create(const char *file, const char *shortcut, @@ -565,59 +565,59 @@ /** * Reload the image data for the smiley. * - * @param smiley The smiley to reload + * @smiley: The smiley to reload */ void gtk_webview_smiley_reload(GtkWebViewSmiley *smiley); /** * Destroy a GtkWebViewSmiley. * - * @param smiley The smiley to destroy + * @smiley: The smiley to destroy */ void gtk_webview_smiley_destroy(GtkWebViewSmiley *smiley); /** * Returns the text associated with a smiley. * - * @param smiley The smiley + * @smiley: The smiley * - * @return The text + * Returns: The text */ const char *gtk_webview_smiley_get_smile(const GtkWebViewSmiley *smiley); /** * Returns the file associated with a smiley. * - * @param smiley The smiley + * @smiley: The smiley * - * @return The file + * Returns: The file */ const char *gtk_webview_smiley_get_file(const GtkWebViewSmiley *smiley); /** * Returns the invisibility of a smiley. * - * @param smiley The smiley + * @smiley: The smiley * - * @return The hidden status + * Returns: The hidden status */ gboolean gtk_webview_smiley_get_hidden(const GtkWebViewSmiley *smiley); /** * Returns the flags associated with a smiley. * - * @param smiley The smiley + * @smiley: The smiley * - * @return The flags + * Returns: The flags */ GtkWebViewSmileyFlags gtk_webview_smiley_get_flags(const GtkWebViewSmiley *smiley); /** * Returns the smiley object associated with the text. * - * @param webview The GtkWebView - * @param sml The name of the smiley category - * @param text The text associated with the smiley + * @webview: The GtkWebView + * @sml: The name of the smiley category + * @text: The text associated with the smiley */ GtkWebViewSmiley *gtk_webview_smiley_find(GtkWebView *webview, const char *sml, const char *text); @@ -625,9 +625,9 @@ /** * Associates a smiley with a GtkWebView. * - * @param webview The GtkWebView - * @param sml The name of the smiley category - * @param smiley The GtkWebViewSmiley to associate + * @webview: The GtkWebView + * @sml: The name of the smiley category + * @smiley: The GtkWebViewSmiley to associate */ void gtk_webview_associate_smiley(GtkWebView *webview, const char *sml, GtkWebViewSmiley *smiley); @@ -635,16 +635,16 @@ /** * Removes all smileys associated with a GtkWebView. * - * @param webview The GtkWebView. + * @webview: The GtkWebView. */ void gtk_webview_remove_smileys(GtkWebView *webview); /** * Inserts a smiley at the current location or selection in a GtkWebView. * - * @param webview The GtkWebView - * @param sml The category of the smiley - * @param smiley The text of the smiley to insert + * @webview: The GtkWebView + * @sml: The category of the smiley + * @smiley: The text of the smiley to insert */ void gtk_webview_insert_smiley(GtkWebView *webview, const char *sml, const char *smiley); @@ -652,22 +652,22 @@ /** * Makes the toolbar associated with a GtkWebView visible. * - * @param webview The GtkWebView. + * @webview: The GtkWebView. */ void gtk_webview_show_toolbar(GtkWebView *webview); /** * Makes the toolbar associated with a GtkWebView invisible. * - * @param webview The GtkWebView. + * @webview: The GtkWebView. */ void gtk_webview_hide_toolbar(GtkWebView *webview); /** * Activate an action on the toolbar associated with a GtkWebView. * - * @param webview The GtkWebView - * @param action The GtkWebViewAction + * @webview: The GtkWebView + * @action: The GtkWebViewAction */ void gtk_webview_activate_toolbar(GtkWebView *webview, GtkWebViewAction action);
--- a/pidgin/gtkwebviewtoolbar.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkwebviewtoolbar.h Wed Jan 29 05:28:33 2014 +0530 @@ -53,30 +53,30 @@ /** * Returns the GType for a GtkWebViewToolbar widget * - * @return The GType for GtkWebViewToolbar widget + * Returns: The GType for GtkWebViewToolbar widget */ GType gtk_webviewtoolbar_get_type(void); /** * Create a new GtkWebViewToolbar object * - * @return A GtkWidget corresponding to the GtkWebViewToolbar object + * Returns: A GtkWidget corresponding to the GtkWebViewToolbar object */ GtkWidget *gtk_webviewtoolbar_new(void); /** * Attach a GtkWebViewToolbar object to a GtkWebView * - * @param toolbar The GtkWebViewToolbar object - * @param webview The GtkWebView object + * @toolbar: The GtkWebViewToolbar object + * @webview: The GtkWebView object */ void gtk_webviewtoolbar_attach(GtkWebViewToolbar *toolbar, GtkWidget *webview); /** * Associate the smileys from a protocol to a GtkWebViewToolbar object * - * @param toolbar The GtkWebViewToolbar object - * @param proto_id The ID of the protocol from which smileys are associated + * @toolbar: The GtkWebViewToolbar object + * @proto_id: The ID of the protocol from which smileys are associated */ void gtk_webviewtoolbar_associate_smileys(GtkWebViewToolbar *toolbar, const char *proto_id); @@ -84,8 +84,8 @@ /** * Switch the active conversation for a GtkWebViewToolbar object * - * @param toolbar The GtkWebViewToolbar object - * @param conv The new conversation + * @toolbar: The GtkWebViewToolbar object + * @conv: The new conversation */ void gtk_webviewtoolbar_switch_active_conversation(GtkWebViewToolbar *toolbar, PurpleConversation *conv); @@ -93,8 +93,8 @@ /** * Activate a GtkWebViewToolbar action * - * @param toolbar The GtkWebViewToolbar object - * @param action The GtkWebViewAction + * @toolbar: The GtkWebViewToolbar object + * @action: The GtkWebViewAction */ void gtk_webviewtoolbar_activate(GtkWebViewToolbar *toolbar, GtkWebViewAction action);
--- a/pidgin/gtkwhiteboard.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkwhiteboard.h Wed Jan 29 05:28:33 2014 +0530 @@ -74,7 +74,7 @@ /** * Gets the GtkWhiteboard UI Operations. * - * @return The GtkWhiteboard UI Operations. + * Returns: The GtkWhiteboard UI Operations. */ PurpleWhiteboardUiOps *pidgin_whiteboard_get_ui_ops( void );
--- a/pidgin/gtkxfer.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/gtkxfer.h Wed Jan 29 05:28:33 2014 +0530 @@ -46,14 +46,14 @@ /** * Creates a new file transfer dialog. * - * @return The new dialog. + * Returns: The new dialog. */ PidginXferDialog *pidgin_xfer_dialog_new(void); /** * Destroys a file transfer dialog. * - * @param dialog The file transfer dialog. + * @dialog: The file transfer dialog. */ void pidgin_xfer_dialog_destroy(PidginXferDialog *dialog); @@ -61,30 +61,30 @@ * Displays the file transfer dialog given. * If dialog is @c NULL, displays the default dialog, creating one if necessary * - * @param dialog The file transfer dialog to show. + * @dialog: The file transfer dialog to show. */ void pidgin_xfer_dialog_show(PidginXferDialog *dialog); /** * Hides the file transfer dialog. * - * @param dialog The file transfer dialog to hide. + * @dialog: The file transfer dialog to hide. */ void pidgin_xfer_dialog_hide(PidginXferDialog *dialog); /** * Adds a file transfer to the dialog. * - * @param dialog The file transfer dialog. - * @param xfer The file transfer. + * @dialog: The file transfer dialog. + * @xfer: The file transfer. */ void pidgin_xfer_dialog_add_xfer(PidginXferDialog *dialog, PurpleXfer *xfer); /** * Removes a file transfer from the dialog. * - * @param dialog The file transfer dialog. - * @param xfer The file transfer. + * @dialog: The file transfer dialog. + * @xfer: The file transfer. */ void pidgin_xfer_dialog_remove_xfer(PidginXferDialog *dialog, PurpleXfer *xfer); @@ -92,8 +92,8 @@ /** * Indicate in a file transfer dialog that a transfer was cancelled. * - * @param dialog The file transfer dialog. - * @param xfer The file transfer that was cancelled. + * @dialog: The file transfer dialog. + * @xfer: The file transfer that was cancelled. */ void pidgin_xfer_dialog_cancel_xfer(PidginXferDialog *dialog, PurpleXfer *xfer); @@ -101,8 +101,8 @@ /** * Updates the information for a transfer in the dialog. * - * @param dialog The file transfer dialog. - * @param xfer The file transfer. + * @dialog: The file transfer dialog. + * @xfer: The file transfer. */ void pidgin_xfer_dialog_update_xfer(PidginXferDialog *dialog, PurpleXfer *xfer); @@ -127,21 +127,21 @@ /** * Sets pidgin's main file transfer dialog. * - * @param dialog The main dialog. + * @dialog: The main dialog. */ void pidgin_set_xfer_dialog(PidginXferDialog *dialog); /** * Returns pirgin's main file transfer dialog. * - * @return The main dialog. + * Returns: The main dialog. */ PidginXferDialog *pidgin_get_xfer_dialog(void); /** * Returns the UI operations structure for the GTK+ file transfer UI. * - * @return The GTK+ file transfer UI operations structure. + * Returns: The GTK+ file transfer UI operations structure. */ PurpleXferUiOps *pidgin_xfers_get_ui_ops(void);
--- a/pidgin/minidialog.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/minidialog.h Wed Jan 29 05:28:33 2014 +0530 @@ -100,9 +100,9 @@ } PidginMiniDialogClass; /** The type of a callback triggered by a button in a mini-dialog being pressed. - * @param mini_dialog a dialog, one of whose buttons has been pressed. - * @param button the button which was pressed. - * @param user_data arbitrary data, supplied to + * @mini_dialog: a dialog, one of whose buttons has been pressed. + * @button: the button which was pressed. + * @user_data: arbitrary data, supplied to * pidgin_mini_dialog_add_button() when the button was * created. */ @@ -114,55 +114,55 @@ /** Creates a new #PidginMiniDialog with a stock icon. This is a shortcut for creating the dialog * with @c g_object_new() then setting each property yourself. - * @return a new #PidginMiniDialog. + * Returns: a new #PidginMiniDialog. */ PidginMiniDialog *pidgin_mini_dialog_new(const gchar *title, const gchar *description, const gchar *icon_name); /** Creates a new #PidginMiniDialog with a custom icon. This is a shortcut for creating the dialog * with @c g_object_new() then setting each property yourself. - * @return a new #PidginMiniDialog. + * Returns: a new #PidginMiniDialog. */ PidginMiniDialog *pidgin_mini_dialog_new_with_custom_icon(const gchar *title, const gchar *description, GdkPixbuf *custom_icon); /** Shortcut for setting a mini-dialog's title via GObject properties. - * @param mini_dialog a mini-dialog - * @param title the new title for @a mini_dialog + * @mini_dialog: a mini-dialog + * @title: the new title for @a mini_dialog */ void pidgin_mini_dialog_set_title(PidginMiniDialog *mini_dialog, const char *title); /** Shortcut for setting a mini-dialog's description via GObject properties. - * @param mini_dialog a mini-dialog - * @param description the new description for @a mini_dialog, or @c NULL to + * @mini_dialog: a mini-dialog + * @description: the new description for @a mini_dialog, or @c NULL to * hide the description widget. */ void pidgin_mini_dialog_set_description(PidginMiniDialog *mini_dialog, const char *description); /** Enable GMarkup elements in the mini-dialog's description. - * @param mini_dialog a mini-dialog + * @mini_dialog: a mini-dialog */ void pidgin_mini_dialog_enable_description_markup(PidginMiniDialog *mini_dialog); /** Sets a callback which gets invoked when a hyperlink in the dialog's description is clicked on. - * @param mini_dialog a mini-dialog - * @param cb the callback to invoke - * @param user_data the user data to pass to the callback + * @mini_dialog: a mini-dialog + * @cb: the callback to invoke + * @user_data: the user data to pass to the callback */ void pidgin_mini_dialog_set_link_callback(PidginMiniDialog *mini_dialog, GCallback cb, gpointer user_data); /** Shortcut for setting a mini-dialog's icon via GObject properties. - * @param mini_dialog a mini-dialog - * @param icon_name the Gtk stock ID of an icon, or @c NULL for no icon. + * @mini_dialog: a mini-dialog + * @icon_name: the Gtk stock ID of an icon, or @c NULL for no icon. */ void pidgin_mini_dialog_set_icon_name(PidginMiniDialog *mini_dialog, const char *icon_name); /** Shortcut for setting a mini-dialog's custom icon via GObject properties. - * @param mini_dialog a mini-dialog - * @param custom_icon the pixbuf to use as a custom icon + * @mini_dialog: a mini-dialog + * @custom_icon: the pixbuf to use as a custom icon */ void pidgin_mini_dialog_set_custom_icon(PidginMiniDialog *mini_dialog, GdkPixbuf *custom_icon); @@ -170,10 +170,10 @@ /** Adds a new button to a mini-dialog, and attaches the supplied callback to * its <tt>clicked</tt> signal. After a button is clicked, the dialog is * destroyed. - * @param mini_dialog a mini-dialog - * @param text the text to display on the new button - * @param clicked_cb the function to call when the button is clicked - * @param user_data arbitrary data to pass to @a clicked_cb when it is + * @mini_dialog: a mini-dialog + * @text: the text to display on the new button + * @clicked_cb: the function to call when the button is clicked + * @user_data: arbitrary data to pass to @a clicked_cb when it is * called. */ void pidgin_mini_dialog_add_button(PidginMiniDialog *mini_dialog, @@ -188,8 +188,8 @@ gpointer user_data); /** Gets the number of widgets packed into PidginMiniDialog.contents. - * @param mini_dialog a mini-dialog - * @return the number of widgets in @a mini_dialog->contents. + * @mini_dialog: a mini-dialog + * Returns: the number of widgets in @a mini_dialog->contents. */ guint pidgin_mini_dialog_get_num_children(PidginMiniDialog *mini_dialog);
--- a/pidgin/pidginstock.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/pidginstock.h Wed Jan 29 05:28:33 2014 +0530 @@ -224,7 +224,7 @@ /** * Loades all of the icons from the status icon theme into Pidgin stock * - * @param theme the theme to load, or null to load all the default icons + * @theme: the theme to load, or null to load all the default icons */ void pidgin_stock_load_status_icon_theme(PidginStatusIconTheme *theme);
--- a/pidgin/pidgintooltip.h Wed Jan 29 00:28:08 2014 +0530 +++ b/pidgin/pidgintooltip.h Wed Jan 29 05:28:33 2014 +0530 @@ -29,34 +29,34 @@ #include <gtk/gtk.h> /** - * @param tipwindow The window for the tooltip. - * @param path The GtkTreePath representing the row under the cursor. - * @param userdata The userdata set during pidgin_tooltip_setup_for_treeview. + * @tipwindow: The window for the tooltip. + * @path: The GtkTreePath representing the row under the cursor. + * @userdata: The userdata set during pidgin_tooltip_setup_for_treeview. * @param w The value of this should be set to the desired width of the tooltip window. * @param h The value of this should be set to the desired height of the tooltip window. * - * @return @c TRUE if the tooltip was created correctly, @c FALSE otherwise. + * Returns: @c TRUE if the tooltip was created correctly, @c FALSE otherwise. */ typedef gboolean (*PidginTooltipCreateForTree)(GtkWidget *tipwindow, GtkTreePath *path, gpointer userdata, int *w, int *h); /** - * @param tipwindow The window for the tooltip. - * @param userdata The userdata set during pidgin_tooltip_show. + * @tipwindow: The window for the tooltip. + * @userdata: The userdata set during pidgin_tooltip_show. * @param w The value of this should be set to the desired width of the tooltip window. * @param h The value of this should be set to the desired height of the tooltip window. * - * @return @c TRUE if the tooltip was created correctly, @c FALSE otherwise. + * Returns: @c TRUE if the tooltip was created correctly, @c FALSE otherwise. */ typedef gboolean (*PidginTooltipCreate)(GtkWidget *tipwindow, gpointer userdata, int *w, int *h); /** - * @param tipwindow The window for the tooltip. - * @param cr The cairo context for drawing. - * @param userdata The userdata set during pidgin_tooltip_setup_for_treeview or pidgin_tooltip_show. + * @tipwindow: The window for the tooltip. + * @cr: The cairo context for drawing. + * @userdata: The userdata set during pidgin_tooltip_setup_for_treeview or pidgin_tooltip_show. * - * @return @c TRUE if the tooltip was painted correctly, @c FALSE otherwise. + * Returns: @c TRUE if the tooltip was painted correctly, @c FALSE otherwise. */ typedef gboolean (*PidginTooltipPaint)(GtkWidget *tipwindow, cairo_t *cr, gpointer userdata); @@ -66,12 +66,12 @@ /** * Setup tooltip drawing functions for a treeview. * - * @param tree The treeview - * @param userdata The userdata to send to the callback functions - * @param create_cb Callback function to create the tooltip for a GtkTreePath - * @param paint_cb Callback function to paint the tooltip + * @tree: The treeview + * @userdata: The userdata to send to the callback functions + * @create_cb: Callback function to create the tooltip for a GtkTreePath + * @paint_cb: Callback function to paint the tooltip * - * @return @c TRUE if the tooltip callbacks were setup correctly. + * Returns: @c TRUE if the tooltip callbacks were setup correctly. */ gboolean pidgin_tooltip_setup_for_treeview(GtkWidget *tree, gpointer userdata, PidginTooltipCreateForTree create_cb, PidginTooltipPaint paint_cb); @@ -79,12 +79,12 @@ /** * Setup tooltip drawing functions for any widget. * - * @param widget The widget - * @param userdata The userdata to send to the callback functions - * @param create_cb Callback function to create the tooltip for the widget - * @param paint_cb Callback function to paint the tooltip + * @widget: The widget + * @userdata: The userdata to send to the callback functions + * @create_cb: Callback function to create the tooltip for the widget + * @paint_cb: Callback function to paint the tooltip * - * @return @c TRUE if the tooltip callbacks were setup correctly. + * Returns: @c TRUE if the tooltip callbacks were setup correctly. */ gboolean pidgin_tooltip_setup_for_widget(GtkWidget *widget, gpointer userdata, PidginTooltipCreate create_cb, PidginTooltipPaint paint_cb); @@ -97,10 +97,10 @@ /** * Create and show a tooltip. * - * @param widget The widget the tooltip is for - * @param userdata The userdata to send to the callback functions - * @param create_cb Callback function to create the tooltip from the GtkTreePath - * @param paint_cb Callback function to paint the tooltip + * @widget: The widget the tooltip is for + * @userdata: The userdata to send to the callback functions + * @create_cb: Callback function to create the tooltip from the GtkTreePath + * @paint_cb: Callback function to paint the tooltip */ void pidgin_tooltip_show(GtkWidget *widget, gpointer userdata, PidginTooltipCreate create_cb, PidginTooltipPaint paint_cb);
