encoding: modernize Go documentation

Across all encoding packages, linkify declarations if possible.
In some cases, we convert a code block into a bulleted list,
which then further allows for more linkification.

Change-Id: I68fedf362615b34228bab5d4859b7d87d831c570
Reviewed-on: https://go-review.googlesource.com/c/go/+/524977
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Daniel Martí <mvdan@mvdan.cc>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: qiulaidongfeng <2645477756@qq.com>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>

3 files changed, 41 insertions, 41 deletions

diff --git a/src/encoding/xml/marshal.go b/src/encoding/xml/marshal.go
index 5cf12f0888..c2931a534b 100644
--- a/src/encoding/xml/marshal.go
+++ b/src/encoding/xml/marshal.go
@@ -17,7 +17,7 @@ import (
 )
 
 const (
-	// Header is a generic XML header suitable for use with the output of Marshal.
+	// Header is a generic XML header suitable for use with the output of [Marshal].
 	// This is not automatically added to any output of this package,
 	// it is provided as a convenience.
 	Header = `<?xml version="1.0" encoding="UTF-8"?>` + "\n"
@@ -34,7 +34,7 @@ const (
 //
 // The name for the XML elements is taken from, in order of preference:
 //   - the tag on the XMLName field, if the data is a struct
-//   - the value of the XMLName field of type Name
+//   - the value of the XMLName field of type [Name]
 //   - the tag of the struct field used to obtain the data
 //   - the name of the struct field used to obtain the data
 //   - the name of the marshaled type
@@ -62,9 +62,9 @@ const (
 //     string of length zero.
 //   - an anonymous struct field is handled as if the fields of its
 //     value were part of the outer struct.
-//   - a field implementing Marshaler is written by calling its MarshalXML
+//   - a field implementing [Marshaler] is written by calling its MarshalXML
 //     method.
-//   - a field implementing encoding.TextMarshaler is written by encoding the
+//   - a field implementing [encoding.TextMarshaler] is written by encoding the
 //     result of its MarshalText method as text.
 //
 // If a field uses a tag "a>b>c", then the element c will be nested inside
@@ -74,7 +74,7 @@ const (
 // If the XML name for a struct field is defined by both the field tag and the
 // struct's XMLName field, the names must match.
 //
-// See MarshalIndent for an example.
+// See [MarshalIndent] for an example.
 //
 // Marshal will return an error if asked to marshal a channel, function, or map.
 func Marshal(v any) ([]byte, error) {
@@ -96,7 +96,7 @@ func Marshal(v any) ([]byte, error) {
 // By convention, arrays or slices are typically encoded as a sequence
 // of elements, one per entry.
 // Using start as the element tag is not required, but doing so
-// will enable Unmarshal to match the XML elements to the correct
+// will enable [Unmarshal] to match the XML elements to the correct
 // struct field.
 // One common implementation strategy is to construct a separate
 // value with a layout corresponding to the desired XML and then
@@ -114,9 +114,9 @@ type Marshaler interface {
 //
 // MarshalXMLAttr returns an XML attribute with the encoded value of the receiver.
 // Using name as the attribute name is not required, but doing so
-// will enable Unmarshal to match the attribute to the correct
+// will enable [Unmarshal] to match the attribute to the correct
 // struct field.
-// If MarshalXMLAttr returns the zero attribute Attr{}, no attribute
+// If MarshalXMLAttr returns the zero attribute [Attr]{}, no attribute
 // will be generated in the output.
 // MarshalXMLAttr is used only for struct fields with the
 // "attr" option in the field tag.
@@ -124,7 +124,7 @@ type MarshalerAttr interface {
 	MarshalXMLAttr(name Name) (Attr, error)
 }
 
-// MarshalIndent works like Marshal, but each XML element begins on a new
+// MarshalIndent works like [Marshal], but each XML element begins on a new
 // indented line that starts with prefix and is followed by one or more
 // copies of indent according to the nesting depth.
 func MarshalIndent(v any, prefix, indent string) ([]byte, error) {
@@ -162,10 +162,10 @@ func (enc *Encoder) Indent(prefix, indent string) {
 
 // Encode writes the XML encoding of v to the stream.
 //
-// See the documentation for Marshal for details about the conversion
+// See the documentation for [Marshal] for details about the conversion
 // of Go values to XML.
 //
-// Encode calls Flush before returning.
+// Encode calls [Encoder.Flush] before returning.
 func (enc *Encoder) Encode(v any) error {
 	err := enc.p.marshalValue(reflect.ValueOf(v), nil, nil)
 	if err != nil {
@@ -177,10 +177,10 @@ func (enc *Encoder) Encode(v any) error {
 // EncodeElement writes the XML encoding of v to the stream,
 // using start as the outermost tag in the encoding.
 //
-// See the documentation for Marshal for details about the conversion
+// See the documentation for [Marshal] for details about the conversion
 // of Go values to XML.
 //
-// EncodeElement calls Flush before returning.
+// EncodeElement calls [Encoder.Flush] before returning.
 func (enc *Encoder) EncodeElement(v any, start StartElement) error {
 	err := enc.p.marshalValue(reflect.ValueOf(v), nil, &start)
 	if err != nil {
@@ -196,16 +196,16 @@ var (
 )
 
 // EncodeToken writes the given XML token to the stream.
-// It returns an error if StartElement and EndElement tokens are not properly matched.
+// It returns an error if [StartElement] and [EndElement] tokens are not properly matched.
 //
-// EncodeToken does not call Flush, because usually it is part of a larger operation
-// such as Encode or EncodeElement (or a custom Marshaler's MarshalXML invoked
+// EncodeToken does not call [Encoder.Flush], because usually it is part of a larger operation
+// such as [Encoder.Encode] or [Encoder.EncodeElement] (or a custom [Marshaler]'s MarshalXML invoked
 // during those), and those will call Flush when finished.
 // Callers that create an Encoder and then invoke EncodeToken directly, without
 // using Encode or EncodeElement, need to call Flush when finished to ensure
 // that the XML is written to the underlying writer.
 //
-// EncodeToken allows writing a ProcInst with Target set to "xml" only as the first token
+// EncodeToken allows writing a [ProcInst] with Target set to "xml" only as the first token
 // in the stream.
 func (enc *Encoder) EncodeToken(t Token) error {
 
@@ -303,7 +303,7 @@ func isValidDirective(dir Directive) bool {
 }
 
 // Flush flushes any buffered XML to the underlying writer.
-// See the EncodeToken documentation for details about when it is necessary.
+// See the [Encoder.EncodeToken] documentation for details about when it is necessary.
 func (enc *Encoder) Flush() error {
 	return enc.p.w.Flush()
 }
@@ -1106,7 +1106,7 @@ func (s *parentStack) push(parents []string) error {
 	return nil
 }
 
-// UnsupportedTypeError is returned when Marshal encounters a type
+// UnsupportedTypeError is returned when [Marshal] encounters a type
 // that cannot be converted into XML.
 type UnsupportedTypeError struct {
 	Type reflect.Type
diff --git a/src/encoding/xml/read.go b/src/encoding/xml/read.go
index e3f9a587dd..3cc4968c76 100644
--- a/src/encoding/xml/read.go
+++ b/src/encoding/xml/read.go
@@ -19,7 +19,7 @@ import (
 // an XML element is an order-dependent collection of anonymous
 // values, while a data structure is an order-independent collection
 // of named values.
-// See package json for a textual representation more suitable
+// See [encoding/json] for a textual representation more suitable
 // to data structures.
 
 // Unmarshal parses the XML-encoded data and stores the result in
@@ -96,7 +96,7 @@ import (
 // If Unmarshal encounters a field type that implements the Unmarshaler
 // interface, Unmarshal calls its UnmarshalXML method to produce the value from
 // the XML element.  Otherwise, if the value implements
-// encoding.TextUnmarshaler, Unmarshal calls that value's UnmarshalText method.
+// [encoding.TextUnmarshaler], Unmarshal calls that value's UnmarshalText method.
 //
 // Unmarshal maps an XML element to a string or []byte by saving the
 // concatenation of that element's character data in the string or
@@ -105,7 +105,7 @@ import (
 // Unmarshal maps an attribute value to a string or []byte by saving
 // the value in the string or slice.
 //
-// Unmarshal maps an attribute value to an Attr by saving the attribute,
+// Unmarshal maps an attribute value to an [Attr] by saving the attribute,
 // including its name, in the Attr.
 //
 // Unmarshal maps an XML element or attribute value to a slice by
@@ -134,16 +134,16 @@ func Unmarshal(data []byte, v any) error {
 	return NewDecoder(bytes.NewReader(data)).Decode(v)
 }
 
-// Decode works like Unmarshal, except it reads the decoder
+// Decode works like [Unmarshal], except it reads the decoder
 // stream to find the start element.
 func (d *Decoder) Decode(v any) error {
 	return d.DecodeElement(v, nil)
 }
 
-// DecodeElement works like Unmarshal except that it takes
+// DecodeElement works like [Unmarshal] except that it takes
 // a pointer to the start XML element to decode into v.
 // It is useful when a client reads some raw XML tokens itself
-// but also wants to defer to Unmarshal for some elements.
+// but also wants to defer to [Unmarshal] for some elements.
 func (d *Decoder) DecodeElement(v any, start *StartElement) error {
 	val := reflect.ValueOf(v)
 	if val.Kind() != reflect.Pointer {
@@ -184,7 +184,7 @@ type Unmarshaler interface {
 // an XML attribute description of themselves.
 //
 // UnmarshalXMLAttr decodes a single XML attribute.
-// If it returns an error, the outer call to Unmarshal stops and
+// If it returns an error, the outer call to [Unmarshal] stops and
 // returns that error.
 // UnmarshalXMLAttr is used only for struct fields with the
 // "attr" option in the field tag.
diff --git a/src/encoding/xml/xml.go b/src/encoding/xml/xml.go
index d121986944..73eedad290 100644
--- a/src/encoding/xml/xml.go
+++ b/src/encoding/xml/xml.go
@@ -34,7 +34,7 @@ func (e *SyntaxError) Error() string {
 
 // A Name represents an XML name (Local) annotated
 // with a name space identifier (Space).
-// In tokens returned by Decoder.Token, the Space identifier
+// In tokens returned by [Decoder.Token], the Space identifier
 // is given as a canonical URL, not the short prefix used
 // in the document being parsed.
 type Name struct {
@@ -48,7 +48,7 @@ type Attr struct {
 }
 
 // A Token is an interface holding one of the token types:
-// StartElement, EndElement, CharData, Comment, ProcInst, or Directive.
+// [StartElement], [EndElement], [CharData], [Comment], [ProcInst], or [Directive].
 type Token any
 
 // A StartElement represents an XML start element.
@@ -127,14 +127,14 @@ func CopyToken(t Token) Token {
 }
 
 // A TokenReader is anything that can decode a stream of XML tokens, including a
-// Decoder.
+// [Decoder].
 //
 // When Token encounters an error or end-of-file condition after successfully
 // reading a token, it returns the token. It may return the (non-nil) error from
 // the same call or return the error (and a nil token) from a subsequent call.
 // An instance of this general case is that a TokenReader returning a non-nil
 // token at the end of the token stream may return either io.EOF or a nil error.
-// The next Read should return nil, io.EOF.
+// The next Read should return nil, [io.EOF].
 //
 // Implementations of Token are discouraged from returning a nil token with a
 // nil error. Callers should treat a return of nil, nil as indicating that
@@ -216,7 +216,7 @@ type Decoder struct {
 }
 
 // NewDecoder creates a new XML parser reading from r.
-// If r does not implement io.ByteReader, NewDecoder will
+// If r does not implement [io.ByteReader], NewDecoder will
 // do its own buffering.
 func NewDecoder(r io.Reader) *Decoder {
 	d := &Decoder{
@@ -246,28 +246,28 @@ func NewTokenDecoder(t TokenReader) *Decoder {
 }
 
 // Token returns the next XML token in the input stream.
-// At the end of the input stream, Token returns nil, io.EOF.
+// At the end of the input stream, Token returns nil, [io.EOF].
 //
 // Slices of bytes in the returned token data refer to the
 // parser's internal buffer and remain valid only until the next
-// call to Token. To acquire a copy of the bytes, call CopyToken
+// call to Token. To acquire a copy of the bytes, call [CopyToken]
 // or the token's Copy method.
 //
 // Token expands self-closing elements such as <br>
 // into separate start and end elements returned by successive calls.
 //
-// Token guarantees that the StartElement and EndElement
+// Token guarantees that the [StartElement] and [EndElement]
 // tokens it returns are properly nested and matched:
 // if Token encounters an unexpected end element
 // or EOF before all expected end elements,
 // it will return an error.
 //
-// If CharsetReader is called and returns an error,
+// If [Decoder.CharsetReader] is called and returns an error,
 // the error is wrapped and returned.
 //
 // Token implements XML name spaces as described by
 // https://www.w3.org/TR/REC-xml-names/. Each of the
-// Name structures contained in the Token has the Space
+// [Name] structures contained in the Token has the Space
 // set to the URL identifying its name space when known.
 // If Token encounters an unrecognized name space prefix,
 // it uses the prefix as the Space rather than report an error.
@@ -534,7 +534,7 @@ func (d *Decoder) autoClose(t Token) (Token, bool) {
 
 var errRawToken = errors.New("xml: cannot use RawToken from UnmarshalXML method")
 
-// RawToken is like Token but does not verify that
+// RawToken is like [Decoder.Token] but does not verify that
 // start and end elements match and does not translate
 // name space prefixes to their corresponding URLs.
 func (d *Decoder) RawToken() (Token, error) {
@@ -1596,7 +1596,7 @@ var second = &unicode.RangeTable{
 // HTMLEntity is an entity map containing translations for the
 // standard HTML entity characters.
 //
-// See the Decoder.Strict and Decoder.Entity fields' documentation.
+// See the [Decoder.Strict] and [Decoder.Entity] fields' documentation.
 var HTMLEntity map[string]string = htmlEntity
 
 var htmlEntity = map[string]string{
@@ -1865,7 +1865,7 @@ var htmlEntity = map[string]string{
 // HTMLAutoClose is the set of HTML elements that
 // should be considered to close automatically.
 //
-// See the Decoder.Strict and Decoder.Entity fields' documentation.
+// See the [Decoder.Strict] and [Decoder.Entity] fields' documentation.
 var HTMLAutoClose []string = htmlAutoClose
 
 var htmlAutoClose = []string{
@@ -1993,9 +1993,9 @@ func (p *printer) EscapeString(s string) {
 	p.WriteString(s[last:])
 }
 
-// Escape is like EscapeText but omits the error return value.
+// Escape is like [EscapeText] but omits the error return value.
 // It is provided for backwards compatibility with Go 1.0.
-// Code targeting Go 1.1 or later should use EscapeText.
+// Code targeting Go 1.1 or later should use [EscapeText].
 func Escape(w io.Writer, s []byte) {
 	EscapeText(w, s)
 }