bytes,strings: add available godoc link

Change-Id: Id9706a783d3321e3706eeee102286522e7968efd
Reviewed-on: https://go-review.googlesource.com/c/go/+/534775
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>

src/bytes/buffer.go

@@ -15,7 +15,7 @@ import (
 // smallBufferSize is an initial allocation minimal capacity.
 const smallBufferSize = 64
 
-// A Buffer is a variable-sized buffer of bytes with Read and Write methods.
+// A Buffer is a variable-sized buffer of bytes with [Buffer.Read] and [Buffer.Write] methods.
 // The zero value for Buffer is an empty buffer ready to use.
 type Buffer struct {
 	buf      []byte // contents are the bytes buf[off : len(buf)]
@@ -48,19 +48,19 @@ const maxInt = int(^uint(0) >> 1)
 
 // Bytes returns a slice of length b.Len() holding the unread portion of the buffer.
 // The slice is valid for use only until the next buffer modification (that is,
-// only until the next call to a method like Read, Write, Reset, or Truncate).
+// only until the next call to a method like [Buffer.Read], [Buffer.Write], [Buffer.Reset], or [Buffer.Truncate]).
 // The slice aliases the buffer content at least until the next buffer modification,
 // so immediate changes to the slice will affect the result of future reads.
 func (b *Buffer) Bytes() []byte { return b.buf[b.off:] }
 
 // AvailableBuffer returns an empty buffer with b.Available() capacity.
 // This buffer is intended to be appended to and
-// passed to an immediately succeeding Write call.
+// passed to an immediately succeeding [Buffer.Write] call.
 // The buffer is only valid until the next write operation on b.
 func (b *Buffer) AvailableBuffer() []byte { return b.buf[len(b.buf):] }
 
 // String returns the contents of the unread portion of the buffer
-// as a string. If the Buffer is a nil pointer, it returns "<nil>".
+// as a string. If the [Buffer] is a nil pointer, it returns "<nil>".
 //
 // To build strings more efficiently, see the strings.Builder type.
 func (b *Buffer) String() string {
@@ -102,7 +102,7 @@ func (b *Buffer) Truncate(n int) {
 
 // Reset resets the buffer to be empty,
 // but it retains the underlying storage for use by future writes.
-// Reset is the same as Truncate(0).
+// Reset is the same as [Buffer.Truncate](0).
 func (b *Buffer) Reset() {
 	b.buf = b.buf[:0]
 	b.off = 0
@@ -160,7 +160,7 @@ func (b *Buffer) grow(n int) int {
 // another n bytes. After Grow(n), at least n bytes can be written to the
 // buffer without another allocation.
 // If n is negative, Grow will panic.
-// If the buffer can't grow it will panic with ErrTooLarge.
+// If the buffer can't grow it will panic with [ErrTooLarge].
 func (b *Buffer) Grow(n int) {
 	if n < 0 {
 		panic("bytes.Buffer.Grow: negative count")
@@ -171,7 +171,7 @@ func (b *Buffer) Grow(n int) {
 
 // Write appends the contents of p to the buffer, growing the buffer as
 // needed. The return value n is the length of p; err is always nil. If the
-// buffer becomes too large, Write will panic with ErrTooLarge.
+// buffer becomes too large, Write will panic with [ErrTooLarge].
 func (b *Buffer) Write(p []byte) (n int, err error) {
 	b.lastRead = opInvalid
 	m, ok := b.tryGrowByReslice(len(p))
@@ -183,7 +183,7 @@ func (b *Buffer) Write(p []byte) (n int, err error) {
 
 // WriteString appends the contents of s to the buffer, growing the buffer as
 // needed. The return value n is the length of s; err is always nil. If the
-// buffer becomes too large, WriteString will panic with ErrTooLarge.
+// buffer becomes too large, WriteString will panic with [ErrTooLarge].
 func (b *Buffer) WriteString(s string) (n int, err error) {
 	b.lastRead = opInvalid
 	m, ok := b.tryGrowByReslice(len(s))
@@ -194,7 +194,7 @@ func (b *Buffer) WriteString(s string) (n int, err error) {
 }
 
 // MinRead is the minimum slice size passed to a Read call by
-// Buffer.ReadFrom. As long as the Buffer has at least MinRead bytes beyond
+// [Buffer.ReadFrom]. As long as the [Buffer] has at least MinRead bytes beyond
 // what is required to hold the contents of r, ReadFrom will not grow the
 // underlying buffer.
 const MinRead = 512
@@ -202,7 +202,7 @@ const MinRead = 512
 // ReadFrom reads data from r until EOF and appends it to the buffer, growing
 // the buffer as needed. The return value n is the number of bytes read. Any
 // error except io.EOF encountered during the read is also returned. If the
-// buffer becomes too large, ReadFrom will panic with ErrTooLarge.
+// buffer becomes too large, ReadFrom will panic with [ErrTooLarge].
 func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) {
 	b.lastRead = opInvalid
 	for {
@@ -279,9 +279,9 @@ func (b *Buffer) WriteTo(w io.Writer) (n int64, err error) {
 }
 
 // WriteByte appends the byte c to the buffer, growing the buffer as needed.
-// The returned error is always nil, but is included to match bufio.Writer's
+// The returned error is always nil, but is included to match [bufio.Writer]'s
 // WriteByte. If the buffer becomes too large, WriteByte will panic with
-// ErrTooLarge.
+// [ErrTooLarge].
 func (b *Buffer) WriteByte(c byte) error {
 	b.lastRead = opInvalid
 	m, ok := b.tryGrowByReslice(1)
@@ -294,8 +294,8 @@ func (b *Buffer) WriteByte(c byte) error {
 
 // WriteRune appends the UTF-8 encoding of Unicode code point r to the
 // buffer, returning its length and an error, which is always nil but is
-// included to match bufio.Writer's WriteRune. The buffer is grown as needed;
+// included to match [bufio.Writer]'s WriteRune. The buffer is grown as needed;
-// if it becomes too large, WriteRune will panic with ErrTooLarge.
+// if it becomes too large, WriteRune will panic with [ErrTooLarge].
 func (b *Buffer) WriteRune(r rune) (n int, err error) {
 	// Compare as uint32 to correctly handle negative runes.
 	if uint32(r) < utf8.RuneSelf {
@@ -334,7 +334,7 @@ func (b *Buffer) Read(p []byte) (n int, err error) {
 }
 
 // Next returns a slice containing the next n bytes from the buffer,
-// advancing the buffer as if the bytes had been returned by Read.
+// advancing the buffer as if the bytes had been returned by [Buffer.Read].
 // If there are fewer than n bytes in the buffer, Next returns the entire buffer.
 // The slice is only valid until the next call to a read or write method.
 func (b *Buffer) Next(n int) []byte {
@@ -388,10 +388,10 @@ func (b *Buffer) ReadRune() (r rune, size int, err error) {
 	return r, n, nil
 }
 
-// UnreadRune unreads the last rune returned by ReadRune.
+// UnreadRune unreads the last rune returned by [Buffer.ReadRune].
 // If the most recent read or write operation on the buffer was
-// not a successful ReadRune, UnreadRune returns an error.  (In this regard
+// not a successful [Buffer.ReadRune], UnreadRune returns an error.  (In this regard
-// it is stricter than UnreadByte, which will unread the last byte
+// it is stricter than [Buffer.UnreadByte], which will unread the last byte
 // from any read operation.)
 func (b *Buffer) UnreadRune() error {
 	if b.lastRead <= opInvalid {
@@ -460,23 +460,23 @@ func (b *Buffer) ReadString(delim byte) (line string, err error) {
 	return string(slice), err
 }
 
-// NewBuffer creates and initializes a new Buffer using buf as its
+// NewBuffer creates and initializes a new [Buffer] using buf as its
-// initial contents. The new Buffer takes ownership of buf, and the
+// initial contents. The new [Buffer] takes ownership of buf, and the
 // caller should not use buf after this call. NewBuffer is intended to
-// prepare a Buffer to read existing data. It can also be used to set
+// prepare a [Buffer] to read existing data. It can also be used to set
 // the initial size of the internal buffer for writing. To do that,
 // buf should have the desired capacity but a length of zero.
 //
-// In most cases, new(Buffer) (or just declaring a Buffer variable) is
+// In most cases, new([Buffer]) (or just declaring a [Buffer] variable) is
-// sufficient to initialize a Buffer.
+// sufficient to initialize a [Buffer].
 func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} }
 
-// NewBufferString creates and initializes a new Buffer using string s as its
+// NewBufferString creates and initializes a new [Buffer] using string s as its
 // initial contents. It is intended to prepare a buffer to read an existing
 // string.
 //
-// In most cases, new(Buffer) (or just declaring a Buffer variable) is
+// In most cases, new([Buffer]) (or just declaring a [Buffer] variable) is
-// sufficient to initialize a Buffer.
+// sufficient to initialize a [Buffer].
 func NewBufferString(s string) *Buffer {
 	return &Buffer{buf: []byte(s)}
 }

src/bytes/reader.go

@@ -13,7 +13,7 @@ import (
 // A Reader implements the io.Reader, io.ReaderAt, io.WriterTo, io.Seeker,
 // io.ByteScanner, and io.RuneScanner interfaces by reading from
 // a byte slice.
-// Unlike a Buffer, a Reader is read-only and supports seeking.
+// Unlike a [Buffer], a Reader is read-only and supports seeking.
 // The zero value for Reader operates like a Reader of an empty slice.
 type Reader struct {
 	s        []byte
@@ -31,11 +31,11 @@ func (r *Reader) Len() int {
 }
 
 // Size returns the original length of the underlying byte slice.
-// Size is the number of bytes available for reading via ReadAt.
+// Size is the number of bytes available for reading via [Reader.ReadAt].
-// The result is unaffected by any method calls except Reset.
+// The result is unaffected by any method calls except [Reader.Reset].
 func (r *Reader) Size() int64 { return int64(len(r.s)) }
 
-// Read implements the io.Reader interface.
+// Read implements the [io.Reader] interface.
 func (r *Reader) Read(b []byte) (n int, err error) {
 	if r.i >= int64(len(r.s)) {
 		return 0, io.EOF
@@ -46,7 +46,7 @@ func (r *Reader) Read(b []byte) (n int, err error) {
 	return
 }
 
-// ReadAt implements the io.ReaderAt interface.
+// ReadAt implements the [io.ReaderAt] interface.
 func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) {
 	// cannot modify state - see io.ReaderAt
 	if off < 0 {
@@ -62,7 +62,7 @@ func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) {
 	return
 }
 
-// ReadByte implements the io.ByteReader interface.
+// ReadByte implements the [io.ByteReader] interface.
 func (r *Reader) ReadByte() (byte, error) {
 	r.prevRune = -1
 	if r.i >= int64(len(r.s)) {
@@ -73,7 +73,7 @@ func (r *Reader) ReadByte() (byte, error) {
 	return b, nil
 }
 
-// UnreadByte complements ReadByte in implementing the io.ByteScanner interface.
+// UnreadByte complements [Reader.ReadByte] in implementing the [io.ByteScanner] interface.
 func (r *Reader) UnreadByte() error {
 	if r.i <= 0 {
 		return errors.New("bytes.Reader.UnreadByte: at beginning of slice")
@@ -83,7 +83,7 @@ func (r *Reader) UnreadByte() error {
 	return nil
 }
 
-// ReadRune implements the io.RuneReader interface.
+// ReadRune implements the [io.RuneReader] interface.
 func (r *Reader) ReadRune() (ch rune, size int, err error) {
 	if r.i >= int64(len(r.s)) {
 		r.prevRune = -1
@@ -99,7 +99,7 @@ func (r *Reader) ReadRune() (ch rune, size int, err error) {
 	return
 }
 
-// UnreadRune complements ReadRune in implementing the io.RuneScanner interface.
+// UnreadRune complements [Reader.ReadRune] in implementing the [io.RuneScanner] interface.
 func (r *Reader) UnreadRune() error {
 	if r.i <= 0 {
 		return errors.New("bytes.Reader.UnreadRune: at beginning of slice")
@@ -112,7 +112,7 @@ func (r *Reader) UnreadRune() error {
 	return nil
 }
 
-// Seek implements the io.Seeker interface.
+// Seek implements the [io.Seeker] interface.
 func (r *Reader) Seek(offset int64, whence int) (int64, error) {
 	r.prevRune = -1
 	var abs int64
@@ -133,7 +133,7 @@ func (r *Reader) Seek(offset int64, whence int) (int64, error) {
 	return abs, nil
 }
 
-// WriteTo implements the io.WriterTo interface.
+// WriteTo implements the [io.WriterTo] interface.
 func (r *Reader) WriteTo(w io.Writer) (n int64, err error) {
 	r.prevRune = -1
 	if r.i >= int64(len(r.s)) {
@@ -152,8 +152,8 @@ func (r *Reader) WriteTo(w io.Writer) (n int64, err error) {
 	return
 }
 
-// Reset resets the Reader to be reading from b.
+// Reset resets the [Reader.Reader] to be reading from b.
 func (r *Reader) Reset(b []byte) { *r = Reader{b, 0, -1} }
 
-// NewReader returns a new Reader reading from b.
+// NewReader returns a new [Reader.Reader] reading from b.
 func NewReader(b []byte) *Reader { return &Reader{b, 0, -1} }

src/strings/builder.go

@@ -10,7 +10,7 @@ import (
 	"unsafe"
 )
 
-// A Builder is used to efficiently build a string using Write methods.
+// A Builder is used to efficiently build a string using [Builder.Write] methods.
 // It minimizes memory copying. The zero value is ready to use.
 // Do not copy a non-zero Builder.
 type Builder struct {
@@ -57,7 +57,7 @@ func (b *Builder) Len() int { return len(b.buf) }
 // already written.
 func (b *Builder) Cap() int { return cap(b.buf) }
 
-// Reset resets the Builder to be empty.
+// Reset resets the [Builder] to be empty.
 func (b *Builder) Reset() {
 	b.addr = nil
 	b.buf = nil

src/strings/reader.go

@@ -10,8 +10,8 @@ import (
 	"unicode/utf8"
 )
 
-// A Reader implements the io.Reader, io.ReaderAt, io.ByteReader, io.ByteScanner,
+// A Reader implements the [io.Reader], [io.ReaderAt], [io.ByteReader], [io.ByteScanner],
-// io.RuneReader, io.RuneScanner, io.Seeker, and io.WriterTo interfaces by reading
+// [io.RuneReader], [io.RuneScanner], [io.Seeker], and [io.WriterTo] interfaces by reading
 // from a string.
 // The zero value for Reader operates like a Reader of an empty string.
 type Reader struct {
@@ -30,12 +30,12 @@ func (r *Reader) Len() int {
 }
 
 // Size returns the original length of the underlying string.
-// Size is the number of bytes available for reading via ReadAt.
+// Size is the number of bytes available for reading via [Reader.ReadAt].
 // The returned value is always the same and is not affected by calls
 // to any other method.
 func (r *Reader) Size() int64 { return int64(len(r.s)) }
 
-// Read implements the io.Reader interface.
+// Read implements the [io.Reader] interface.
 func (r *Reader) Read(b []byte) (n int, err error) {
 	if r.i >= int64(len(r.s)) {
 		return 0, io.EOF
@@ -46,7 +46,7 @@ func (r *Reader) Read(b []byte) (n int, err error) {
 	return
 }
 
-// ReadAt implements the io.ReaderAt interface.
+// ReadAt implements the [io.ReaderAt] interface.
 func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) {
 	// cannot modify state - see io.ReaderAt
 	if off < 0 {
@@ -62,7 +62,7 @@ func (r *Reader) ReadAt(b []byte, off int64) (n int, err error) {
 	return
 }
 
-// ReadByte implements the io.ByteReader interface.
+// ReadByte implements the [io.ByteReader] interface.
 func (r *Reader) ReadByte() (byte, error) {
 	r.prevRune = -1
 	if r.i >= int64(len(r.s)) {
@@ -73,7 +73,7 @@ func (r *Reader) ReadByte() (byte, error) {
 	return b, nil
 }
 
-// UnreadByte implements the io.ByteScanner interface.
+// UnreadByte implements the [io.ByteScanner] interface.
 func (r *Reader) UnreadByte() error {
 	if r.i <= 0 {
 		return errors.New("strings.Reader.UnreadByte: at beginning of string")
@@ -83,7 +83,7 @@ func (r *Reader) UnreadByte() error {
 	return nil
 }
 
-// ReadRune implements the io.RuneReader interface.
+// ReadRune implements the [io.RuneReader] interface.
 func (r *Reader) ReadRune() (ch rune, size int, err error) {
 	if r.i >= int64(len(r.s)) {
 		r.prevRune = -1
@@ -99,7 +99,7 @@ func (r *Reader) ReadRune() (ch rune, size int, err error) {
 	return
 }
 
-// UnreadRune implements the io.RuneScanner interface.
+// UnreadRune implements the [io.RuneScanner] interface.
 func (r *Reader) UnreadRune() error {
 	if r.i <= 0 {
 		return errors.New("strings.Reader.UnreadRune: at beginning of string")
@@ -112,7 +112,7 @@ func (r *Reader) UnreadRune() error {
 	return nil
 }
 
-// Seek implements the io.Seeker interface.
+// Seek implements the [io.Seeker] interface.
 func (r *Reader) Seek(offset int64, whence int) (int64, error) {
 	r.prevRune = -1
 	var abs int64
@@ -133,7 +133,7 @@ func (r *Reader) Seek(offset int64, whence int) (int64, error) {
 	return abs, nil
 }
 
-// WriteTo implements the io.WriterTo interface.
+// WriteTo implements the [io.WriterTo] interface.
 func (r *Reader) WriteTo(w io.Writer) (n int64, err error) {
 	r.prevRune = -1
 	if r.i >= int64(len(r.s)) {
@@ -152,9 +152,9 @@ func (r *Reader) WriteTo(w io.Writer) (n int64, err error) {
 	return
 }
 
-// Reset resets the Reader to be reading from s.
+// Reset resets the [Reader] to be reading from s.
 func (r *Reader) Reset(s string) { *r = Reader{s, 0, -1} }
 
-// NewReader returns a new Reader reading from s.
+// NewReader returns a new [Reader] reading from s.
-// It is similar to bytes.NewBufferString but more efficient and non-writable.
+// It is similar to [bytes.NewBufferString] but more efficient and non-writable.
 func NewReader(s string) *Reader { return &Reader{s, 0, -1} }

src/strings/replace.go

@@ -23,7 +23,7 @@ type replacer interface {
 	WriteString(w io.Writer, s string) (n int, err error)
 }
 
-// NewReplacer returns a new Replacer from a list of old, new string
+// NewReplacer returns a new [Replacer] from a list of old, new string
 // pairs. Replacements are performed in the order they appear in the
 // target string, without overlapping matches. The old string
 // comparisons are done in argument order.

src/strings/strings.go

@@ -272,7 +272,7 @@ func genSplit(s, sep string, sepSave, n int) []string {
 //	n < 0: all substrings
 //
 // Edge cases for s and sep (for example, empty strings) are handled
-// as described in the documentation for Split.
+// as described in the documentation for [Split].
 //
 // To split around the first instance of a separator, see Cut.
 func SplitN(s, sep string, n int) []string { return genSplit(s, sep, 0, n) }
@@ -301,7 +301,7 @@ func SplitAfterN(s, sep string, n int) []string {
 // If sep is empty, Split splits after each UTF-8 sequence. If both s
 // and sep are empty, Split returns an empty slice.
 //
-// It is equivalent to SplitN with a count of -1.
+// It is equivalent to [SplitN] with a count of -1.
 //
 // To split around the first instance of a separator, see Cut.
 func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }
@@ -315,7 +315,7 @@ func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }
 // If sep is empty, SplitAfter splits after each UTF-8 sequence. If
 // both s and sep are empty, SplitAfter returns an empty slice.
 //
-// It is equivalent to SplitAfterN with a count of -1.
+// It is equivalent to [SplitAfterN] with a count of -1.
 func SplitAfter(s, sep string) []string {
 	return genSplit(s, sep, len(sep), -1)
 }
@@ -904,7 +904,7 @@ func Trim(s, cutset string) string {
 // TrimLeft returns a slice of the string s with all leading
 // Unicode code points contained in cutset removed.
 //
-// To remove a prefix, use TrimPrefix instead.
+// To remove a prefix, use [TrimPrefix] instead.
 func TrimLeft(s, cutset string) string {
 	if s == "" || cutset == "" {
 		return s
@@ -952,7 +952,7 @@ func trimLeftUnicode(s, cutset string) string {
 // TrimRight returns a slice of the string s, with all trailing
 // Unicode code points contained in cutset removed.
 //
-// To remove a suffix, use TrimSuffix instead.
+// To remove a suffix, use [TrimSuffix] instead.
 func TrimRight(s, cutset string) string {
 	if s == "" || cutset == "" {
 		return s