Mercurial > pidgin

changeset 26681:84ab7b2db114

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
propagate from branch 'im.pidgin.pidgin' (head 76c6ab76464455ef2db1b4037f1e13745bb1d510) to branch 'im.pidgin.cpw.darkrain42.docs' (head ed14613587b57ee08712bcfb95b7a27861b6c20e)
author Paul Aurich <paul@darkrain42.org>
date Sat, 25 Apr 2009 23:26:47 +0000
parents 75cbde35d8e3 (current diff) f7bc9d6e844d (diff)
children 0c4976fb5f57
files ChangeLog.API pidgin/gtkblist-theme.h pidgin/gtkicon-theme.h pidgin/gtknotify.h
diffstat 8 files changed, 87 insertions(+), 71 deletions(-) [+]
line wrap: on
line diff
--- a/libpurple/blist.h	Sat Apr 25 22:42:16 2009 +0000
+++ b/libpurple/blist.h	Sat Apr 25 23:26:47 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	Sat Apr 25 22:42:16 2009 +0000
+++ b/libpurple/smiley.h	Sat Apr 25 23:26:47 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	Sat Apr 25 22:42:16 2009 +0000
+++ b/libpurple/sound-theme.h	Sat Apr 25 23:26:47 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	Sat Apr 25 22:42:16 2009 +0000
+++ b/libpurple/theme-loader.h	Sat Apr 25 23:26:47 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	Sat Apr 25 22:42:16 2009 +0000
+++ b/libpurple/theme-manager.h	Sat Apr 25 23:26:47 2009 +0000
@@ -1,5 +1,5 @@
 /**
- * @file thememanager.h  Theme Manager API
+ * @file theme-manager.h  Theme Manager API
  */
 
 /*
--- a/libpurple/xmlnode.h	Sat Apr 25 22:42:16 2009 +0000
+++ b/libpurple/xmlnode.h	Sat Apr 25 23:26:47 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.h	Sat Apr 25 22:42:16 2009 +0000
+++ b/pidgin/gtkblist-theme.h	Sat Apr 25 23:26:47 2009 +0000
@@ -341,7 +341,7 @@
  * Sets the text color and font to be used for expanded groups.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_expanded_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -357,7 +357,7 @@
  * Sets the text color and font to be used for expanded groups.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_collapsed_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -373,7 +373,7 @@
  * Sets the text color and font to be used for expanded contacts.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_contact_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -381,7 +381,7 @@
  * Sets the text color and font to be used for online buddies.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_online_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -389,7 +389,7 @@
  * Sets the text color and font to be used for away and idle buddies.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_away_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -397,7 +397,7 @@
  * Sets the text color and font to be used for offline buddies.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_offline_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -405,7 +405,7 @@
  * Sets the text color and font to be used for idle buddies.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_idle_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -413,7 +413,7 @@
  * Sets the text color and font to be used for buddies with unread messages.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_unread_message_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -422,7 +422,7 @@
  * that mention your nick.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_unread_message_nick_said_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
@@ -430,7 +430,7 @@
  * Sets the text color and font to be used for buddy status messages.
  *
  * @param theme  The PidginBlist theme.
- * @param pair The new text font at color pair.
+ * @param pair The new text font and color pair.
  */
 void pidgin_blist_theme_set_status_text_info(PidginBlistTheme *theme, const PidginThemeFont *pair);
 
--- a/pidgin/gtkicon-theme.h	Sat Apr 25 22:42:16 2009 +0000
+++ b/pidgin/gtkicon-theme.h	Sat Apr 25 23:26:47 2009 +0000
@@ -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
  */