Mercurial > pidgin3 / file diff

diff: libpurple/accountopt.h

libpurple/accountopt.h

branch
gtkdoc-conversion
changeset 35396
7bfe75a37af7
parent 35394
38facb8226d4
child 35419
d0aecd9a8104
child 37039
7d964cdccbb5
--- a/libpurple/accountopt.h	Fri Jan 31 18:45:48 2014 +0530
+++ b/libpurple/accountopt.h	Fri Jan 31 19:38:07 2014 +0530
@@ -32,9 +32,24 @@
 /** Data Structures                                                       */
 /**************************************************************************/
 
-/** @copydoc _PurpleAccountOption */
+/**
+ * PurpleAccountOption:
+ *
+ * An option for an account.
+ *
+ * This is set by protocols, and appears in the account settings
+ * dialogs.
+ */
 typedef struct _PurpleAccountOption		PurpleAccountOption;
-/** @copydoc _PurpleAccountUserSplit */
+
+/**
+ * PurpleAccountUserSplit:
+ *
+ * A username split.
+ *
+ * This is used by some protocols to separate the fields of the username
+ * into more human-readable components.
+ */
 typedef struct _PurpleAccountUserSplit	PurpleAccountUserSplit;
 
 G_BEGIN_DECLS
@@ -45,57 +60,66 @@
 /*@{*/
 
 /**
+ * purple_account_option_new:
+ * @type:      The type of option.
+ * @text:      The text of the option.
+ * @pref_name: The account preference name for the option.
+ *
  * Creates a new account option.  If you know what @a type will be in advance,
  * consider using purple_account_option_bool_new(),
  * purple_account_option_int_new(), purple_account_option_string_new() or
  * purple_account_option_list_new() (as appropriate) instead.
  *
- * @type:      The type of option.
- * @text:      The text of the option.
- * @pref_name: The account preference name for the option.
- *
  * Returns: The account option.
  */
 PurpleAccountOption *purple_account_option_new(PurplePrefType type,
 	const char *text, const char *pref_name);
 
 /**
- * Creates a new boolean account option.
- *
+ * purple_account_option_bool_new:
  * @text:          The text of the option.
  * @pref_name:     The account preference name for the option.
  * @default_value: The default value.
  *
+ * Creates a new boolean account option.
+ *
  * Returns: The account option.
  */
 PurpleAccountOption *purple_account_option_bool_new(const char *text,
 	const char *pref_name, gboolean default_value);
 
 /**
- * Creates a new integer account option.
- *
+ * purple_account_option_int_new:
  * @text:          The text of the option.
  * @pref_name:     The account preference name for the option.
  * @default_value: The default value.
  *
+ * Creates a new integer account option.
+ *
  * Returns: The account option.
  */
 PurpleAccountOption *purple_account_option_int_new(const char *text,
 	const char *pref_name, int default_value);
 
 /**
- * Creates a new string account option.
- *
+ * purple_account_option_string_new:
  * @text:          The text of the option.
  * @pref_name:     The account preference name for the option.
  * @default_value: The default value.
  *
+ * Creates a new string account option.
+ *
  * Returns: The account option.
  */
 PurpleAccountOption *purple_account_option_string_new(const char *text,
 	const char *pref_name, const char *default_value);
 
 /**
+ * purple_account_option_list_new:
+ * @text:      The text of the option.
+ * @pref_name: The account preference name for the option.
+ * @list:      The key, value list.
+ *
  * Creates a new list account option.
  *
  * The list passed will be owned by the account option, and the
@@ -106,73 +130,79 @@
  * the internal ID that should be passed to purple_account_set_string() to
  * choose that value.
  *
- * @text:      The text of the option.
- * @pref_name: The account preference name for the option.
- * @list:      The key, value list.
- *
  * Returns: The account option.
  */
 PurpleAccountOption *purple_account_option_list_new(const char *text,
 	const char *pref_name, GList *list);
 
 /**
- * Destroys an account option.
+ * purple_account_option_destroy:
+ * @option: The option to destroy.
  *
- * @option: The option to destroy.
+ * Destroys an account option.
  */
 void purple_account_option_destroy(PurpleAccountOption *option);
 
 /**
- * Sets the default boolean value for an account option.
- *
+ * purple_account_option_set_default_bool:
  * @option: The account option.
  * @value:  The default boolean value.
+ *
+ * Sets the default boolean value for an account option.
  */
 void purple_account_option_set_default_bool(PurpleAccountOption *option,
 										  gboolean value);
 
 /**
- * Sets the default integer value for an account option.
- *
+ * purple_account_option_set_default_int:
  * @option: The account option.
  * @value:  The default integer value.
+ *
+ * Sets the default integer value for an account option.
  */
 void purple_account_option_set_default_int(PurpleAccountOption *option,
 										 int value);
 
 /**
- * Sets the default string value for an account option.
- *
+ * purple_account_option_set_default_string:
  * @option: The account option.
  * @value:  The default string value.
+ *
+ * Sets the default string value for an account option.
  */
 void purple_account_option_set_default_string(PurpleAccountOption *option,
 											const char *value);
 
 /**
+ * purple_account_option_string_set_masked:
+ * @option: The account option.
+ * @masked: The masking.
+ *
  * Sets the masking for an account option. Setting this to %TRUE acts
  * as a hint to the UI that the option's value should be obscured from
  * view, like a password.
- *
- * @option: The account option.
- * @masked: The masking.
  */
 void
 purple_account_option_string_set_masked(PurpleAccountOption *option, gboolean masked);
 
 /**
+ * purple_account_option_string_set_hints:
+ * @option: The account option.
+ * @hints: The list of hints, stored as strings.
+ *
  * Sets the hint list for an account option.
  *
  * The list passed will be owned by the account option, and the
  * strings inside will be freed automatically.
- *
- * @option: The account option.
- * @hints: The list of hints, stored as strings.
  */
 void purple_account_option_string_set_hints(PurpleAccountOption *option,
 	GSList *hints);
 
 /**
+ * purple_account_option_set_list:
+ * @option: The account option.
+ * @values: The default list value.
+ *
  * Sets the list values for an account option.
  *
  * The list passed will be owned by the account option, and the
@@ -180,73 +210,77 @@
  *
  * The list is in key, value pairs. The key is the ID stored and used
  * internally, and the value is the label displayed.
- *
- * @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.
- *
+ * purple_account_option_add_list_item:
  * @option: The account option.
  * @key:    The key.
  * @value:  The value.
+ *
+ * Adds an item to a list account option.
  */
 void purple_account_option_add_list_item(PurpleAccountOption *option,
 									   const char *key, const char *value);
 
 /**
- * Returns the specified account option's type.
+ * purple_account_option_get_type:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the specified 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.
+ * purple_account_option_get_text:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the text for an account option.
  *
  * Returns: The account option's text.
  */
 const char *purple_account_option_get_text(const PurpleAccountOption *option);
 
 /**
+ * purple_account_option_get_setting:
+ * @option: The account option.
+ *
  * Returns the name of an account option.  This corresponds to the @c pref_name
  * parameter supplied to purple_account_option_new() or one of the
  * type-specific constructors.
  *
- * @option: The account option.
- *
  * Returns: The option's name.
  */
 const char *purple_account_option_get_setting(const PurpleAccountOption *option);
 
 /**
- * Returns the default boolean value for an account option.
+ * purple_account_option_get_default_bool:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the default boolean value for an account option.
  *
  * Returns: The default boolean value.
  */
 gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
 
 /**
- * Returns the default integer value for an account option.
+ * purple_account_option_get_default_int:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the default integer value for an account option.
  *
  * Returns: The default integer value.
  */
 int purple_account_option_get_default_int(const PurpleAccountOption *option);
 
 /**
- * Returns the default string value for an account option.
+ * purple_account_option_get_default_string:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the default string value for an account option.
  *
  * Returns: The default string value.
  */
@@ -254,9 +288,10 @@
 	const PurpleAccountOption *option);
 
 /**
- * Returns the default string value for a list account option.
+ * purple_account_option_get_default_list_value:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the default string value for a list account option.
  *
  * Returns: The default list string value.
  */
@@ -264,30 +299,33 @@
 	const PurpleAccountOption *option);
 
 /**
+ * purple_account_option_string_get_masked:
+ * @option: The account option.
+ *
  * Returns whether an option's value should be masked from view, like a
  * password.  If so, the UI might display each character of the option
  * as a '*' (for example).
  *
- * @option: The account option.
- *
  * Returns: %TRUE if the option's value should be obscured.
  */
 gboolean
 purple_account_option_string_get_masked(const PurpleAccountOption *option);
 
 /**
- * Returns the list of hints for an account option.
+ * purple_account_option_string_get_hints:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the list of hints for an account option.
  *
  * Returns: (transfer none): 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.
+ * purple_account_option_get_list:
+ * @option: The account option.
  *
- * @option: The account option.
+ * Returns the list values for an account option.
  *
  * Returns: (transfer none): A list of #PurpleKeyValuePair, mapping the human-readable
  *              description of the value to the <tt>(const char *)</tt> that
@@ -305,12 +343,13 @@
 /*@{*/
 
 /**
- * Creates a new account username split.
- *
+ * purple_account_user_split_new:
  * @text:          The text of the option.
  * @default_value: The default value.
  * @sep:           The field separator.
  *
+ * Creates a new account username split.
+ *
  * Returns: The new user split.
  */
 PurpleAccountUserSplit *purple_account_user_split_new(const char *text,
@@ -318,25 +357,28 @@
 												  char sep);
 
 /**
- * Destroys an account username split.
+ * purple_account_user_split_destroy:
+ * @split: The split to destroy.
  *
- * @split: The split to destroy.
+ * Destroys an account username split.
  */
 void purple_account_user_split_destroy(PurpleAccountUserSplit *split);
 
 /**
- * Returns the text for an account username split.
+ * purple_account_user_split_get_text:
+ * @split: The account username split.
  *
- * @split: The account username split.
+ * Returns the text for an account username split.
  *
  * 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.
+ * purple_account_user_split_get_default_value:
+ * @split: The account username split.
  *
- * @split: The account username split.
+ * Returns the default string value for an account split.
  *
  * Returns: The default string.
  */
@@ -344,28 +386,31 @@
 		const PurpleAccountUserSplit *split);
 
 /**
- * Returns the field separator for an account split.
+ * purple_account_user_split_get_separator:
+ * @split: The account username split.
  *
- * @split: The account username split.
+ * Returns the field separator for an account split.
  *
  * Returns: The field separator.
  */
 char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split);
 
 /**
- * Returns the 'reverse' value for an account split.
+ * purple_account_user_split_get_reverse:
+ * @split: The account username split.
  *
- * @split: The account username split.
+ * Returns the 'reverse' value for an account split.
  *
  * Returns: The 'reverse' value.
  */
 gboolean purple_account_user_split_get_reverse(const PurpleAccountUserSplit *split);
 
 /**
- * Sets the 'reverse' value for an account split.
- *
+ * purple_account_user_split_set_reverse:
  * @split:   The account username split.
  * @reverse: The 'reverse' value
+ *
+ * Sets the 'reverse' value for an account split.
  */
 void purple_account_user_split_set_reverse(PurpleAccountUserSplit *split, gboolean reverse);

Mercurial Repository: pidgin3

mercurial