changeset 30720:7a0ae0a9d716

Document MsnTable. Does fallback table is really needed? It's only set for XFR in notification.c and it uses the same callback.

--- a/libpurple/protocols/msn/table.h	Wed Mar 31 17:32:36 2010 +0000
+++ b/libpurple/protocols/msn/table.h	Wed Mar 31 19:35:20 2010 +0000
@@ -34,20 +34,60 @@
 
 struct _MsnTable
 {
-	GHashTable *cmds;
-	GHashTable *msgs;
-	GHashTable *errors;
+	GHashTable *cmds; 		/**< Callbacks that manage command response. */
+	GHashTable *msgs; 		/**< Callbacks that manage incoming messages. */
+	GHashTable *errors; 	/**< Callbacks that manage command errors. */
 
-	GHashTable *async;
-	GHashTable *fallback;
+	GHashTable *async; 		/**< Callbacks that manage incoming asyncronous messages. */
+	/* TODO: Does this one is really needed? */
+	GHashTable *fallback; 	/**< Fallback callback. */
 };
 
+/**
+ * Create a new instance of a MsnTable which map commands, errors and messages
+ * with callbacks that will handle it.
+ *
+ * @return A new MsnTable.
+ */
 MsnTable *msn_table_new(void);
+
+/**
+ * Destroy a MsnTable.
+ *
+ * @param table The MsnTable to be destroyed.
+ */
 void msn_table_destroy(MsnTable *table);
 
+/**
+ * Relate an incomming command from server with a callback able to handle
+ * the event.
+ *
+ * @param table 	The MsnTable.
+ * @param command 	If NULL this add an incoming asyncronous command set in answer.
+ * 					Else, the command sent.
+ * @param answer 	The server answer to 'command'. If 'command' is NULL,
+ * 					the asyncronous command sent by the server.
+ * @param cb 		Callback to handle this event.
+ */
 void msn_table_add_cmd(MsnTable *table, char *command, char *answer,
 					   MsnTransCb cb);
+
+/**
+ * Set a callback to handle incoming command errors.
+ *
+ * @param table 	The MsnTable.
+ * @param answer 	Incoming command with error.
+ * @param cb 		Callback to handle this error.
+ */
 void msn_table_add_error(MsnTable *table, char *answer, MsnErrorCb cb);
+
+/**
+ * Relate a message Content-type with a callback able to handle it.
+ *
+ * @param table 	The MsnTable.
+ * @param type 		The Message Content-Type.
+ * @param cb 		Callback to handle this Content-type.
+ */
 void msn_table_add_msg_type(MsnTable *table, char *type, MsnMsgTypeCb cb);
 
 #endif /* MSN_TABLE_H */