2 files changed, 9 insertions(+), 8 deletions(-)

M doc.go
M session.go

@@ 83,8 83,8 @@
 //
 // However, writing individual XML tokens can be tedious and error prone.
 // The mellium.im/xmpp/stanza package contains functions and structs that aid in
-// the construction of message, presence and IQ elements which have special
-// semantics in XMPP and are known as "stanzas".
+// the construction of message, presence and info/query (IQ) elements which have
+// special semantics in XMPP and are known as "stanzas".
 // These can be sent with the Send and SendElement methods.
 //
 //     // Send initial presence to let the server know we want to receive messages.


@@ 94,6 94,7 @@
 // polling for incoming XML on the input stream—and possibly writing to the
 // output stream in response—easier, we need a long running goroutine.
 // Session includes the Serve method for starting this processing.
+//
 // Serve provides a Handler with access to the stream but prevents it from
 // advancing the stream beyond the current element and always advances the
 // stream to the end of the element when the handler returns (even if the

@@ 588,17 588,17 @@ func getID(start xml.StartElement) string {
 // SendElement transmits the first element read from the provided token reader
 // using start as the outermost tag in the encoding.
 //
-// If the element is an IQ stanza, Send blocks until a response is received and
-// then returns a reader from which it can be read.
+// If the element is an info/query (IQ) stanza, Send blocks until a response is
+// received and then returns a reader from which the response can be read.
+// If the input stream is not being processed (a call to Serve is not running),
+// SendElement may block forever.
 // If the provided context is closed before the response is received SendElement
-// immediately returns an error and any response received at a later time must
-// be handled separately.
+// immediately returns an error and any response received at a later time will
+// not be associated with the original request.
 // The response does not need to be consumed in its entirety, but it must be
 // closed before stream processing will resume.
 // If an error is returned, xml.TokenReader will be nil; the converse is not
 // necessarily true.
-// If the input stream is not being processed (a call to Serve is not running),
-// SendElement may block forever.
 //
 // SendElement is safe for concurrent use by multiple goroutines.
 func (s *Session) SendElement(ctx context.Context, r xml.TokenReader, start xml.StartElement) (xmlstream.TokenReadCloser, error) {