pidgin: 6f11e9ff: Document a few types in cmds, partly to ...

[resiak at pidgin.im]

-----------------------------------------------------------------
Revision: 6f11e9ff55b5d55cea2f29b8001fc2b6598eb2a4
Ancestor: c692f6fe1b8c7e0dd4b0099bd67703d5941ddac5
Author: resiak at pidgin.im
Date: 2008-06-15T12:50:23
Branch: im.pidgin.pidgin
URL: http://d.pidgin.im/viewmtn/revision/info/6f11e9ff55b5d55cea2f29b8001fc2b6598eb2a4

Modified files:
        libpurple/cmds.h

ChangeLog: 

Document a few types in cmds, partly to make doxygen links to those types work.

-------------- next part --------------
============================================================
--- libpurple/cmds.h	ad751a42c6357b659ae8d5b1462323d83aacae8a
+++ libpurple/cmds.h	877e4437774d5a1cd82e07e462e55ede50d9edd2
@@ -30,6 +30,7 @@
 /**************************************************************************/
 /*@{*/
 
+/** The possible results of running a command with purple_cmd_do_command(). */
 typedef enum _PurpleCmdStatus {
 	PURPLE_CMD_STATUS_OK,
 	PURPLE_CMD_STATUS_FAILED,
@@ -39,16 +40,31 @@ typedef enum _PurpleCmdStatus {
 	PURPLE_CMD_STATUS_WRONG_TYPE,
 } PurpleCmdStatus;
 
+/** Commands registered with the core return one of these values when run.
+ *  Normally, a command will want to return one of the first two; in some
+ *  unusual cases, you might want to have several functions called for a
+ *  particular command; in this case, they should return
+ *  #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other
+ *  commands with the same name.
+ */
 typedef enum _PurpleCmdRet {
-	PURPLE_CMD_RET_OK,       /**< Everything's okay. Don't look for another command to call. */
+	PURPLE_CMD_RET_OK,       /**< Everything's okay; Don't look for another command to call. */
 	PURPLE_CMD_RET_FAILED,   /**< The command failed, but stop looking.*/
 	PURPLE_CMD_RET_CONTINUE, /**< Continue, looking for other commands with the same name to call. */
 } PurpleCmdRet;
 
 #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func)
 
+/** A function implementing a command, as passed to purple_cmd_register().
+ *
+ *  @todo document the arguments to these functions.
+ * */
 typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd,
                                   gchar **args, gchar **error, void *data);
+/** A unique integer representing a command registered with
+ *  purple_cmd_register(), which can subsequently be passed to
+ *  purple_cmd_unregister() to unregister that command.
+ */
 typedef guint PurpleCmdId;
 
 typedef enum _PurpleCmdPriority {