im.pidgin.pidgin: 683c1f218ebbbd0e0b65c6d1bd95f2d9dfb2bb17

[resiak at soc.pidgin.im]

-----------------------------------------------------------------
Revision: 683c1f218ebbbd0e0b65c6d1bd95f2d9dfb2bb17
Ancestor: f9d3abd0678a04291edd671c4e5d87c7217984bb
Author: resiak at soc.pidgin.im
Date: 2007-10-12T16:27:41
Branch: im.pidgin.pidgin

Modified files:
        libpurple/prpl.h

ChangeLog: 

Add some (but not much!) documentation to PurplePluginProtocolInfo.

-------------- next part --------------
============================================================
--- libpurple/prpl.h	619fc26a7e52ef07b82536c9ba88bab5b7397de5
+++ libpurple/prpl.h	b3aaff3b33a417e1e80d01af56179273031269a0
@@ -226,11 +226,17 @@ struct _PurplePluginProtocolInfo
 	void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
 
 	/**
-	 * This must be implemented, and must add at least the offline
-	 * and online states.
+	 * Returns a list of #PurpleStatusType which exist for this account;
+	 * this must be implemented, and must add at least the offline and
+	 * online states.
 	 */
 	GList *(*status_types)(PurpleAccount *account);
 
+	/**
+	 * Returns a list of #PurpleMenuAction structs, which represent extra
+	 * actions to be shown in (for example) the right-click menu for @a
+	 * node.
+	 */
 	GList *(*blist_node_menu)(PurpleBlistNode *node);
 	GList *(*chat_info)(PurpleConnection *);
 	GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
@@ -258,6 +264,10 @@ struct _PurplePluginProtocolInfo
 
 	void (*set_info)(PurpleConnection *, const char *info);
 	unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
+	/**
+	 * Should arrange for purple_notify_userinfo() to be called with
+	 * @a who's user info.
+	 */
 	void (*get_info)(PurpleConnection *, const char *who);
 	void (*set_status)(PurpleAccount *account, PurpleStatus *status);
 
@@ -287,8 +297,13 @@ struct _PurplePluginProtocolInfo
 	/** new user registration */
 	void (*register_user)(PurpleAccount *);
 
-	/* get "chat buddy" info and away message */
+	/** Deprecated and vestigal; use #get_cb_real_name and #get_info
+	 *  instead.
+	 */
 	void (*get_cb_info)(PurpleConnection *, int, const char *who);
+	/** Also deprecated and vestigal; use #get_cb_real_name and
+	 *  #status_text instead.
+	 */
 	void (*get_cb_away)(PurpleConnection *, int, const char *who);
 
 	/** save/store buddy's alias on server list/roster */
@@ -348,10 +363,13 @@ struct _PurplePluginProtocolInfo
 	/* room list serialize */
 	char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
 
-	/* Remove the user from the server. (This is only at the bottom to keep binary compatibility.)
-	 * The account can either be connected or disconnected. After the removal is finished,
-	 * the connection will stay open and has to be closed!
+	/** Remove the user from the server.  The account can either be
+	 * connected or disconnected. After the removal is finished, the
+	 * connection will stay open and has to be closed!
 	 */
+	/* This is here rather than next to register_user for API compatibility
+	 * reasons.
+	 */
 	void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
 	
 	/* Attention API for sending & receiving zaps/nudges/buzzes etc. */