Update package documentation.

Clean up and simplify some language, remove filler words and fix a couple of
English syntax errors.

doc.go

@@ -15,8 +15,8 @@ The handler package helps adapt existing functions to this interface.
 A server finds the handler for a request by looking up its method name in a
 jrpc2.Assigner provided when the server is set up.
 
-For example, suppose we have defined the following Add function, and would like
-to export it as a JSON-RPC method:
+For example, suppose we would like to export the following Add function as a
+JSON-RPC method:
 
    // Add returns the sum of a slice of integers.
    func Add(ctx context.Context, values []int) int {
@@ -27,8 +27,8 @@ to export it as a JSON-RPC method:
       return sum
    }
 
-To convert Add to a jrpc2.Handler, call the handler.New function, which uses
-reflection to lift its argument into the jrpc2.Handler interface:
+To convert Add to a jrpc2.Handler, call handler.New, which uses reflection to
+lift its argument into the jrpc2.Handler interface:
 
    h := handler.New(Add)  // h is a jrpc2.Handler that invokes Add
 
@@ -43,27 +43,27 @@ Equipped with an Assigner we can now construct a Server:
 
    srv := jrpc2.NewServer(assigner, nil)  // nil for default options
 
-To serve requests, we will next need a channel.Channel. The channel package
-exports functions that can adapt various input and output streams.  For this
-example, we'll use a channel that delimits messages by newlines, and
-communicates on os.Stdin and os.Stdout:
+To serve requests, we need a channel.Channel. The channel package exports
+functions to adapt various input and output streams.  For this example, we'll
+use a channel that delimits messages by newlines, and communicates on os.Stdin
+and os.Stdout:
 
    ch := channel.Line(os.Stdin, os.Stdout)
    srv.Start(ch)
 
-Once started, the running server will handle incoming requests until the
-channel closes, or until it is stopped explicitly by calling srv.Stop(). To
-wait for the server to finish, call:
+Once started, the running server handles incoming requests until the channel
+closes, or until it is stopped explicitly by calling srv.Stop(). To wait for
+the server to finish, call:
 
    err := srv.Wait()
 
-This will report the error that led to the server exiting. A working
-implementation of this example can found in cmd/examples/adder/adder.go:
+This will report the error that led to the server exiting.  The code for this
+example is availabe from cmd/examples/adder/adder.go:
 
     $ go run cmd/examples/adder/adder.go
 
-You can interact with this server by typing JSON-RPC requests on stdin, such as
-for example:
+Interact with the server by sending JSON-RPC requests on stdin, such as for
+example:
 
    {"jsonrpc":"2.0", "id":1, "method":"Add", "params":[1, 3, 5, 7]}
 
@@ -75,7 +75,7 @@ server over a channel.Channel, and is safe for concurrent use by multiple
 goroutines. It supports batched requests and may have arbitrarily many pending
 requests in flight simultaneously.
 
-To establish a client we first need a channel:
+To create a client we need a channel:
 
    import "net"
 
@@ -88,21 +88,21 @@ To send a single RPC, use the Call method:
 
    rsp, err := cli.Call(ctx, "Add", []int{1, 3, 5, 7})
 
-This blocks until the response is received. Any error returned by the server,
+Call blocks until the response is received. Any error returned by the server,
 including cancellation or deadline exceeded, has concrete type *jrpc2.Error.
 
-To issue a batch of requests all at once, use the Batch method:
+To issue a batch of requests, use the Batch method:
 
    rsps, err := cli.Batch(ctx, []jrpc2.Spec{
       {Method: "Math.Add", Params: []int{1, 2, 3}},
       {Method: "Math.Mul", Params: []int{4, 5, 6}},
       {Method: "Math.Max", Params: []int{-1, 5, 3, 0, 1}},
    })
 
-The Batch method waits until all the responses are received.  An error from the
-Batch call reflects an error in sending the request: The caller must check each
-response separately for errors from the server. The responses will be returned
-in the same order as the Spec values, save that notifications are omitted.
+Batch blocks until all the responses are received.  An error from the Batch
+call reflects an error in sending the request: The caller must check each
+response separately for errors from the server. Responses are returned in the
+same order as the Spec values, save that notifications are omitted.
 
 To decode the result from a successful response use its UnmarshalResult method:
 
@@ -111,27 +111,26 @@ To decode the result from a successful response use its UnmarshalResult method:
       log.Fatalln("UnmarshalResult:", err)
    }
 
-To shut down a client and discard all its pending work, call cli.Close().
+To close a client and discard all its pending work, call cli.Close().
 
 
 Notifications
 
-The JSON-RPC protocol also supports a kind of request called a notification.
-Notifications differ from ordinary calls in that they are one-way: The client
-sends them to the server, but the server does not reply.
+The JSON-RPC protocol also supports notifications.  Notifications differ from
+calls in that they are one-way: The client sends them to the server, but the
+server does not reply.
 
-A jrpc2.Client supports sending notifications as follows:
+Use the Notify method of a jrpc2.Client to send notifications:
 
    err := cli.Notify(ctx, "Alert", handler.Obj{
       "message": "A fire is burning!",
    })
 
-Unlike ordinary requests, there are no responses for notifications; a
-notification is complete once it has been sent.
+A notification is complete once it has been sent.
 
-On the server side, notifications are identical to ordinary requests, save that
-their return value is discarded once the handler returns. If a handler does not
-want to do anything for a notification, it can query the request:
+On server, notifications are handled identically to ordinary requests, except
+that the return value is discarded once the handler returns. If a handler does
+not want to do anything for a notification, it can query the request:
 
    if req.IsNotification() {
       return 0, nil  // ignore notifications
@@ -140,23 +139,23 @@ want to do anything for a notification, it can query the request:
 
 Cancellation
 
-The *Client and *Server types support a non-standard cancellation protocol,
-that consists of a notification method "rpc.cancel" taking an array of request
-IDs to be cancelled. Upon receiving this notification, the server will cancel
-the context of each method handler whose ID is named.
+The *jrpc2.Client and *jrpc2.Server types support a non-standard cancellation
+protocol, consisting of a notification method "rpc.cancel" taking an array of
+request IDs to be cancelled. The server cancels the context of each method
+handler whose ID is named.
 
-When the context associated with a client request is cancelled, the client will
-send an "rpc.cancel" notification to the server for that request's ID.  The
-"rpc.cancel" method is automatically handled (unless disabled) by the *Server
-implementation from this package.
+When the context associated with a client request is cancelled, the client
+sends an "rpc.cancel" notification to the server for that request's ID.  The
+"rpc.cancel" method is automatically handled (unless disabled) by the
+*jrpc2.Server implementation from this package.
 
 
 Services with Multiple Methods
 
-The examples above show a server with only one method using handler.New; you
-will often want to expose more than one. The handler.NewService function
-supports this by applying New to all the exported methods of a concrete value
-to produce a handler.Map for those methods:
+The example above shows a server with one method using handler.New.  To
+simplify exporting multiple methods, the handler.NewService function applies
+handler.New to all the relevant exported methods of a concrete value, returning
+a handler.Map for those methods:
 
    type math struct{}
 
@@ -191,10 +190,10 @@ require a more complex hierarchy.
 Concurrency
 
 A Server processes requests concurrently, up to the Concurrency limit given in
-its ServerOptions. Two requests (calls or notifications) are concurrent if they
-arrive as part of the same batch. In addition, two calls are concurrent if the
-time intervals between the arrival of the request objects and delivery of the
-response objects overlap.
+its ServerOptions. Two requests (either calls or notifications) are concurrent
+if they arrive as part of the same batch. In addition, two calls are concurrent
+if the time intervals between the arrival of the request objects and delivery
+of the response objects overlap.
 
 The server may issue concurrent requests to their handlers in any order.
 Otherwise, requests are processed in order of arrival. Notifications, in
@@ -205,8 +204,8 @@ was fully processed before any subsequent calls are issued.
 
 Non-Standard Extension Methods
 
-By default a jrpc2.Server exports the following built-in non-standard extension
-methods:
+By default, a *jrpc2.Server exports the following built-in non-standard
+extension methods:
 
   rpc.serverInfo(null) ⇒ jrpc2.ServerInfo
   Returns a jrpc2.ServerInfo value giving server metrics.
@@ -223,11 +222,11 @@ the DisableBuiltin server option to true when constructing the server.
 
 Server Push
 
-The AllowPush option in jrpc2.ServerOptions enables the server to "push"
-requests back to the client. This is a non-standard extension of JSON-RPC used
-by some applications such as the Language Server Protocol (LSP). If this
-feature is enabled, the server's Notify and Callback methods send requests back
-to the client:
+The AllowPush option in jrpc2.ServerOptions allows a server to "push" requests
+back to the client. This is a non-standard extension of JSON-RPC used by some
+applications such as the Language Server Protocol (LSP). If this feature is
+enabled, the server's Notify and Callback methods send requests back to the
+client. Otherwise, those methods will report an error:
 
   if err := s.Notify(ctx, "methodName", params); err == jrpc2.ErrPushUnsupported {
     // server push is not enabled
@@ -237,9 +236,10 @@ to the client:
   }
 
 A method handler may use jrpc2.PushNotify and jrpc2.PushCall functions to
-access these methods.  On the client side, the OnNotify and OnCallback options
-in jrpc2.ClientOptions provide hooks to which any server requests are
-delivered, if they are set.
+access these methods from its context.
+
+On the client side, the OnNotify and OnCallback options in jrpc2.ClientOptions
+provide hooks to which any server requests are delivered, if they are set.
 */
 package jrpc2