Mercurial > pidgin
changeset 26679:872d30754311
propagate from branch 'im.pidgin.pidgin' (head 1ae2b55502a0afd8f28918fc4726683c52e998e9)
to branch 'im.pidgin.cpw.darkrain42.docs' (head 3dd6aa6f6c394f0be53f01c2decd3f15ff229ff5)
| author | Paul Aurich <paul@darkrain42.org> |
|---|---|
| date | Mon, 20 Apr 2009 00:10:51 +0000 |
| parents | 657ccc44e763 (current diff) 78ef23551355 (diff) |
| children | f7bc9d6e844d |
| files | ChangeLog.API libpurple/blist.h libpurple/xmlnode.h pidgin/gtkblist-theme.h |
| diffstat | 11 files changed, 139 insertions(+), 75 deletions(-) [+] |
line wrap: on
line diff
--- a/libpurple/blist.h Sun Apr 19 15:35:28 2009 +0000 +++ b/libpurple/blist.h Mon Apr 20 00:10:51 2009 +0000 @@ -118,8 +118,8 @@ /** * A Buddy list node. This can represent a group, a buddy, or anything else. - * This is a base class for struct buddy and struct group and for anything - * else that wants to put itself in the buddy list. */ + * This is a base class for PurpleBuddy, PurpleContact, PurpleGroup, and for + * anything else that wants to put itself in the buddy list. */ struct _PurpleBlistNode { PurpleBlistNodeType type; /**< The type of node this is */ PurpleBlistNode *prev; /**< The sibling before this buddy. */ @@ -207,7 +207,7 @@ PurpleBlistNode *node); /**< This will update a node in the buddy list. */ void (*remove)(PurpleBuddyList *list, PurpleBlistNode *node); /**< This removes a node from the list */ - void (*destroy)(PurpleBuddyList *list); /**< When the list gets destroyed, this gets called to destroy the UI. */ + void (*destroy)(PurpleBuddyList *list); /**< When the list is destroyed, this is called to destroy the UI. */ void (*set_visible)(PurpleBuddyList *list, gboolean show); /**< Hides or unhides the buddy list */ void (*request_add_buddy)(PurpleAccount *account, const char *username, @@ -276,7 +276,7 @@ * * @since 2.6.0 */ -void *purple_blist_get_ui_data(void); +gpointer purple_blist_get_ui_data(void); /** * Sets the UI data for the list. @@ -285,7 +285,7 @@ * * @since 2.6.0 */ -void purple_blist_set_ui_data(void *ui_data); +void purple_blist_set_ui_data(gpointer ui_data); /** * Returns the next node of a given node. This function is to be used to iterate @@ -360,7 +360,7 @@ * @return The UI data. * @since 2.6.0 */ -void *purple_blist_node_get_ui_data(const PurpleBlistNode *node); +gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node); /** * Sets the UI data of a given node. @@ -370,7 +370,7 @@ * * @since 2.6.0 */ -void purple_blist_node_set_ui_data(PurpleBlistNode *node, void *ui_data); +void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data); /** * Shows the buddy list, creating a new one if necessary. @@ -393,6 +393,8 @@ /** * Updates a buddy's status. * + * 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. */ @@ -499,12 +501,19 @@ void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node); /** - * Creates a new buddy + * Creates a new buddy. + * + * This function only creates the PurpleBuddy. Use purple_blist_add_buddy + * 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 + * + * @see purple_account_add_buddy + * @see purple_blist_add_buddy */ PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias); @@ -618,7 +627,7 @@ * Creates a new group * * 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. + * 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 @@ -727,18 +736,22 @@ /** * 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, nor does - * it clean up the prpl_data. + * This doesn't actually try to remove the buddy from the server list. * * @param buddy The buddy to be removed + * + * @see purple_account_remove_buddy */ void purple_blist_remove_buddy(PurpleBuddy *buddy); /** * Removes a contact, and any buddies it contains, and frees the memory - * allocated to it. + * 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 + * + * @see purple_blist_remove_buddy */ void purple_blist_remove_contact(PurpleContact *contact); @@ -850,7 +863,7 @@ * 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 in the account) + * @param name The buddy's name (or NULL to return all buddies for the account) * * @return A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist */ @@ -945,7 +958,7 @@ const char *purple_group_get_name(PurpleGroup *group); /** - * Called when an account gets signed on. Tells the UI to update all the + * Called when an account connects. Tells the UI to update all the * buddies. * * @param account The account @@ -954,7 +967,7 @@ /** - * Called when an account gets signed off. Sets the presence of all the buddies to 0 + * 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
--- a/libpurple/smiley.h Sun Apr 19 15:35:28 2009 +0000 +++ b/libpurple/smiley.h Mon Apr 20 00:10:51 2009 +0000 @@ -61,44 +61,41 @@ /*@{*/ /** - * GObject foo. + * GObject-fu. * @internal. */ GType purple_smiley_get_type(void); /** - * Creates a new custom smiley structure and populates it. + * Creates a new custom smiley from a PurpleStoredImage. * - * If a custom smiley with the informed shortcut already exist, it + * 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 custom smiley associated shortcut. + * @param shortcut The associated shortcut (e.g. "(homer)"). * - * @return The custom smiley structure filled up. + * @return The custom smiley. */ PurpleSmiley * purple_smiley_new(PurpleStoredImage *img, const char *shortcut); /** - * Creates a new custom smiley structure and populates it. + * Creates a new custom smiley, reading the image data from a file. * - * The data is retrieved from an already existent file. - * - * If a custom smiley with the informed shortcut already exist, it + * If a custom smiley with the given shortcut already exists, it * will be automaticaly returned. * - * @param shortcut The custom smiley associated shortcut. - * @param filepath The image file to be imported to a - * new custom smiley. + * @param shortcut The associated shortcut (e.g. "(homer)"). + * @param filepath The image file. * - * @return The custom smiley structure filled up. + * @return The custom smiley. */ PurpleSmiley * purple_smiley_new_from_file(const char *shortcut, const char *filepath); /** - * Destroy the custom smiley and release the associated resources. + * Destroys the custom smiley and release the associated resources. * * @param smiley The custom smiley. */ @@ -109,32 +106,28 @@ * Changes the custom smiley's shortcut. * * @param smiley The custom smiley. - * @param shortcut The custom smiley associated shortcut. + * @param shortcut The new shortcut. A custom smiley with this shortcut + * cannot already be in use. * - * @return TRUE whether the shortcut is not associated with another - * custom smiley and the parameters are valid. FALSE otherwise. + * @return TRUE if the shortcut was changed. FALSE otherwise. */ gboolean purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut); /** - * Changes the custom smiley's data. - * - * When the filename controling is made outside this API, the param - * #keepfilename must be TRUE. - * Otherwise, the file and filename will be regenerated, and the - * old one will be removed. + * Changes the custom smiley's image data. * * @param smiley The custom smiley. - * @param smiley_data The custom smiley data. - * @param smiley_data_len The custom smiley data length. + * @param 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. */ void purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data, size_t smiley_data_len); /** - * Returns the custom smiley's associated shortcut. + * Returns the custom smiley's associated shortcut (e.g. "(homer)"). * * @param smiley The custom smiley. * @@ -155,11 +148,11 @@ * Returns the PurpleStoredImage with the reference counter incremented. * * The returned PurpleStoredImage reference counter must be decremented - * after use. + * when the caller is done using it. * * @param smiley The custom smiley. * - * @return A PurpleStoredImage reference. + * @return A PurpleStoredImage. */ PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley); @@ -167,7 +160,7 @@ * Returns the custom smiley's data. * * @param smiley The custom smiley. - * @param len If not @c NULL, the length of the icon data returned + * @param 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. @@ -194,6 +187,8 @@ * directly. If you find yourself wanting to use this function, think * very long and hard about it, and then don't. * + * Think some more. + * * @param smiley The custom smiley. * * @return A full path to the file, or @c NULL under various conditions. @@ -210,7 +205,8 @@ /*@{*/ /** - * Returns a list of all custom smileys. The caller should free the list. + * Returns a list of all custom smileys. The caller is responsible for freeing + * the list. * * @return A list of all custom smileys. */ @@ -218,23 +214,21 @@ purple_smileys_get_all(void); /** - * Returns the custom smiley given it's shortcut. + * Returns a custom smiley given its shortcut. * * @param shortcut The custom smiley's shortcut. * - * @return The custom smiley (with a reference for the caller) if found, - * or @c NULL if not found. + * @return The custom smiley if found, or @c NULL if not found. */ PurpleSmiley * purple_smileys_find_by_shortcut(const char *shortcut); /** - * Returns the custom smiley given it's checksum. + * Returns a custom smiley given its checksum. * * @param checksum The custom smiley's checksum. * - * @return The custom smiley (with a reference for the caller) if found, - * or @c NULL if not found. + * @return The custom smiley if found, or @c NULL if not found. */ PurpleSmiley * purple_smileys_find_by_checksum(const char *checksum); @@ -242,10 +236,10 @@ /** * Returns the directory used to store custom smiley cached files. * - * The default directory is PURPLEDIR/smileys, unless otherwise specified + * The default directory is PURPLEDIR/custom_smiley, unless otherwise specified * by purple_buddy_icons_set_cache_dir(). * - * @return The directory to store custom smyles cached files to. + * @return The directory in which to store custom smileys cached files. */ const char *purple_smileys_get_storing_dir(void);
--- a/libpurple/sound-theme.h Sun Apr 19 15:35:28 2009 +0000 +++ b/libpurple/sound-theme.h Mon Apr 20 00:10:51 2009 +0000 @@ -73,6 +73,7 @@ /** * Returns a copy of the filename for the sound event. * + * @param theme The theme. * @param event The purple sound event to look up. * * @returns The filename of the sound event. @@ -83,6 +84,7 @@ /** * 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 * * @returns The directory + '/' + filename of the sound event. This is @@ -94,8 +96,9 @@ /** * Sets the filename for a given sound event * - * @param event the purple sound event to look up - * @param filename the name of the file to be used for the 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 */ void purple_sound_theme_set_file(PurpleSoundTheme *theme, const gchar *event,
--- a/libpurple/theme-loader.h Sun Apr 19 15:35:28 2009 +0000 +++ b/libpurple/theme-loader.h Mon Apr 20 00:10:51 2009 +0000 @@ -82,7 +82,8 @@ /** * Creates a new PurpleTheme * - * @param dir The directory containing the theme + * @param loader The theme loader + * @param dir The directory containing the theme * * @returns A PurpleTheme containing the information from the directory */
--- a/libpurple/theme-manager.h Sun Apr 19 15:35:28 2009 +0000 +++ b/libpurple/theme-manager.h Mon Apr 20 00:10:51 2009 +0000 @@ -1,5 +1,5 @@ /** - * @file thememanager.h Theme Manager API + * @file theme-manager.h Theme Manager API */ /*
--- a/libpurple/xmlnode.h Sun Apr 19 15:35:28 2009 +0000 +++ b/libpurple/xmlnode.h Mon Apr 20 00:10:51 2009 +0000 @@ -335,11 +335,14 @@ * root node of an XML document will parse the entire document * into a tree of nodes, and return the xmlnode of the root. * - * @param str The string of xml. - * @param description The description of the file being parsed - * @process The utility that is calling xmlnode_from_file + * @param dir The directory where the file is located + * @param filename The filename + * @param 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 xmlnode_from_file. Used as + * the category for debugging. * - * @return The new node. + * @return The new node or NULL if an error occurred. * * @since 2.6.0 */
--- a/pidgin/gtkblist-theme-loader.h Sun Apr 19 15:35:28 2009 +0000 +++ b/pidgin/gtkblist-theme-loader.h Mon Apr 20 00:10:51 2009 +0000 @@ -1,5 +1,5 @@ /** - * @file gtkblist-loader.h Pidgin Buddy List Theme Loader Class API + * @file gtkblist-theme-loader.h Pidgin Buddy List Theme Loader Class API */ /* pidgin
--- a/pidgin/gtkblist-theme.h Sun Apr 19 15:35:28 2009 +0000 +++ b/pidgin/gtkblist-theme.h Mon Apr 20 00:10:51 2009 +0000 @@ -102,6 +102,8 @@ /** * Returns the background color of the buddy list. * + * @param theme The theme. + * * @returns A gdk color. */ GdkColor *pidgin_blist_theme_get_background_color(PidginBlistTheme *theme); @@ -110,6 +112,8 @@ * Returns the opacity of the buddy list window * (0.0 or clear to 1.0 fully opaque). * + * @param theme The theme. + * * @returns The opacity */ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme); @@ -117,6 +121,8 @@ /** * Returns the layout to be used with the buddy list. * + * @param theme The theme. + * * @returns The buddy list layout. */ PidginBlistLayout *pidgin_blist_theme_get_layout(PidginBlistTheme *theme); @@ -124,6 +130,8 @@ /** * Returns the background color to be used with expanded groups. * + * @param theme The theme. + * * @returns A gdk color. */ GdkColor *pidgin_blist_theme_get_expanded_background_color(PidginBlistTheme *theme); @@ -131,6 +139,8 @@ /** * Returns the text font and color to be used with expanded groups. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_expanded_text_info(PidginBlistTheme *theme); @@ -138,6 +148,8 @@ /** * Returns the background color to be used with collapsed groups. * + * @param theme The theme. + * * @returns A gdk color. */ GdkColor *pidgin_blist_theme_get_collapsed_background_color(PidginBlistTheme *theme); @@ -145,6 +157,8 @@ /** * Returns the text font and color to be used with collapsed groups. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_collapsed_text_info(PidginBlistTheme *theme); @@ -152,6 +166,8 @@ /** * Returns the colors to be used for contacts and chats. * + * @param theme The theme. + * * @returns A gdkcolor for contacts and chats. */ GdkColor *pidgin_blist_theme_get_contact_color(PidginBlistTheme *theme); @@ -159,6 +175,8 @@ /** * Returns the text font and color to be used for expanded contacts. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_contact_text_info(PidginBlistTheme *theme); @@ -166,6 +184,8 @@ /** * Returns the text font and color to be used for online buddies. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_online_text_info(PidginBlistTheme *theme); @@ -173,6 +193,8 @@ /** * Returns the text font and color to be used for away and idle buddies. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_away_text_info(PidginBlistTheme *theme); @@ -180,6 +202,8 @@ /** * Returns the text font and color to be used for offline buddies. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_offline_text_info(PidginBlistTheme *theme); @@ -187,6 +211,8 @@ /** * Returns the text font and color to be used for idle buddies. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_idle_text_info(PidginBlistTheme *theme); @@ -194,6 +220,8 @@ /** * Returns the text font and color to be used for buddies with unread messages. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_unread_message_text_info(PidginBlistTheme *theme); @@ -202,6 +230,8 @@ * Returns the text font and color to be used for chats with unread messages * that mention your nick. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_unread_message_nick_said_text_info(PidginBlistTheme *theme); @@ -209,6 +239,8 @@ /** * Returns the text font and color to be used for a buddy's status message. * + * @param theme The theme. + * * @returns A font and color pair. */ FontColorPair *pidgin_blist_theme_get_status_text_info(PidginBlistTheme *theme); @@ -218,6 +250,7 @@ /** * Sets the background color to be used for this buddy list theme. * + * @param theme The theme. * @param color The new background color. */ void pidgin_blist_theme_set_background_color(PidginBlistTheme *theme, const GdkColor *color); @@ -225,6 +258,7 @@ /** * Sets the opacity to be used for this buddy list theme. * + * @param theme The theme. * @param opacity The new opacity setting. */ void pidgin_blist_theme_set_opacity(PidginBlistTheme *theme, gdouble opacity); @@ -232,6 +266,7 @@ /** * Sets the buddy list layout to be used for this buddy list theme. * + * @param theme The theme. * @param layout The new layout. */ void pidgin_blist_theme_set_layout(PidginBlistTheme *theme, const PidginBlistLayout *layout); @@ -239,6 +274,7 @@ /** * Sets the background color to be used for expanded groups. * + * @param theme The theme. * @param color The new background color. */ void pidgin_blist_theme_set_expanded_background_color(PidginBlistTheme *theme, const GdkColor *color); @@ -246,13 +282,15 @@ /** * Sets the text color and font to be used for expanded groups. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_expanded_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the background color to be used for collapsed groups. * + * @param theme The theme. * @param color The new background color. */ void pidgin_blist_theme_set_collapsed_background_color(PidginBlistTheme *theme, const GdkColor *color); @@ -260,13 +298,15 @@ /** * Sets the text color and font to be used for expanded groups. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_collapsed_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the background color to be used for contacts and chats. * + * @param theme The theme. * @param color The color to use for contacts and chats. */ void pidgin_blist_theme_set_contact_color(PidginBlistTheme *theme, const GdkColor *color); @@ -274,42 +314,48 @@ /** * Sets the text color and font to be used for expanded contacts. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_contact_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the text color and font to be used for online buddies. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_online_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the text color and font to be used for away and idle buddies. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_away_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the text color and font to be used for offline buddies. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_offline_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the text color and font to be used for idle buddies. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_idle_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the text color and font to be used for buddies with unread messages. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_unread_message_text_info(PidginBlistTheme *theme, const FontColorPair *pair); @@ -317,14 +363,16 @@ * Sets the text color and font to be used for a chat with unread messages * that mention your nick. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_unread_message_nick_said_text_info(PidginBlistTheme *theme, const FontColorPair *pair); /** * Sets the text color and font to be used for buddy status messages. * - * @param pair The new text font at color pair. + * @param theme The theme. + * @param pair The new text font and color pair. */ void pidgin_blist_theme_set_status_text_info(PidginBlistTheme *theme, const FontColorPair *pair);
--- a/pidgin/gtkicon-theme-loader.h Sun Apr 19 15:35:28 2009 +0000 +++ b/pidgin/gtkicon-theme-loader.h Mon Apr 20 00:10:51 2009 +0000 @@ -1,5 +1,5 @@ /** - * @file gtkicon-loader.h Pidgin Icon Theme Loader Class API + * @file gtkicon-theme-loader.h Pidgin Icon Theme Loader Class API */ /* purple
--- a/pidgin/gtkicon-theme.h Sun Apr 19 15:35:28 2009 +0000 +++ b/pidgin/gtkicon-theme.h Mon Apr 20 00:10:51 2009 +0000 @@ -1,5 +1,5 @@ /** - * @file icon-theme.h Pidgin Icon Theme Class API + * @file gtkicon-theme.h Pidgin Icon Theme Class API */ /* pidgin @@ -72,6 +72,7 @@ /** * 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 * * @returns the filename of the icon event @@ -82,6 +83,7 @@ /** * 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 */