--- 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);
