--- a/stream.go	Thu Dec 29 11:25:26 2011 -0700
+++ b/stream.go	Fri Dec 30 17:16:37 2011 -0700
@@ -551,7 +551,9 @@
 // Register a callback to handle the next XMPP stanza (iq, message, or
 // presence) with a given id. The provided function will not be called
 // more than once. If it returns false, the stanza will not be made
-// available on the normal Client.In channel.
+// available on the normal Client.In channel. The stanza handler
+// must not read from that channel, as deliveries on it cannot proceed
+// until the handler returns true or false.
 func (cl *Client) HandleStanza(id string, f func(Stanza) bool) {
 	h := &stanzaHandler{id: id, f: f}
 	cl.handlers <- h