cpw.darkrain42.docs: 3e88c816: Exposing the GHashTable seems crazy to m...

[paul at darkrain42.org]

-----------------------------------------------------------------
Revision: 3e88c816c99890a92e616803a7295e85e17fe8b3
Ancestor: 6ddba69dc6d0bac552c512dd4495b255463c1c5c
Author: paul at darkrain42.org
Date: 2009-03-12T05:56:04
Branch: im.pidgin.cpw.darkrain42.docs
URL: http://d.pidgin.im/viewmtn/revision/info/3e88c816c99890a92e616803a7295e85e17fe8b3

Modified files:
        libpurple/blist.h

ChangeLog: 

Exposing the GHashTable seems crazy to me. See #8644.

-------------- next part --------------
============================================================
--- libpurple/blist.h	940d68f8d08cae1fc27ffa04af27adef9821c377
+++ libpurple/blist.h	8094fa3f7971065958c66bec7d943f88d8fccbd3
@@ -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,7 +261,12 @@ PurpleBlistNode *purple_blist_get_root(v
 
 /**
  * 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.
  *
  * @since 2.6.0