cpw.darkrain42.docs: 0c12c56a: More documentation (mostly little change...

[paul at darkrain42.org]

-----------------------------------------------------------------
Revision: 0c12c56a9f1f3094bb926125a44c04a556e1dee5
Ancestor: 5a6a0a50a16d0e13da565ba4c60891abc8c1e6d9
Author: paul at darkrain42.org
Date: 2009-03-12T06:19:15
Branch: im.pidgin.cpw.darkrain42.docs
URL: http://d.pidgin.im/viewmtn/revision/info/0c12c56a9f1f3094bb926125a44c04a556e1dee5

Modified files:
        libpurple/blist.h

ChangeLog: 

More documentation (mostly little changes)

-------------- next part --------------
============================================================
--- libpurple/blist.h	8094fa3f7971065958c66bec7d943f88d8fccbd3
+++ libpurple/blist.h	ed05bd23811ffb82fe865f6b16fd61edf3c0659c
@@ -280,7 +280,7 @@ GHashTable *purple_blist_get_buddies(voi
  *
  * @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.
@@ -289,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
@@ -364,7 +364,7 @@ PurpleBlistNode *purple_blist_node_get_s
  * @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.
@@ -374,7 +374,7 @@ void *purple_blist_node_get_ui_data(cons
  *
  * @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.
@@ -397,6 +397,8 @@ void purple_blist_set_visible(gboolean s
 /**
  * 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.
  */
@@ -496,12 +498,19 @@ void purple_blist_add_chat(PurpleChat *c
 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);
 
@@ -608,7 +617,7 @@ void purple_blist_add_buddy(PurpleBuddy 
  * 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
@@ -703,19 +712,23 @@ void purple_contact_invalidate_priority_
 
 /**
  * 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);
 
 /**
@@ -826,7 +839,7 @@ PurpleBuddy *purple_find_buddy_in_group(
  * 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
  */
@@ -921,7 +934,7 @@ const char *purple_group_get_name(Purple
 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
@@ -930,7 +943,7 @@ void purple_blist_add_account(PurpleAcco
 
 
 /**
- * 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