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>

4 files changed, 22 insertions, 18 deletions

diff --git a/src/encoding/binary/binary.go b/src/encoding/binary/binary.go
index 3fb18a7a03..f001be8386 100644
--- a/src/encoding/binary/binary.go
+++ b/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,6 +45,8 @@ 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
@@ -50,10 +54,10 @@ type AppendByteOrder interface {
 	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 {
diff --git a/src/encoding/binary/native_endian_big.go b/src/encoding/binary/native_endian_big.go
index 1a24354f4b..bcc8e30b74 100644
--- a/src/encoding/binary/native_endian_big.go
+++ b/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
diff --git a/src/encoding/binary/native_endian_little.go b/src/encoding/binary/native_endian_little.go
index 67b41ae0a2..38d3e9b695 100644
--- a/src/encoding/binary/native_endian_little.go
+++ b/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
diff --git a/src/encoding/binary/varint.go b/src/encoding/binary/varint.go
index 7b14fb2b63..64dd9d61b4 100644
--- a/src/encoding/binary/varint.go
+++ b/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)