docs/conn: clarify ordering guarantees for bidirectional calls (#105)

Users can otherwise mistake transport ordering for application-level synchronization and attempt blocking calls from the synchronous read loop.

async.go

@@ -3,7 +3,8 @@ package jsonrpc2
 import "context"
 
 // AsyncHandler wraps a Handler such that each request is handled in its own
-// goroutine. It is a convenience wrapper.
+// goroutine. Handlers may therefore start or finish in a different order than
+// requests are received. It is a convenience wrapper.
 func AsyncHandler(h Handler) Handler {
 	return asyncHandler{h}
 }

conn.go

@@ -156,7 +156,9 @@ func (c *Conn) Notify(ctx context.Context, method string, params interface{}, op
 	return err
 }
 
-// Reply sends a successful response with a result.
+// Reply sends a successful response with a result. It returns after writing
+// the response to the ObjectStream; it does not wait for the peer to receive or
+// process the response.
 func (c *Conn) Reply(ctx context.Context, id ID, result interface{}) error {
 	resp := &Response{ID: id}
 	if err := resp.SetResult(result); err != nil {

jsonrpc2.go

@@ -59,10 +59,12 @@ const (
 
 // Handler handles JSON-RPC requests and notifications.
 type Handler interface {
-	// Handle is called to handle a request. No other requests are handled until
-	// it returns. If you do not require strict ordering behavior of received
-	// RPCs, it is suggested to wrap your handler in AsyncHandler. The context
-	// is automatically canceled when the connection closes.
+	// Handle is called to handle a request. While it is running, the connection
+	// does not process any other requests or responses. A handler that waits for
+	// a call's response must therefore run asynchronously. If you do not require
+	// strict ordering behavior of received RPCs, it is suggested to wrap your
+	// handler in AsyncHandler. The context is automatically canceled when the
+	// connection closes.
 	Handle(context.Context, *Conn, *Request)
 }