--- a/src/irc_chan.h	Mon Mar 30 01:31:13 2009 +0300
+++ b/src/irc_chan.h	Mon Mar 30 01:31:27 2009 +0300
@@ -26,7 +26,12 @@
 };
 
 /**
- * Semantic IRC channel callbacks.
+ * High-level IRC channel callbacks for convenience.
+ *
+ * These are based on the normal irc_chan::handlers interface, and you can use both freely.
+ *
+ * The on_self_* handlers are for actions that affect our own status on the channel, the rest are only for actions
+ * done by other users.
  *
  * Where callbacks have irc_nm arguments, these are MAY be given as NULL if the prefix could not be parsed.
  */
@@ -51,22 +56,9 @@
 };
 
 /**
- * Invoke the given callback with the given args
- */
-#define IRC_CHAN_INVOKE_CALLBACK(chan, _cb_name_, ...)          \
-    do {                                                        \
-        struct chain_head *head;                                \
-                                                                \
-        CHAIN_FOREACH(&(chan)->callbacks, head) {               \
-            const struct irc_chan_callbacks *callbacks = head->chain;       \
-                                                                \
-            if (callbacks->_cb_name_)                           \
-                callbacks->_cb_name_((chan), ## __VA_ARGS__, head->arg);    \
-        }                                                       \
-    } while (0);
-
-/**
- * Per-channel-user state
+ * Per-channel-user state. This is used to store the list of irc_user's on an irc_chan.
+ *
+ * The nickname is accessible via user->nickname.
  */
 struct irc_chan_user {
     /** The per-network user info */
@@ -77,23 +69,26 @@
 };
 
 /**
- * IRC channel state
+ * Persistent IRC channel state, part of irc_net.
+ *
+ * This stores the channel's info, status flags, users list, and handlers/callbacks.
+ *
+ * Create/get channels using the irc_net_add_chan()/irc_net_get_chan() interface, and then attach your own
+ * callbacks/handlers using irc_chan_add_callbacks()/irc_chan::handlers and irc_cmd_add().
+ *
+ * Note that irc_net will propagate all relevant events for each channel.
  */
 struct irc_chan {
-    /** The irc_net.channels list */
-    TAILQ_ENTRY(irc_chan) node;
-
-    /* The network we're on */
+    /** The network we're part of */
     struct irc_net *net;
 
     /** Our identifying info */
     struct irc_chan_info info;
     
     /** 
-     * @group State flags 
+     * @defgroup irc_chan_state State flags 
      * @{ 
      */
-
     /** JOIN request sent, waiting for reply */
     bool joining;
 
@@ -113,6 +108,9 @@
 
     /** High-level user callbacks */
     struct chain_list callbacks;
+
+    /** The irc_net::channels list */
+    TAILQ_ENTRY(irc_chan) net_channels;
 };
 
 /**
@@ -138,7 +136,7 @@
 void irc_chan_destroy (struct irc_chan *chan);
 
 /**
- * Add high-level irc_chan callbacks
+ * Add a set of high-level irc_chan callbacks. Not all callbacks need to be implemented.
  */
 err_t irc_chan_add_callbacks (struct irc_chan *chan, const struct irc_chan_callbacks *callbacks, void *arg);
 
@@ -150,20 +148,19 @@
 /**
  * Look up an irc_chan_user struct by nickname for this channel, returning NULL if no such chan_user exists.
  *
+ * Be careful not to hold on to this, as the irc_chan_user struct may be released if the user leaves the channel.
+ *
  * @param chan the channel context
  * @param nickname the user's current nickname
- * @param return the irc_chan_user state, or NULL if nickname not found
+ * @return the irc_chan_user state, or NULL if nickname not found
  */
 struct irc_chan_user* irc_chan_get_user (struct irc_chan *chan, const char *nickname);
 
 /**
  * Send the initial JOIN message.
  *
- * The channel must be in the IRC_CHAN_INIT state, and will transition to the IRC_CHAN_JOINING state.
- *
  * @param chan the channel to JOIN
  */
 err_t irc_chan_join (struct irc_chan *chan);
 
-
 #endif