update documentation; minor bug fixes

cap.go

@@ -83,6 +83,10 @@ func handleCAP(c *Client, e Event) {
 	}
 }
 
+// handleCHGHOST handles incoming IRCv3 hostname change events. CHGHOST is
+// what occurs (when enabled) when a servers services change the hostname of
+// a user. Traditionally, this was simply resolved with a quick QUIT and JOIN,
+// however CHGHOST resolves this in a much cleaner fashion.
 func handleCHGHOST(c *Client, e Event) {
 	if len(e.Params) != 2 {
 		return
@@ -100,6 +104,8 @@ func handleCHGHOST(c *Client, e Event) {
 	c.state.mu.Unlock()
 }
 
+// handleAWAY handles incoming IRCv3 AWAY events, for which are sent both
+// when users are no longer away, or when they are away.
 func handleAWAY(c *Client, e Event) {
 	c.state.mu.Lock()
 	for chanName := range c.state.channels {
@@ -112,6 +118,10 @@ func handleAWAY(c *Client, e Event) {
 	c.state.mu.Unlock()
 }
 
+// handleACCOUNT handles incoming IRCv3 ACCOUNT events. ACCOUNT is sent when
+// a user logs into an account, logs out of their account, or logs into a
+// different account. The account backend is handled server-side, so this
+// could be NickServ, X (undernet?), etc.
 func handleACCOUNT(c *Client, e Event) {
 	if len(e.Params) != 1 {
 		return

client.go

@@ -709,8 +709,8 @@ func (c *Client) Whowas(nick string, amount int) error {
 }
 
 // GetServerOption retrieves a server capability setting that was retrieved
-// during client connection. This is also known as ISUPPORT. Will panic if
-// used when tracking has been disabled. Examples of usage:
+// during client connection. This is also known as ISUPPORT (or RPL_PROTOCTL).
+// Will panic if used when tracking has been disabled. Examples of usage:
 //
 //   nickLen, success := GetServerOption("MAXNICKLEN")
 //
@@ -731,7 +731,7 @@ func (c *Client) GetServerOption(key string) (result string, success bool) {
 // used when tracking has been disabled.
 func (c *Client) ServerName() (name string) {
 	if c.Config.DisableTracking {
-		panic("GetServerOption() used when tracking is disabled")
+		panic("ServerName() used when tracking is disabled")
 	}
 
 	name, _ = c.GetServerOption("SERVER")
@@ -740,11 +740,11 @@ func (c *Client) ServerName() (name string) {
 }
 
 // NetworkName returns the network identifier. E.g. "EsperNet", "ByteIRC".
-// May be empty if the server does not support RPL_ISUPPORT. Will panic if
-// used when tracking has been disabled.
+// May be empty if the server does not support RPL_ISUPPORT (or RPL_PROTOCTL).
+// Will panic if used when tracking has been disabled.
 func (c *Client) NetworkName() (name string) {
 	if c.Config.DisableTracking {
-		panic("GetServerOption() used when tracking is disabled")
+		panic("NetworkName() used when tracking is disabled")
 	}
 
 	name, _ = c.GetServerOption("NETWORK")
@@ -758,7 +758,7 @@ func (c *Client) NetworkName() (name string) {
 // disabled.
 func (c *Client) ServerVersion() (version string) {
 	if c.Config.DisableTracking {
-		panic("GetServerOption() used when tracking is disabled")
+		panic("ServerVersion() used when tracking is disabled")
 	}
 
 	version, _ = c.GetServerOption("VERSION")
@@ -767,8 +767,12 @@ func (c *Client) ServerVersion() (version string) {
 }
 
 // ServerMOTD returns the servers message of the day, if the server has sent
-// it upon connect.
+// it upon connect. Will panic if used when tracking has been disabled.
 func (c *Client) ServerMOTD() (motd string) {
+	if c.Config.DisableTracking {
+		panic("ServerMOTD() used when tracking is disabled")
+	}
+
 	c.state.mu.Lock()
 	motd = c.state.motd
 	c.state.mu.Unlock()

handlers.go

@@ -130,6 +130,8 @@ func handlePART(c *Client, e Event) {
 	c.state.mu.Unlock()
 }
 
+// handleTOPIC handles incoming TOPIC events and keeps channel tracking info
+// updated with the latest channel topic.
 func handleTOPIC(c *Client, e Event) {
 	var name string
 	switch len(e.Params) {
@@ -234,6 +236,9 @@ func handleQUIT(c *Client, e Event) {
 	c.state.mu.Unlock()
 }
 
+// handleMYINFO handles incoming MYINFO events -- these are commonly used
+// to tell us what the server name is, what version of software is being used
+// as well as what channel and user modes are being used on the server.
 func handleMYINFO(c *Client, e Event) {
 	// Malformed or odd output. As this can differ strongly between networks,
 	// just skip it.
@@ -247,10 +252,15 @@ func handleMYINFO(c *Client, e Event) {
 	c.state.mu.Unlock()
 }
 
+// handleISUPPORT handles incoming RPL_ISUPPORT (also known as RPL_PROTOCTL)
+// events. These commonly contain the server capabilities and limitations.
+// For example, things like max channel name length, or nickname length.
 func handleISUPPORT(c *Client, e Event) {
 	// Must be a ISUPPORT-based message. 005 is also used for server bounce
 	// related things, so this callback may be triggered during other
 	// situations.
+
+	// Also known as RPL_PROTOCTL.
 	if !strings.HasSuffix(e.Trailing, "this server") {
 		return
 	}
@@ -277,6 +287,8 @@ func handleISUPPORT(c *Client, e Event) {
 	c.state.mu.Unlock()
 }
 
+// handleMOTD handles incoming MOTD messages and buffers them up for use with
+// Client.ServerMOTD().
 func handleMOTD(c *Client, e Event) {
 	c.state.mu.Lock()