changeset 26674:247e2a759ed2

More documentation (mostly little changes)

--- a/libpurple/blist.h	Thu Mar 12 06:01:56 2009 +0000
+++ b/libpurple/blist.h	Thu Mar 12 06:19:15 2009 +0000
@@ -280,7 +280,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.
@@ -289,7 +289,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
@@ -364,7 +364,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.
@@ -374,7 +374,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.
@@ -397,6 +397,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.
  */
@@ -496,12 +498,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);
 
@@ -608,7 +617,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
@@ -703,19 +712,23 @@
 
 /**
  * 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 @@
  * 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(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 @@
 
 
 /**
- * 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