cpw.qulogic.msnp16: 34c0e1ea: Document MsnTable.

[masca at cpw.pidgin.im]

-----------------------------------------------------------------
Revision: 34c0e1eaebc87fff2e8bdb3d04e3a0b8867837d6
Ancestor: dc54108c6dae325a53d8a79336f144d5e80c1781
Author: masca at cpw.pidgin.im
Date: 2010-03-31T19:35:20
Branch: im.pidgin.cpw.qulogic.msnp16
URL: http://d.pidgin.im/viewmtn/revision/info/34c0e1eaebc87fff2e8bdb3d04e3a0b8867837d6

Modified files:
        libpurple/protocols/msn/table.h

ChangeLog: 

Document MsnTable.

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

-------------- next part --------------
============================================================
--- libpurple/protocols/msn/table.h	3a3e99f624b7aba158045d1389b90ebbdfd0c0e0
+++ libpurple/protocols/msn/table.h	b6a5d48741a58ab19412d72325d8803d44fcb09e
@@ -34,20 +34,60 @@ struct _MsnTable
 
 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 */