propagate from branch 'im.pidgin.pidgin' (head d2bc0c2ff7f43ce21af6aeb024584d995bc57143)

            to branch 'im.pidgin.cpw.darkrain42.docs' (head a1d0db99c31396c6360eb8b2a34e4bae7e40b827)

8 files changed, 88 insertions, 72 deletions

diff --git a/libpurple/blist.h b/libpurple/blist.h
index d425d94f29..895cc65d10 100644
--- a/libpurple/blist.h
+++ b/libpurple/blist.h
@@ -118,8 +118,8 @@ typedef enum
 
 /**
  * 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 @@ struct _PurpleBlistUiOps
 		       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 @@ GSList *purple_blist_get_buddies(void);
  *
  * @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 @@ void *purple_blist_get_ui_data(void);
  *
  * @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 @@ PurpleBlistNode *purple_blist_node_get_sibling_prev(PurpleBlistNode *node);
  * @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 @@ void *purple_blist_node_get_ui_data(const PurpleBlistNode *node);
  *
  * @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 @@ void purple_blist_set_visible(gboolean show);
 /**
  * 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_chat_destroy(PurpleChat *chat);
 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 @@ void purple_blist_add_buddy(PurpleBuddy *buddy, PurpleContact *contact, PurpleGr
  * 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 @@ void purple_contact_invalidate_priority_buddy(PurpleContact *contact);
 
 /**
  * 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 @@ PurpleBuddy *purple_find_buddy_in_group(PurpleAccount *account, const char *name
  * 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 @@ gboolean purple_group_on_account(PurpleGroup *g, PurpleAccount *account);
 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 @@ void purple_blist_add_account(PurpleAccount *account);
 
 
 /**
- * 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
diff --git a/libpurple/smiley.h b/libpurple/smiley.h
index ecb4385b6b..cfd2c0bb43 100644
--- a/libpurple/smiley.h
+++ b/libpurple/smiley.h
@@ -61,44 +61,41 @@ extern "C" {
 /*@{*/
 
 /**
- * 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 @@ purple_smiley_delete(PurpleSmiley *smiley);
  * 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 @@ const char *purple_smiley_get_checksum(const PurpleSmiley *smiley);
  * 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 @@ PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley);
  * 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 @@ const char *purple_smiley_get_extension(const PurpleSmiley *smiley);
  * 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 @@ char *purple_smiley_get_full_path(PurpleSmiley *smiley);
 /*@{*/
 
 /**
- * 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 @@ GList *
 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 @@ purple_smileys_find_by_checksum(const char *checksum);
 /**
  * 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);
 
diff --git a/libpurple/sound-theme.h b/libpurple/sound-theme.h
index 3c40a462c2..3814e4527f 100644
--- a/libpurple/sound-theme.h
+++ b/libpurple/sound-theme.h
@@ -73,6 +73,7 @@ GType purple_sound_theme_get_type(void);
 /**
  * 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 @@ const gchar *purple_sound_theme_get_file(PurpleSoundTheme *theme,
 /**
  * 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 @@ gchar *purple_sound_theme_get_file_full(PurpleSoundTheme *theme,
 /**
  * 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,
diff --git a/libpurple/theme-loader.h b/libpurple/theme-loader.h
index 8cd82155c3..5496f2c7e2 100644
--- a/libpurple/theme-loader.h
+++ b/libpurple/theme-loader.h
@@ -82,7 +82,8 @@ const gchar *purple_theme_loader_get_type_string(PurpleThemeLoader *self);
 /**
  * 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
  */
diff --git a/libpurple/theme-manager.h b/libpurple/theme-manager.h
index 96e0a6986d..c34b6bc160 100644
--- a/libpurple/theme-manager.h
+++ b/libpurple/theme-manager.h
@@ -1,5 +1,5 @@
 /**
- * @file thememanager.h  Theme Manager API
+ * @file theme-manager.h  Theme Manager API
  */
 
 /*
diff --git a/libpurple/xmlnode.h b/libpurple/xmlnode.h
index b311e8e82c..4175cede81 100644
--- a/libpurple/xmlnode.h
+++ b/libpurple/xmlnode.h
@@ -335,11 +335,14 @@ void xmlnode_free(xmlnode *node);
  * 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
- *
- * @return The new node.
+ * @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 or NULL if an error occurred.
  *
  * @since 2.6.0
  */
diff --git a/pidgin/gtkblist-theme.h b/pidgin/gtkblist-theme.h
index 9636dddb28..2c4fb07fb0 100644
--- a/pidgin/gtkblist-theme.h
+++ b/pidgin/gtkblist-theme.h
@@ -341,7 +341,7 @@ void pidgin_blist_theme_set_expanded_background_color(PidginBlistTheme *theme, c
  * 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 @@ void pidgin_blist_theme_set_collapsed_background_color(PidginBlistTheme *theme,
  * 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 @@ void pidgin_blist_theme_set_contact_color(PidginBlistTheme *theme, const GdkColo
  * 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 @@ void pidgin_blist_theme_set_contact_text_info(PidginBlistTheme *theme, const Pid
  * 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 @@ void pidgin_blist_theme_set_online_text_info(PidginBlistTheme *theme, const Pidg
  * 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 @@ void pidgin_blist_theme_set_away_text_info(PidginBlistTheme *theme, const Pidgin
  * 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 @@ void pidgin_blist_theme_set_offline_text_info(PidginBlistTheme *theme, const Pid
  * 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 @@ void pidgin_blist_theme_set_idle_text_info(PidginBlistTheme *theme, const Pidgin
  * 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 @@ void pidgin_blist_theme_set_unread_message_text_info(PidginBlistTheme *theme, co
  * 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 @@ void pidgin_blist_theme_set_unread_message_nick_said_text_info(PidginBlistTheme
  * 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);
 
diff --git a/pidgin/gtkicon-theme.h b/pidgin/gtkicon-theme.h
index f479f07c96..ce67048ba8 100644
--- a/pidgin/gtkicon-theme.h
+++ b/pidgin/gtkicon-theme.h
@@ -72,6 +72,7 @@ GType pidgin_icon_theme_get_type(void);
 /**
  * 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 @@ const gchar *pidgin_icon_theme_get_icon(PidginIconTheme *theme,
 /**
  * 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
  */