diff -r 5e7e64544cb7 -r f0db6ebf18b9 src/irc_cmd.h
--- a/src/irc_cmd.h	Mon Mar 30 01:31:13 2009 +0300
+++ b/src/irc_cmd.h	Mon Mar 30 01:31:27 2009 +0300
@@ -4,27 +4,32 @@
 /**
  * @file
  *
- * Flexible command handlers callback lists for use with irc_lines
+ * Command handlers callback lists for use with irc_line's
  */
 
 #include "irc_line.h"
 #include "chain.h"
 
 /**
- * Single command -> handler mapping for lookup
+ * A single command name + handler function lookup entry. This defines the irc_line::command to handle, and the function used to handle it.
+ *
+ * Note that when an irc_line is matched against an array of these, only the *first* matching handler is invoked.
  */
 struct irc_cmd_handler {
     /** The command name to match */
     const char *command;
 
-    /** The handler function */
+    /**
+     * The handler function.
+     *
+     * @param line the irc_line that matched the command
+     * @param arg the context arg, as given to irc_cmd_add.
+     */
     void (*func) (const struct irc_line *line, void *arg);
 };
 
 /**
- * @struct irc_cmd_handlers
- *
- * A dynamic list of irc_cmd_chain handlers
+ * A dynamic list of irc_cmd_handler's
  */
 typedef struct chain_list irc_cmd_handlers_t;
 
@@ -34,22 +39,35 @@
 void irc_cmd_init (irc_cmd_handlers_t *handlers);
 
 /**
- * Add an irc_cmd_chain to the irc_cmd_handlers list for the given handlers/arg
+ * Append the given NULL-termianted array of irc_cmd_handler's to the irc_cmd_handlers list, without copying it.
+ *
+ * @param handlers the irc_cmd_handlers_t
+ * @param list the { NULL, NULL } termianted array of irc_cmd_handlers
+ * @param arg the opaque context argument, will be passed to the func's of the given list when invoked
  */
 err_t irc_cmd_add (irc_cmd_handlers_t *handlers, const struct irc_cmd_handler *list, void *arg);
 
 /**
- * Trigger irc_cmd_chain callbacks for the given irc_line
+ * Trigger all relevant handlers for the given irc_line.
+ *
+ * @param handlers the irc_cmd_handlers_t
+ * @param line the line to match against the handlers and invoke the func with
  */
 void irc_cmd_invoke (irc_cmd_handlers_t *handlers, const struct irc_line *line);
 
 /**
- * Remove a previously added chain_head from the irc_cmd_handlers list with the given list/arg
+ * Remove a previously added handler list.
+ *
+ * @param handlers the irc_cmd_handlers_t
+ * @param list the list given to irc_cmd_add, compared as pointer value
+ * @param arg the context arg given to irc_cmd_add, compared as pointer value
  */
 void irc_cmd_remove (irc_cmd_handlers_t *handlers, const struct irc_cmd_handler *list, void *arg);
 
 /**
- * Cleanup an irc_cmd_handlers list
+ * Cleanup an irc_cmd_handlers list, releasing all memory.
+ *
+ * @param handlers the irc_cmd_handlers_t to cleanup
  */
 void irc_cmd_free (irc_cmd_handlers_t *handlers);