all: update doc comments to add link tags

No functional changes.

base.go

@@ -10,7 +10,7 @@ import (
 	"strings"
 )
 
-// An Assigner maps method names to Handler functions.
+// An Assigner maps method names to [Handler] functions.
 type Assigner interface {
 	// Assign returns the handler for the named method, or returns nil to
 	// indicate that the method is not known.
@@ -20,8 +20,8 @@ type Assigner interface {
 	Assign(ctx context.Context, method string) Handler
 }
 
-// Namer is an optional interface that an Assigner may implement to expose the
-// names of its methods to the ServerInfo method.
+// Namer is an optional interface that an [Assigner] may implement to expose
+// the names of its methods to the ServerInfo method.
 type Namer interface {
 	// Names returns all known method names in lexicographic order.
 	Names() []string
@@ -33,8 +33,8 @@ type Namer interface {
 // of type *jrpc2.Error to control the response code sent back to the caller;
 // otherwise the server will wrap the resulting value.
 //
-// The context passed to the handler by a *jrpc2.Server includes two special
-// values that the handler may extract.
+// The context passed to the handler by a [Server] includes two special values
+// that the handler may extract.
 //
 // To obtain the server instance running the handler, write:
 //
@@ -75,10 +75,10 @@ func (r *Request) HasParams() bool { return len(r.params) != 0 }
 // By default, unknown object keys are ignored and discarded when unmarshaling
 // into a v of struct type. If the type of v implements a DisallowUnknownFields
 // method, unknown fields will instead generate an InvalidParams error.  The
-// jrpc2.StrictFields helper adapts existing struct values to this interface.
-// For more specific behaviour, implement a custom json.Unmarshaler.
+// [StrictFields] helper adapts existing struct values to this interface.  For
+// more specific behaviour, implement a custom [json.Unmarshaler].
 //
-// If v has type *json.RawMessage, unmarshaling will never report an error.
+// If v has type [*json.RawMessage], unmarshaling will never report an error.
 func (r *Request) UnmarshalParams(v any) error {
 	if len(r.params) == 0 {
 		return nil
@@ -134,11 +134,11 @@ func (r *Response) Error() *Error { return r.err }
 //
 // By default, unknown object keys are ignored and discarded when unmarshaling
 // into a v of struct type. If the type of v implements a DisallowUnknownFields
-// method, unknown fields will instead generate an error.  The
-// jrpc2.StrictFields helper adapts existing struct values to this interface.
-// For more specific behaviour, implement a custom json.Unmarshaler.
+// method, unknown fields will instead generate an error.  The [StrictFields]
+// helper adapts existing struct values to this interface.  For more specific
+// behaviour, implement a custom [json.Unmarshaler].
 //
-// If v has type *json.RawMessage, unmarshaling will never report an error.
+// If v has type [*json.RawMessage], unmarshaling will never report an error.
 func (r *Response) UnmarshalResult(v any) error {
 	if r.err != nil {
 		return r.err

channel/channel.go

@@ -2,9 +2,9 @@
 
 // Package channel defines a communications channel.
 //
-// A Channel encodes/transmits and decodes/receives data records. The types in
-// this package support sending and receiving over an unstructured stream using
-// a configurable framing discipline.
+// A [Channel] encodes/transmits and decodes/receives data records. The types
+// in this package support sending and receiving over an unstructured stream
+// using a configurable framing discipline.
 //
 // # Channels
 //
@@ -23,7 +23,7 @@
 //
 // # Framing
 //
-// A Framing function adapts a pair of io.Reader and io.WriteCloser to a
+// A [Framing] function adapts a pair of [io.Reader] and [io.WriteCloser] to a
 // Channel by imposing a particular message-framing discipline. This package
 // provides several framing implementations, for example:
 //

channel/hdr.go

@@ -12,8 +12,8 @@ import (
 	"strings"
 )
 
-// StrictHeader defines a Framing that transmits and receives messages using a
-// header prefix similar to HTTP, in which mimeType describes the content type.
+// StrictHeader defines a [Framing] that transmits and receives messages using
+// a header prefix similar to HTTP, in which mimeType describes the content type.
 //
 // Specifically, each message is sent in the format:
 //
@@ -54,7 +54,7 @@ func StrictHeader(mimeType string) Framing {
 	}
 }
 
-// A ContentTypeMismatchError is reported by the Recv method of a Header
+// A ContentTypeMismatchError is reported by the Recv method of a [Header]
 // framing when the content type of the message does not match the type
 // expected by the channel.
 type ContentTypeMismatchError struct {
@@ -90,10 +90,11 @@ func (h *hdr) Send(msg []byte) error {
 	return err
 }
 
-// Recv implements part of the Channel interface. If the content type of the
+// Recv implements part of the [Channel] interface. If the content type of the
 // received message does not match the expected value, Recv returns the decoded
-// message along with an error of concrete type *ContentTypeMismatchError.  The
-// caller may choose to ignore this error by testing explicitly for this type.
+// message along with an error of concrete type [*ContentTypeMismatchError].
+// The caller may choose to ignore this error by testing explicitly for this
+// type.
 func (h *hdr) Recv() ([]byte, error) {
 	var contentType, contentLength string
 	for {
@@ -149,10 +150,10 @@ func (h *hdr) Recv() ([]byte, error) {
 	return data[:size], contentErr
 }
 
-// Close implements part of the Channel interface.
+// Close implements part of the [Channel] interface.
 func (h *hdr) Close() error { return h.wc.Close() }
 
-// Header returns a framing that behaves as StrictHeader, but allows received
+// Header returns a framing that behaves as [StrictHeader], but allows received
 // messages to omit the Content-Type header without error. An error will still
 // be reported if a content-type is set but does not match.
 func Header(mimeType string) Framing {
@@ -174,8 +175,8 @@ func (o opthdr) Recv() ([]byte, error) {
 	return msg, err
 }
 
-// LSP is a header framing (see Header) that transmits and receives messages on
-// r and wc using the MIME type application/vscode-jsonrpc. This is the format
-// preferred by the Language Server Protocol (LSP), defined by
+// LSP is a header framing (see [Header]) that transmits and receives messages
+// on r and wc using the MIME type application/vscode-jsonrpc. This is the
+// format preferred by the Language Server Protocol (LSP), defined by
 // https://microsoft.github.io/language-server-protocol
 var LSP = Header("application/vscode-jsonrpc; charset=utf-8")

channel/json.go

@@ -28,7 +28,7 @@ type jsonc struct {
 	buf json.RawMessage
 }
 
-// Send implements part of the Channel interface.
+// Send implements part of the [Channel] interface.
 func (c jsonc) Send(msg []byte) error {
 	if len(msg) == 0 || isNull(msg) {
 		_, err := io.WriteString(c.wc, "null\n")
@@ -38,9 +38,9 @@ func (c jsonc) Send(msg []byte) error {
 	return err
 }
 
-// Recv implements part of the Channel interface. It reports an error if the
+// Recv implements part of the [Channel] interface. It reports an error if the
 // message is not a structurally valid JSON value. It is safe for the caller to
-// treat any record returned as a json.RawMessage.
+// treat any record returned as a [json.RawMessage].
 func (c jsonc) Recv() ([]byte, error) {
 	c.buf = c.buf[:0] // reset
 	if err := c.dec.Decode(&c.buf); err != nil {
@@ -51,7 +51,7 @@ func (c jsonc) Recv() ([]byte, error) {
 	return c.buf, nil
 }
 
-// Close implements part of the Channel interface.
+// Close implements part of the [Channel] interface.
 func (c jsonc) Close() error { return c.wc.Close() }
 
 func isNull(msg json.RawMessage) bool {

channel/split.go

@@ -30,7 +30,7 @@ type split struct {
 	buf   *bufio.Reader
 }
 
-// Send implements part of the Channel interface.  It reports an error if msg
+// Send implements part of the [Channel] interface.  It reports an error if msg
 // contains a split byte.
 func (c split) Send(msg []byte) error {
 	if bytes.IndexByte(msg, c.split) >= 0 {
@@ -41,7 +41,7 @@ func (c split) Send(msg []byte) error {
 	return err
 }
 
-// Recv implements part of the Channel interface.
+// Recv implements part of the [Channel] interface.
 func (c split) Recv() ([]byte, error) {
 	var buf bytes.Buffer
 	for {
@@ -58,5 +58,5 @@ func (c split) Recv() ([]byte, error) {
 	}
 }
 
-// Close implements part of the Channel interface.
+// Close implements part of the [Channel] interface.
 func (c split) Close() error { return c.wc.Close() }

client.go

@@ -14,7 +14,7 @@ import (
 )
 
 // A Client is a JSON-RPC 2.0 client. The client sends requests and receives
-// responses on a channel.Channel provided by the constructor.
+// responses on a [channel.Channel] provided by the constructor.
 type Client struct {
 	done *sync.WaitGroup // done when the reader is finished at shutdown time
 
@@ -289,7 +289,7 @@ func (c *Client) waitComplete(pctx context.Context, id string, p *Response) {
 
 // Call initiates a single request and blocks until the response returns or ctx
 // ends.  A successful call reports a nil error and a non-nil response. Errors
-// from the server have concrete type *jrpc2.Error.
+// from the server have concrete type [*Error].
 //
 //	rsp, err := c.Call(ctx, method, params)
 //	if e, ok := err.(*jrpc2.Error); ok {

code.go

@@ -48,9 +48,9 @@ func (c codeError) Is(err error) bool {
 	return ok && v.ErrCode() == Code(c)
 }
 
-// Err converts c to an error value, which is nil for NoError and otherwise an
-// error value whose code is c and whose text is based on the built-in string
-// for c if one exists.
+// Err converts c to an error value, which is nil for [NoError] and otherwise
+// an error value whose code is c and whose text is based on the built-in
+// string for c if one exists.
 func (c Code) Err() error {
 	if c == NoError {
 		return nil

ctx.go

@@ -8,7 +8,7 @@ import (
 
 // InboundRequest returns the inbound request associated with the context
 // passed to a Handler, or nil if ctx does not have an inbound request.
-// A *jrpc2.Server populates this value for handler contexts.
+// A [Server] populates this value for handler contexts.
 //
 // This is mainly useful to wrapped server methods that do not have the request
 // as an explicit parameter; for direct implementations of the Handler type the
@@ -24,19 +24,19 @@ func InboundRequest(ctx context.Context) *Request {
 type inboundRequestKey struct{}
 
 // ServerFromContext returns the server associated with the context passed to a
-// Handler by a *jrpc2.Server.  It will panic for a non-handler context.
+// [Handler] by a [Server].  It will panic for a non-handler context.
 //
 // It is safe to retain the server and invoke its methods beyond the lifetime
 // of the context from which it was extracted; however, a handler must not
-// block on the Wait or WaitStatus methods of the server, as the server will
-// deadlock waiting for the handler to return.
+// block on the [Server.Wait] or [Server.WaitStatus] methods, as the server
+// will deadlock waiting for the handler to return.
 func ServerFromContext(ctx context.Context) *Server { return ctx.Value(serverKey{}).(*Server) }
 
 type serverKey struct{}
 
 // ClientFromContext returns the client associated with the given context.
-// This will be populated on the context passed by a *jrpc2.Client to a
-// client-side callback handler.
+// This will be populated on the context passed by a [Client] to a client-side
+// callback handler.
 //
 // A callback handler MUST NOT close the client, as the close will deadlock
 // waiting for the callback to return.

doc.go

@@ -6,15 +6,15 @@ defined by http://www.jsonrpc.org/specification.
 
 # Servers
 
-The *Server type implements a JSON-RPC server. A server communicates with a
-client over a channel.Channel, and dispatches client requests to user-defined
+The [*Server] type implements a JSON-RPC server. A server communicates with a
+client over a [channel.Channel], and dispatches client requests to user-defined
 method handlers.  Method handlers are functions with this signature:
 
 	func(ctx Context.Context, req *jrpc2.Request) (any, error)
 
-A server finds the handler for a request by looking up its method name in a
-jrpc2.Assigner.  A Handler decodes request parameters using the UnmarshalParams
-method on the Request:
+A server finds the handler for a request by looking up its method name in an
+[Assigner].  A [Handler] decodes request parameters using the UnmarshalParams
+method on the [Request]:
 
 	func Handle(ctx context.Context, req *jrpc2.Request) (any, error) {
 	   var args ArgType
@@ -24,8 +24,8 @@ method on the Request:
 	   return usefulStuffWith(args)
 	}
 
-The handler package uses reflection to adapt functions that do not have this
-type to handlers.  For example, given:
+The [github.com/creachadair/jrpc2/handler] package uses reflection to adapt
+functions that do not have this type to handlers.  For example, given:
 
 	// Add returns the sum of a slice of integers.
 	func Add(ctx context.Context, values []int) int {
@@ -47,14 +47,14 @@ interface with a Go map. To advertise this function under the name "Add":
 	   "Add": handler.New(Add),
 	}
 
-Equipped with an Assigner we can now construct a Server:
+Equipped with an Assigner we can now construct a [Server]:
 
 	srv := jrpc2.NewServer(assigner, nil)  // nil for default options
 
-To start the server, we need a channel.Channel. Implementations of the Channel
-interface handle the framing, transmission, and receipt of JSON messages.  The
-channel package implements some common framing disciplines for byte streams
-like pipes and sockets.
+To start the server, we need a [channel.Channel]. Implementations of the
+Channel interface handle the framing, transmission, and receipt of JSON
+messages.  The channel package implements some common framing disciplines for
+byte streams like pipes and sockets.
 
 For this example, we'll use a channel that communicates over stdin and stdout,
 with messages delimited by newlines:
@@ -83,8 +83,8 @@ example:
 
 # Clients
 
-The *Client type implements a JSON-RPC client. A client communicates with a
-server over a channel.Channel, and is safe for concurrent use by multiple
+The [*Client] type implements a JSON-RPC client. A client communicates with a
+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.
 
@@ -102,7 +102,7 @@ To send a single RPC, use the Call method:
 	rsp, err := cli.Call(ctx, "Math.Add", []int{1, 3, 5, 7})
 
 Call blocks until the response is received. Errors returned by the server have
-concrete type *jrpc2.Error.
+concrete type [*Error].
 
 To issue a batch of concurrent requests, use the Batch method:
 
@@ -115,7 +115,7 @@ To issue a batch of concurrent requests, use the Batch method:
 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.
+same order as the [Spec] values, save that notifications are omitted.
 
 To decode the result from a successful response, use its UnmarshalResult method:
 
@@ -155,15 +155,15 @@ want to do anything for a notification, it can query the request:
 
 # Services with Multiple Methods
 
-The example above shows a server with one method.  A handler.Map works for any
-number of distinctly-named methods:
+The example above shows a server with one method.  A [handler.Map] works for
+any number of distinctly-named methods:
 
 	mathService := handler.Map{
 	   "Add": handler.New(Add),
 	   "Mul": handler.New(Mul),
 	}
 
-Maps may be combined with the handler.ServiceMap type to export multiple
+Maps may be combined with the [handler.ServiceMap] type to export multiple
 services from the same server:
 
 	func getStatus(context.Context) string { return "all is well" }
@@ -182,7 +182,7 @@ require a more complex hierarchy.
 
 # Concurrency
 
-A Server issues concurrent requests to handlers in parallel, up to the limit
+A [Server] issues concurrent requests to handlers in parallel, up to the limit
 given by the Concurrency field in ServerOptions.
 
 Two requests (either calls or notifications) are concurrent if they arrive as
@@ -227,7 +227,7 @@ Otherwise, those methods will report an error:
 	  // server push is not enabled
 	}
 
-A method handler may use jrpc2.ServerFromContext to access the server from its
+A method handler may use [ServerFromContext] to access the server from its
 context, and then invoke these methods on it.  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.
@@ -238,7 +238,7 @@ a client response that will never arrive.
 
 # Contexts and Cancellation
 
-Both the Server and the Client use the standard context package to plumb
+Both the [Server] and the [Client] use the standard context package to plumb
 cancellation and other request-specific metadata in handlers and calls.
 
 On the server, the context passed to a handler is automatically cancelled when
@@ -255,7 +255,7 @@ server, as JSON-RPC does not define a standard mechanism to do so.  One typical
 approach (used by LSP, for example) is to define a separate method on the
 server to handle cancellation requests.
 
-If an OnCancel hook is set in the ClientOptions, the client calls it when the
+If an OnCancel hook is set in the [ClientOptions], the client calls it when the
 context for a Call ends before the server has responded.  This can be used to
 forward cancellation to the server separately.
 */