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>

1 files changed, 12 insertions, 8 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 {