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

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

13 files changed, 149 insertions, 84 deletions

diff --git a/ChangeLog.API b/ChangeLog.API
index 6c49b978b8..6fdba25018 100644
--- a/ChangeLog.API
+++ b/ChangeLog.API
@@ -38,6 +38,7 @@ version 2.6.0 (??/??/2009):
 		Deprecated:
 		* purple_buddy_get_local_alias
 		* purple_notify_user_info_remove_entry
+		* purple_smiley_get_storing_dir
 		* purple_status_type_set_primary_attr
 		* purple_status_type_add_attr
 		* purple_status_type_add_attrs
diff --git a/libpurple/blist.h b/libpurple/blist.h
index 9ccb39b77d..1aaf021818 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,
@@ -261,6 +261,11 @@ PurpleBlistNode *purple_blist_get_root(void);
 
 /**
  * Returns the hash table of every buddy in the list.
+ * You MUST treat this data structure as immutable. The only use should
+ * be for iterating over the values (PurpleBuddy*) in performance-critical
+ * code.
+ *
+ * @see purple_find_buddy for the recommended alternative.
  *
  * @return The hash table of every buddy in the list.
  *
@@ -275,7 +280,7 @@ GHashTable *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.
@@ -284,7 +289,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
@@ -359,7 +364,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.
@@ -369,7 +374,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.
@@ -392,6 +397,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.
  */
@@ -491,12 +498,19 @@ PurpleChat *purple_chat_new(PurpleAccount *account, const char *alias, GHashTabl
 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);
 
@@ -603,7 +617,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
@@ -698,19 +712,23 @@ 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);
 
 /**
@@ -821,7 +839,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
  */
@@ -916,7 +934,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
@@ -925,7 +943,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.c b/libpurple/smiley.c
index 2c08b5994b..2b05c55d17 100644
--- a/libpurple/smiley.c
+++ b/libpurple/smiley.c
@@ -57,9 +57,7 @@ static GHashTable *smiley_checksum_index = NULL; /* checksum (char *) => smiley
 
 static guint save_timer = 0;
 static gboolean smileys_loaded = FALSE;
-static char *smileys_dir = NULL;
 
-#define SMILEYS_DEFAULT_FOLDER			"custom_smiley"
 #define SMILEYS_LOG_ID				"smileys"
 
 #define XML_FILE_NAME				"smileys.xml"
@@ -872,7 +870,7 @@ purple_smileys_find_by_checksum(const char *checksum)
 const char *
 purple_smileys_get_storing_dir(void)
 {
-	return smileys_dir;
+	return "";
 }
 
 void
@@ -881,8 +879,6 @@ purple_smileys_init()
 	smiley_shortcut_index = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL);
 	smiley_checksum_index = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL);
 
-	smileys_dir = g_build_filename(purple_user_dir(), SMILEYS_DEFAULT_FOLDER, NULL);
-
 	purple_smileys_load();
 }
 
@@ -897,6 +893,5 @@ purple_smileys_uninit()
 
 	g_hash_table_destroy(smiley_shortcut_index);
 	g_hash_table_destroy(smiley_checksum_index);
-	g_free(smileys_dir);
 }
 
diff --git a/libpurple/smiley.h b/libpurple/smiley.h
index ecb4385b6b..cb951b6cbf 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
- * by purple_buddy_icons_set_cache_dir().
- *
  * @return The directory to store custom smyles cached files to.
+ *
+ * @deprecated This function isn't used and does nothing and will be
+ *             removed in 3.0.0.
  */
 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 bfc41f2403..364f5abd6d 100644
--- a/libpurple/xmlnode.h
+++ b/libpurple/xmlnode.h
@@ -324,11 +324,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-loader.h b/pidgin/gtkblist-theme-loader.h
index a5a40621e3..049c1c6ceb 100644
--- a/pidgin/gtkblist-theme-loader.h
+++ b/pidgin/gtkblist-theme-loader.h
@@ -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
diff --git a/pidgin/gtkblist-theme.h b/pidgin/gtkblist-theme.h
index bcfb4649b4..176f0d5b9a 100644
--- a/pidgin/gtkblist-theme.h
+++ b/pidgin/gtkblist-theme.h
@@ -102,6 +102,8 @@ GType pidgin_blist_theme_get_type(void);
 /**
  * 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 @@ GType pidgin_blist_theme_get_type(void);
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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 @@ gdouble pidgin_blist_theme_get_opacity(PidginBlistTheme *theme);
 /**
  * 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, GdkColor *color);
@@ -225,6 +258,7 @@ void pidgin_blist_theme_set_background_color(PidginBlistTheme *theme, GdkColor *
 /**
  * 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 @@ void pidgin_blist_theme_set_opacity(PidginBlistTheme *theme, gdouble opacity);
 /**
  * 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, PidginBlistLayout *layout);
@@ -239,6 +274,7 @@ void pidgin_blist_theme_set_layout(PidginBlistTheme *theme, PidginBlistLayout *l
 /**
  * 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, GdkColor *color);
@@ -246,13 +282,15 @@ void pidgin_blist_theme_set_expanded_background_color(PidginBlistTheme *theme, G
 /**
  * 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, 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, GdkColor *color);
@@ -260,13 +298,15 @@ void pidgin_blist_theme_set_collapsed_background_color(PidginBlistTheme *theme,
 /**
  * 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, 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, GdkColor *color);
@@ -274,42 +314,48 @@ void pidgin_blist_theme_set_contact_color(PidginBlistTheme *theme, GdkColor *col
 /**
  * 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, 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, 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, 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, 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, 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, FontColorPair *pair);
 
@@ -317,14 +363,16 @@ void pidgin_blist_theme_set_unread_message_text_info(PidginBlistTheme *theme, Fo
  * 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, 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, FontColorPair *pair);
 
diff --git a/pidgin/gtkicon-theme-loader.h b/pidgin/gtkicon-theme-loader.h
index 57ab2b53a3..eccb85dc32 100644
--- a/pidgin/gtkicon-theme-loader.h
+++ b/pidgin/gtkicon-theme-loader.h
@@ -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
diff --git a/pidgin/gtkicon-theme.h b/pidgin/gtkicon-theme.h
index 0ba669d349..ce67048ba8 100644
--- a/pidgin/gtkicon-theme.h
+++ b/pidgin/gtkicon-theme.h
@@ -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 @@ 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
  */
diff --git a/pidgin/gtkstatus-icon-theme.h b/pidgin/gtkstatus-icon-theme.h
index 9dbc14c02d..ba8269a778 100644
--- a/pidgin/gtkstatus-icon-theme.h
+++ b/pidgin/gtkstatus-icon-theme.h
@@ -1,5 +1,5 @@
 /**
- * @file status_icon-theme.h  Pidgin Icon Theme  Class API
+ * @file gtkstatus-icon-theme.h  Pidgin Icon Theme  Class API
  */
 
 /* pidgin