pidgin/pidgin

Add more documentation for PurpleAccountPrefsUiOps and PurplePrefsUiOps
release-2.x.y
2016-06-17, dx
421e7b2020eb
Parents 77c21aabb081
Children 9aa6de025d0c
Add more documentation for PurpleAccountPrefsUiOps and PurplePrefsUiOps

And all those `@since`
2 files changed, 53 insertions(+), 1 deletions(-)
  • +20 -0
    libpurple/account.h
  • +33 -1
    libpurple/prefs.h
    • --- a/libpurple/account.h Thu Jun 16 14:04:10 2016 -0300
    +++ b/libpurple/account.h Fri Jun 17 01:37:49 2016 -0300
    @@ -129,15 +129,33 @@
    * 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 @@
    * 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 @@
    * 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);
    --- a/libpurple/prefs.h Thu Jun 16 14:04:10 2016 -0300
    +++ b/libpurple/prefs.h Fri Jun 17 01:37:49 2016 -0300
    @@ -64,6 +64,8 @@
    /**
    * Opaque type to carry callback information
    + *
    + * @since 2.11.0
    */
    typedef struct _PurplePrefCallbackData PurplePrefCallbackData;
    @@ -72,7 +74,15 @@
    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 @@
    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 @@
    * 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 @@
    * 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 @@
    /**
    * 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);