Added notes for PRIVMSG and NOTICE about responses (re: #144).

src/proto/command.rs

@@ -49,8 +49,32 @@ pub enum Command {
 
     // 3.3 Sending messages
     /// PRIVMSG msgtarget :message
+    ///
+    /// ## Responding to a `PRIVMSG`
+    ///
+    /// When responding to a message, it is not sufficient to simply copy the message target
+    /// (msgtarget). This will work just fine for responding to messages in channels where the
+    /// target is the same for all participants. However, when the message is sent directly to a
+    /// user, this target will be that client's username, and responding to that same target will
+    /// actually mean sending itself a response. In such a case, you should instead respond to the
+    /// user sending the message as specified in the message prefix. Since this is a common
+    /// pattern, there is a utility function
+    /// [`Message::response_target`](../message/struct.Message.html#method.response_target)
+    /// which is used for this exact purpose.
     PRIVMSG(String, String),
     /// NOTICE msgtarget :message
+    ///
+    /// ## Responding to a `NOTICE`
+    ///
+    /// When responding to a notice, it is not sufficient to simply copy the message target
+    /// (msgtarget). This will work just fine for responding to messages in channels where the
+    /// target is the same for all participants. However, when the message is sent directly to a
+    /// user, this target will be that client's username, and responding to that same target will
+    /// actually mean sending itself a response. In such a case, you should instead respond to the
+    /// user sending the message as specified in the message prefix. Since this is a common
+    /// pattern, there is a utility function
+    /// [`Message::response_target`](../message/struct.Message.html#method.response_target)
+    /// which is used for this exact purpose.
     NOTICE(String, String),
 
     // 3.4 Server queries and commands