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 <[email protected]>
Reviewed-by: Daniel Martí <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
Reviewed-by: qiulaidongfeng <[email protected]>
Reviewed-by: Matthew Dempsky <[email protected]>

Author: dsnet

src/encoding/ascii85/ascii85.go

@@ -15,12 +15,12 @@ import (
  * Encoder
  */
 
-// Encode encodes src into at most MaxEncodedLen(len(src))
+// Encode encodes src into at most [MaxEncodedLen](len(src))
 // bytes of dst, returning the actual number of bytes written.
 //
 // The encoding handles 4-byte chunks, using a special encoding
 // for the last fragment, so Encode is not appropriate for use on
-// individual blocks of a large data stream. Use NewEncoder() instead.
+// individual blocks of a large data stream. Use [NewEncoder] instead.
 //
 // Often, ascii85-encoded data is wrapped in <~ and ~> symbols.
 // Encode does not add these.
@@ -173,7 +173,7 @@ func (e CorruptInputError) Error() string {
 // Decode decodes src into dst, returning both the number
 // of bytes written to dst and the number consumed from src.
 // If src contains invalid ascii85 data, Decode will return the
-// number of bytes successfully written and a CorruptInputError.
+// number of bytes successfully written and a [CorruptInputError].
 // Decode ignores space and control characters in src.
 // Often, ascii85-encoded data is wrapped in <~ and ~> symbols.
 // Decode expects these to have been stripped by the caller.
@@ -182,7 +182,7 @@ func (e CorruptInputError) Error() string {
 // end of the input stream and processes it completely rather
 // than wait for the completion of another 32-bit block.
 //
-// NewDecoder wraps an io.Reader interface around Decode.
+// [NewDecoder] wraps an [io.Reader] interface around Decode.
 func Decode(dst, src []byte, flush bool) (ndst, nsrc int, err error) {
 	var v uint32
 	var nb int

src/encoding/asn1/asn1.go

@@ -211,7 +211,7 @@ func parseBitString(bytes []byte) (ret BitString, err error) {
 
 // NULL
 
-// NullRawValue is a RawValue with its Tag set to the ASN.1 NULL type tag (5).
+// NullRawValue is a [RawValue] with its Tag set to the ASN.1 NULL type tag (5).
 var NullRawValue = RawValue{Tag: TagNull}
 
 // NullBytes contains bytes representing the DER-encoded ASN.1 NULL type.
@@ -1031,34 +1031,33 @@ func setDefaultValue(v reflect.Value, params fieldParameters) (ok bool) {
 // fields in val will not be included in rest, as these are considered
 // valid elements of the SEQUENCE and not trailing data.
 //
-// An ASN.1 INTEGER can be written to an int, int32, int64,
-// or *big.Int (from the math/big package).
-// If the encoded value does not fit in the Go type,
-// Unmarshal returns a parse error.
+//   - An ASN.1 INTEGER can be written to an int, int32, int64,
+//     or *[big.Int].
+//     If the encoded value does not fit in the Go type,
+//     Unmarshal returns a parse error.
 //
-// An ASN.1 BIT STRING can be written to a BitString.
+//   - An ASN.1 BIT STRING can be written to a [BitString].
 //
-// An ASN.1 OCTET STRING can be written to a []byte.
+//   - An ASN.1 OCTET STRING can be written to a []byte.
 //
-// An ASN.1 OBJECT IDENTIFIER can be written to an
-// ObjectIdentifier.
+//   - An ASN.1 OBJECT IDENTIFIER can be written to an [ObjectIdentifier].
 //
-// An ASN.1 ENUMERATED can be written to an Enumerated.
+//   - An ASN.1 ENUMERATED can be written to an [Enumerated].
 //
-// An ASN.1 UTCTIME or GENERALIZEDTIME can be written to a time.Time.
+//   - An ASN.1 UTCTIME or GENERALIZEDTIME can be written to a [time.Time].
 //
-// An ASN.1 PrintableString, IA5String, or NumericString can be written to a string.
+//   - An ASN.1 PrintableString, IA5String, or NumericString can be written to a string.
 //
-// Any of the above ASN.1 values can be written to an interface{}.
-// The value stored in the interface has the corresponding Go type.
-// For integers, that type is int64.
+//   - Any of the above ASN.1 values can be written to an interface{}.
+//     The value stored in the interface has the corresponding Go type.
+//     For integers, that type is int64.
 //
-// An ASN.1 SEQUENCE OF x or SET OF x can be written
-// to a slice if an x can be written to the slice's element type.
+//   - An ASN.1 SEQUENCE OF x or SET OF x can be written
+//     to a slice if an x can be written to the slice's element type.
 //
-// An ASN.1 SEQUENCE or SET can be written to a struct
-// if each of the elements in the sequence can be
-// written to the corresponding element in the struct.
+//   - An ASN.1 SEQUENCE or SET can be written to a struct
+//     if each of the elements in the sequence can be
+//     written to the corresponding element in the struct.
 //
 // The following tags on struct fields have special meaning to Unmarshal:
 //

src/encoding/asn1/marshal.go

@@ -721,7 +721,7 @@ func makeField(v reflect.Value, params fieldParameters) (e encoder, err error) {
 
 // Marshal returns the ASN.1 encoding of val.
 //
-// In addition to the struct tags recognised by Unmarshal, the following can be
+// In addition to the struct tags recognized by Unmarshal, the following can be
 // used:
 //
 //	ia5:         causes strings to be marshaled as ASN.1, IA5String values

src/encoding/base32/base32.go

@@ -57,7 +57,7 @@ const (
 // The alphabet is treated as a sequence of byte values
 // without any special treatment for multi-byte UTF-8.
 // The resulting Encoding uses the default padding character ('='),
-// which may be changed or disabled via WithPadding.
+// which may be changed or disabled via [Encoding.WithPadding].
 func NewEncoding(encoder string) *Encoding {
 	if len(encoder) != 32 {
 		panic("encoding alphabet is not 32-bytes long")
@@ -112,12 +112,12 @@ func (enc Encoding) WithPadding(padding rune) *Encoding {
  * Encoder
  */
 
-// Encode encodes src using the encoding enc, writing
-// EncodedLen(len(src)) bytes to dst.
+// Encode encodes src using the encoding enc,
+// writing [Encoding.EncodedLen](len(src)) bytes to dst.
 //
 // The encoding pads the output to a multiple of 8 bytes,
 // so Encode is not appropriate for use on individual blocks
-// of a large data stream. Use NewEncoder() instead.
+// of a large data stream. Use [NewEncoder] instead.
 func (enc *Encoding) Encode(dst, src []byte) {
 	if len(src) == 0 {
 		return
@@ -386,10 +386,10 @@ func (enc *Encoding) decode(dst, src []byte) (n int, end bool, err error) {
 }
 
 // Decode decodes src using the encoding enc. It writes at most
-// DecodedLen(len(src)) bytes to dst and returns the number of bytes
+// [Encoding.DecodedLen](len(src)) bytes to dst and returns the number of bytes
 // written. If src contains invalid base32 data, it will return the
-// number of bytes successfully written and CorruptInputError.
-// New line characters (\r and \n) are ignored.
+// number of bytes successfully written and [CorruptInputError].
+// Newline characters (\r and \n) are ignored.
 func (enc *Encoding) Decode(dst, src []byte) (n int, err error) {
 	buf := make([]byte, len(src))
 	l := stripNewlines(buf, src)

src/encoding/base64/base64.go

@@ -60,7 +60,7 @@ const (
 // The alphabet is treated as a sequence of byte values
 // without any special treatment for multi-byte UTF-8.
 // The resulting Encoding uses the default padding character ('='),
-// which may be changed or disabled via WithPadding.
+// which may be changed or disabled via [Encoding.WithPadding].
 func NewEncoding(encoder string) *Encoding {
 	if len(encoder) != 64 {
 		panic("encoding alphabet is not 64-bytes long")
@@ -87,7 +87,7 @@ func NewEncoding(encoder string) *Encoding {
 }
 
 // WithPadding creates a new encoding identical to enc except
-// with a specified padding character, or NoPadding to disable padding.
+// with a specified padding character, or [NoPadding] to disable padding.
 // The padding character must not be '\r' or '\n',
 // must not be contained in the encoding's alphabet,
 // must not be negative, and must be a rune equal or below '\xff'.
@@ -124,24 +124,24 @@ var URLEncoding = NewEncoding("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvw
 
 // RawStdEncoding is the standard raw, unpadded base64 encoding,
 // as defined in RFC 4648 section 3.2.
-// This is the same as StdEncoding but omits padding characters.
+// This is the same as [StdEncoding] but omits padding characters.
 var RawStdEncoding = StdEncoding.WithPadding(NoPadding)
 
 // RawURLEncoding is the unpadded alternate base64 encoding defined in RFC 4648.
 // It is typically used in URLs and file names.
-// This is the same as URLEncoding but omits padding characters.
+// This is the same as [URLEncoding] but omits padding characters.
 var RawURLEncoding = URLEncoding.WithPadding(NoPadding)
 
 /*
  * Encoder
  */
 
-// Encode encodes src using the encoding enc, writing
-// EncodedLen(len(src)) bytes to dst.
+// Encode encodes src using the encoding enc,
+// writing [Encoding.EncodedLen](len(src)) bytes to dst.
 //
 // The encoding pads the output to a multiple of 4 bytes,
 // so Encode is not appropriate for use on individual blocks
-// of a large data stream. Use NewEncoder() instead.
+// of a large data stream. Use [NewEncoder] instead.
 func (enc *Encoding) Encode(dst, src []byte) {
 	if len(src) == 0 {
 		return
@@ -507,9 +507,9 @@ func (d *decoder) Read(p []byte) (n int, err error) {
 }
 
 // Decode decodes src using the encoding enc. It writes at most
-// DecodedLen(len(src)) bytes to dst and returns the number of bytes
+// [Encoding.DecodedLen](len(src)) bytes to dst and returns the number of bytes
 // written. If src contains invalid base64 data, it will return the
-// number of bytes successfully written and CorruptInputError.
+// number of bytes successfully written and [CorruptInputError].
 // New line characters (\r and \n) are ignored.
 func (enc *Encoding) Decode(dst, src []byte) (n int, err error) {
 	if len(src) == 0 {

src/encoding/binary/binary.go

@@ -17,8 +17,8 @@
 //
 // This package favors simplicity over efficiency. Clients that require
 // high-performance serialization, especially for large data structures,
-// should look at more advanced solutions such as the encoding/gob
-// package or protocol buffers.
+// should look at more advanced solutions such as the [encoding/gob]
+// package or [google.golang.org/protobuf] for protocol buffers.
 package binary
 
 import (
@@ -31,6 +31,8 @@ import (
 
 // A ByteOrder specifies how to convert byte slices into
 // 16-, 32-, or 64-bit unsigned integers.
+//
+// It is implemented by [LittleEndian], [BigEndian], and [NativeEndian].
 type ByteOrder interface {
 	Uint16([]byte) uint16
 	Uint32([]byte) uint32
@@ -43,17 +45,19 @@ type ByteOrder interface {
 
 // AppendByteOrder specifies how to append 16-, 32-, or 64-bit unsigned integers
 // into a byte slice.
+//
+// It is implemented by [LittleEndian], [BigEndian], and [NativeEndian].
 type AppendByteOrder interface {
 	AppendUint16([]byte, uint16) []byte
 	AppendUint32([]byte, uint32) []byte
 	AppendUint64([]byte, uint64) []byte
 	String() string
 }
 
-// LittleEndian is the little-endian implementation of ByteOrder and AppendByteOrder.
+// LittleEndian is the little-endian implementation of [ByteOrder] and [AppendByteOrder].
 var LittleEndian littleEndian
 
-// BigEndian is the big-endian implementation of ByteOrder and AppendByteOrder.
+// BigEndian is the big-endian implementation of [ByteOrder] and [AppendByteOrder].
 var BigEndian bigEndian
 
 type littleEndian struct{}
@@ -227,9 +231,9 @@ func (nativeEndian) GoString() string { return "binary.NativeEndian" }
 // When reading into a struct, all non-blank fields must be exported
 // or Read may panic.
 //
-// The error is EOF only if no bytes were read.
-// If an EOF happens after reading some but not all the bytes,
-// Read returns ErrUnexpectedEOF.
+// The error is [io.EOF] only if no bytes were read.
+// If an [io.EOF] happens after reading some but not all the bytes,
+// Read returns [io.ErrUnexpectedEOF].
 func Read(r io.Reader, order ByteOrder, data any) error {
 	// Fast path for basic types and slices.
 	if n := intDataSize(data); n != 0 {
@@ -460,7 +464,7 @@ func Write(w io.Writer, order ByteOrder, data any) error {
 	return err
 }
 
-// Size returns how many bytes Write would generate to encode the value v, which
+// Size returns how many bytes [Write] would generate to encode the value v, which
 // must be a fixed-size value or a slice of fixed-size values, or a pointer to such data.
 // If v is neither of these, Size returns -1.
 func Size(v any) int {

src/encoding/binary/native_endian_big.go

@@ -10,5 +10,5 @@ type nativeEndian struct {
 	bigEndian
 }
 
-// NativeEndian is the native-endian implementation of ByteOrder and AppendByteOrder.
+// NativeEndian is the native-endian implementation of [ByteOrder] and [AppendByteOrder].
 var NativeEndian nativeEndian

src/encoding/binary/native_endian_little.go

@@ -10,5 +10,5 @@ type nativeEndian struct {
 	littleEndian
 }
 
-// NativeEndian is the native-endian implementation of ByteOrder and AppendByteOrder.
+// NativeEndian is the native-endian implementation of [ByteOrder] and [AppendByteOrder].
 var NativeEndian nativeEndian

src/encoding/binary/varint.go

@@ -37,7 +37,7 @@ const (
 )
 
 // AppendUvarint appends the varint-encoded form of x,
-// as generated by PutUvarint, to buf and returns the extended buffer.
+// as generated by [PutUvarint], to buf and returns the extended buffer.
 func AppendUvarint(buf []byte, x uint64) []byte {
 	for x >= 0x80 {
 		buf = append(buf, byte(x)|0x80)
@@ -88,7 +88,7 @@ func Uvarint(buf []byte) (uint64, int) {
 }
 
 // AppendVarint appends the varint-encoded form of x,
-// as generated by PutVarint, to buf and returns the extended buffer.
+// as generated by [PutVarint], to buf and returns the extended buffer.
 func AppendVarint(buf []byte, x int64) []byte {
 	ux := uint64(x) << 1
 	if x < 0 {
@@ -126,9 +126,9 @@ func Varint(buf []byte) (int64, int) {
 var errOverflow = errors.New("binary: varint overflows a 64-bit integer")
 
 // ReadUvarint reads an encoded unsigned integer from r and returns it as a uint64.
-// The error is EOF only if no bytes were read.
-// If an EOF happens after reading some but not all the bytes,
-// ReadUvarint returns io.ErrUnexpectedEOF.
+// The error is [io.EOF] only if no bytes were read.
+// If an [io.EOF] happens after reading some but not all the bytes,
+// ReadUvarint returns [io.ErrUnexpectedEOF].
 func ReadUvarint(r io.ByteReader) (uint64, error) {
 	var x uint64
 	var s uint
@@ -153,9 +153,9 @@ func ReadUvarint(r io.ByteReader) (uint64, error) {
 }
 
 // ReadVarint reads an encoded signed integer from r and returns it as an int64.
-// The error is EOF only if no bytes were read.
-// If an EOF happens after reading some but not all the bytes,
-// ReadVarint returns io.ErrUnexpectedEOF.
+// The error is [io.EOF] only if no bytes were read.
+// If an [io.EOF] happens after reading some but not all the bytes,
+// ReadVarint returns [io.ErrUnexpectedEOF].
 func ReadVarint(r io.ByteReader) (int64, error) {
 	ux, err := ReadUvarint(r) // ok to continue in presence of error
 	x := int64(ux >> 1)

src/encoding/csv/reader.go

@@ -82,7 +82,7 @@ func (e *ParseError) Error() string {
 
 func (e *ParseError) Unwrap() error { return e.Err }
 
-// These are the errors that can be returned in ParseError.Err.
+// These are the errors that can be returned in [ParseError.Err].
 var (
 	ErrBareQuote  = errors.New("bare \" in non-quoted-field")
 	ErrQuote      = errors.New("extraneous or missing \" in quoted-field")
@@ -100,9 +100,9 @@ func validDelim(r rune) bool {
 
 // A Reader reads records from a CSV-encoded file.
 //
-// As returned by NewReader, a Reader expects input conforming to RFC 4180.
+// As returned by [NewReader], a Reader expects input conforming to RFC 4180.
 // The exported fields can be changed to customize the details before the
-// first call to Read or ReadAll.
+// first call to [Reader.Read] or [Reader.ReadAll].
 //
 // The Reader converts all \r\n sequences in its input to plain \n,
 // including in multiline field values, so that the returned data does
@@ -186,12 +186,12 @@ func NewReader(r io.Reader) *Reader {
 
 // Read reads one record (a slice of fields) from r.
 // If the record has an unexpected number of fields,
-// Read returns the record along with the error ErrFieldCount.
+// Read returns the record along with the error [ErrFieldCount].
 // If the record contains a field that cannot be parsed,
 // Read returns a partial record along with the parse error.
 // The partial record contains all fields read before the error.
-// If there is no data left to be read, Read returns nil, io.EOF.
-// If ReuseRecord is true, the returned slice may be shared
+// If there is no data left to be read, Read returns nil, [io.EOF].
+// If [Reader.ReuseRecord] is true, the returned slice may be shared
 // between multiple calls to Read.
 func (r *Reader) Read() (record []string, err error) {
 	if r.ReuseRecord {
@@ -205,7 +205,7 @@ func (r *Reader) Read() (record []string, err error) {
 
 // FieldPos returns the line and column corresponding to
 // the start of the field with the given index in the slice most recently
-// returned by Read. Numbering of lines and columns starts at 1;
+// returned by [Reader.Read]. Numbering of lines and columns starts at 1;
 // columns are counted in bytes, not runes.
 //
 // If this is called with an out-of-bounds index, it panics.
@@ -231,7 +231,7 @@ type position struct {
 
 // ReadAll reads all the remaining records from r.
 // Each record is a slice of fields.
-// A successful call returns err == nil, not err == io.EOF. Because ReadAll is
+// A successful call returns err == nil, not err == [io.EOF]. Because ReadAll is
 // defined to read until EOF, it does not treat end of file as an error to be
 // reported.
 func (r *Reader) ReadAll() (records [][]string, err error) {
@@ -249,7 +249,7 @@ func (r *Reader) ReadAll() (records [][]string, err error) {
 
 // readLine reads the next line (with the trailing endline).
 // If EOF is hit without a trailing endline, it will be omitted.
-// If some bytes were read, then the error is never io.EOF.
+// If some bytes were read, then the error is never [io.EOF].
 // The result is only valid until the next call to readLine.
 func (r *Reader) readLine() ([]byte, error) {
 	line, err := r.r.ReadSlice('\n')