/pidgin/main: 421e7b2020eb: Add more documentation for PurpleAcc...

[dx]

Changeset: 421e7b2020eb45e194ba63023e5b7bb9408499f3
Author:	 dx <dx at dxzone.com.ar>
Date:	 2016-06-17 01:37 -0300
Branch:	 release-2.x.y
URL: https://hg.pidgin.im/pidgin/main/rev/421e7b2020eb

Description:

Add more documentation for PurpleAccountPrefsUiOps and PurplePrefsUiOps

And all those `@since`

diffstat:

 libpurple/account.h |  20 ++++++++++++++++++++
 libpurple/prefs.h   |  34 +++++++++++++++++++++++++++++++++-
 2 files changed, 53 insertions(+), 1 deletions(-)

diffs (133 lines):

diff --git a/libpurple/account.h b/libpurple/account.h
--- a/libpurple/account.h
+++ b/libpurple/account.h
@@ -129,15 +129,33 @@ struct _PurpleAccountUiOps
  *   it must set them to the account on load and handle changes with set_
  *   methods. Implementing load/save/schedule_save disables the built-in
  *   accounts.xml code.
+ *
+ *   @since 2.11.0
  */
 struct _PurpleAccountPrefsUiOps
 {
+	/** Notifies the UI that an integer account setting was set. */
 	void (*set_int)(PurpleAccount *account, const char *name, int value);
+
+	/** Notifies the UI that a string account setting was set. */
 	void (*set_string)(PurpleAccount *account, const char *name, const char *value);
+
+	/** Notifies the UI that a boolean account setting was set. */
 	void (*set_bool)(PurpleAccount *account, const char *name, gboolean value);
 
+	/** If this is set, accounts.xml loading will be disabled and this
+	 *  function will be called instead.
+	 */
 	void (*load)(void);
+
+	/** If this is set, accounts.xml saving will be disabled and this
+	 *  function will be called instead.
+	 */
 	void (*save)(void);
+
+	/** If this is set, the UI will handle scheduling the timer to call the
+	 *  save function, overriding the default timeout of 5 seconds.
+	 */
 	void (*schedule_save)(void);
 
 	void (*_purple_reserved1)(void);
@@ -1189,6 +1207,7 @@ PurpleAccountUiOps *purple_accounts_get_
  * Sets the UI operations structure to be used for account preferences.
  *
  * @param ops The UI operations structure.
+ * @since 2.11.0
  */
 void purple_account_prefs_set_ui_ops(PurpleAccountPrefsUiOps *ops);
 
@@ -1196,6 +1215,7 @@ void purple_account_prefs_set_ui_ops(Pur
  * Returns the UI operations structure used for account preferences.
  *
  * @return The UI operations structure in use.
+ * @since 2.11.0
  */
 PurpleAccountPrefsUiOps *purple_account_prefs_get_ui_ops(void);
 
diff --git a/libpurple/prefs.h b/libpurple/prefs.h
--- a/libpurple/prefs.h
+++ b/libpurple/prefs.h
@@ -64,6 +64,8 @@ typedef void (*PurplePrefCallback) (cons
 
 /**
  * Opaque type to carry callback information
+ *
+ * @since 2.11.0
  */
 typedef struct _PurplePrefCallbackData PurplePrefCallbackData;
 
@@ -72,7 +74,15 @@ typedef struct _PurplePrefCallbackData P
 typedef struct _PurplePrefsUiOps PurplePrefsUiOps;
 
 
-/**  Prefs UI operations
+/**
+ * Prefs UI operations. This allows overriding the prefs.xml storage with
+ * anything else. 
+ *
+ * Unless specified otherwise, each entry provides an implementation for the
+ * corresponding purple_prefs_* method, and disables the prefs.xml code for it.
+ * This means that to do anything useful, all the methods must be implemented.
+ *
+ * @since 2.11.0
  */
 struct _PurplePrefsUiOps
 {
@@ -105,7 +115,25 @@ struct _PurplePrefsUiOps
 	void (*save)(void);
 	void (*schedule_save)(void);
 
+	/**
+	 * Called when a callback is added to a preference. The UI must keep
+	 * track of it and call #purple_prefs_trigger_callback_object with the
+	 * data attribute.
+	 *
+	 * @param name The preference name.
+	 * @param data The object to be passed when triggering the callback
+	 * @return A pointer to a ui_data object.
+	 * */
 	void *(*connect_callback)(const char *name, PurplePrefCallbackData *data);
+
+	/**
+	 * Called when a callback is removed from a preference. The ui_data
+	 * object is the one returned from connect_callback.
+	 *
+	 * @param name The preference name
+	 * @param ui_data The object that was returned from the
+	 * connect_callback UI OP.
+	 * */
 	void (*disconnect_callback)(const char *name, void *ui_data);
 
 	void (*_purple_reserved1)(void);
@@ -129,6 +157,7 @@ extern "C" {
  * Sets the UI operations structure to be used for preferences.
  *
  * @param ops The UI operations structure.
+ * @since 2.11.0
  */
 void purple_prefs_set_ui_ops(PurplePrefsUiOps *ops);
 
@@ -136,6 +165,7 @@ void purple_prefs_set_ui_ops(PurplePrefs
  * Returns the UI operations structure used for preferences.
  *
  * @return The UI operations structure in use.
+ * @since 2.11.0
  */
 PurplePrefsUiOps *purple_prefs_get_ui_ops(void);
 
@@ -430,6 +460,8 @@ void purple_prefs_trigger_callback(const
 /**
  * Trigger callbacks as if the pref changed, taking a #PurplePrefCallbackData
  * instead of a name
+ *
+ * @since 2.11.0
  */
 void purple_prefs_trigger_callback_object(PurplePrefCallbackData *data);