regexp: add godoc links

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

1 files changed, 46 insertions, 48 deletions

diff --git a/src/regexp/regexp.go b/src/regexp/regexp.go
index 3752b467c6..462f235b1b 100644
--- a/src/regexp/regexp.go
+++ b/src/regexp/regexp.go
@@ -8,9 +8,7 @@
 // general syntax used by Perl, Python, and other languages.
 // More precisely, it is the syntax accepted by RE2 and described at
 // https://golang.org/s/re2syntax, except for \C.
-// For an overview of the syntax, run
-//
-//	go doc regexp/syntax
+// For an overview of the syntax, see the [regexp/syntax] package.
 //
 // The regexp implementation provided by this package is
 // guaranteed to run in time linear in the size of the input.
@@ -23,10 +21,10 @@
 // or any book about automata theory.
 //
 // All characters are UTF-8-encoded code points.
-// Following utf8.DecodeRune, each byte of an invalid UTF-8 sequence
+// Following [utf8.DecodeRune], each byte of an invalid UTF-8 sequence
 // is treated as if it encoded utf8.RuneError (U+FFFD).
 //
-// There are 16 methods of Regexp that match a regular expression and identify
+// There are 16 methods of [Regexp] that match a regular expression and identify
 // the matched text. Their names are matched by this regular expression:
 //
 //	Find(All)?(String)?(Submatch)?(Index)?
@@ -82,7 +80,7 @@ import (
 
 // Regexp is the representation of a compiled regular expression.
 // A Regexp is safe for concurrent use by multiple goroutines,
-// except for configuration methods, such as Longest.
+// except for configuration methods, such as [Regexp.Longest].
 type Regexp struct {
 	expr           string       // as passed to Compile
 	prog           *syntax.Prog // compiled program
@@ -110,21 +108,21 @@ func (re *Regexp) String() string {
 	return re.expr
 }
 
-// Copy returns a new Regexp object copied from re.
-// Calling Longest on one copy does not affect another.
+// Copy returns a new [Regexp] object copied from re.
+// Calling [Regexp.Longest] on one copy does not affect another.
 //
-// Deprecated: In earlier releases, when using a Regexp in multiple goroutines,
+// Deprecated: In earlier releases, when using a [Regexp] in multiple goroutines,
 // giving each goroutine its own copy helped to avoid lock contention.
 // As of Go 1.12, using Copy is no longer necessary to avoid lock contention.
 // Copy may still be appropriate if the reason for its use is to make
-// two copies with different Longest settings.
+// two copies with different [Regexp.Longest] settings.
 func (re *Regexp) Copy() *Regexp {
 	re2 := *re
 	return &re2
 }
 
 // Compile parses a regular expression and returns, if successful,
-// a Regexp object that can be used to match against text.
+// a [Regexp] object that can be used to match against text.
 //
 // When matching against text, the regexp returns a match that
 // begins as early as possible in the input (leftmost), and among those
@@ -132,12 +130,12 @@ func (re *Regexp) Copy() *Regexp {
 // This so-called leftmost-first matching is the same semantics
 // that Perl, Python, and other implementations use, although this
 // package implements it without the expense of backtracking.
-// For POSIX leftmost-longest matching, see CompilePOSIX.
+// For POSIX leftmost-longest matching, see [CompilePOSIX].
 func Compile(expr string) (*Regexp, error) {
 	return compile(expr, syntax.Perl, false)
 }
 
-// CompilePOSIX is like Compile but restricts the regular expression
+// CompilePOSIX is like [Compile] but restricts the regular expression
 // to POSIX ERE (egrep) syntax and changes the match semantics to
 // leftmost-longest.
 //
@@ -164,7 +162,7 @@ func CompilePOSIX(expr string) (*Regexp, error) {
 // That is, when matching against text, the regexp returns a match that
 // begins as early as possible in the input (leftmost), and among those
 // it chooses a match that is as long as possible.
-// This method modifies the Regexp and may not be called concurrently
+// This method modifies the [Regexp] and may not be called concurrently
 // with any other methods.
 func (re *Regexp) Longest() {
 	re.longest = true
@@ -310,7 +308,7 @@ func minInputLen(re *syntax.Regexp) int {
 	}
 }
 
-// MustCompile is like Compile but panics if the expression cannot be parsed.
+// MustCompile is like [Compile] but panics if the expression cannot be parsed.
 // It simplifies safe initialization of global variables holding compiled regular
 // expressions.
 func MustCompile(str string) *Regexp {
@@ -321,7 +319,7 @@ func MustCompile(str string) *Regexp {
 	return regexp
 }
 
-// MustCompilePOSIX is like CompilePOSIX but panics if the expression cannot be parsed.
+// MustCompilePOSIX is like [CompilePOSIX] but panics if the expression cannot be parsed.
 // It simplifies safe initialization of global variables holding compiled regular
 // expressions.
 func MustCompilePOSIX(str string) *Regexp {
@@ -339,13 +337,13 @@ func quote(s string) string {
 	return strconv.Quote(s)
 }
 
-// NumSubexp returns the number of parenthesized subexpressions in this Regexp.
+// NumSubexp returns the number of parenthesized subexpressions in this [Regexp].
 func (re *Regexp) NumSubexp() int {
 	return re.numSubexp
 }
 
 // SubexpNames returns the names of the parenthesized subexpressions
-// in this Regexp. The name for the first sub-expression is names[1],
+// in this [Regexp]. The name for the first sub-expression is names[1],
 // so that if m is a match slice, the name for m[i] is SubexpNames()[i].
 // Since the Regexp as a whole cannot be named, names[0] is always
 // the empty string. The slice should not be modified.
@@ -521,7 +519,7 @@ func (re *Regexp) LiteralPrefix() (prefix string, complete bool) {
 	return re.prefix, re.prefixComplete
 }
 
-// MatchReader reports whether the text returned by the RuneReader
+// MatchReader reports whether the text returned by the [io.RuneReader]
 // contains any match of the regular expression re.
 func (re *Regexp) MatchReader(r io.RuneReader) bool {
 	return re.doMatch(r, nil, "")
@@ -541,7 +539,7 @@ func (re *Regexp) Match(b []byte) bool {
 
 // MatchReader reports whether the text returned by the RuneReader
 // contains any match of the regular expression pattern.
-// More complicated queries need to use Compile and the full Regexp interface.
+// More complicated queries need to use [Compile] and the full [Regexp] interface.
 func MatchReader(pattern string, r io.RuneReader) (matched bool, err error) {
 	re, err := Compile(pattern)
 	if err != nil {
@@ -552,7 +550,7 @@ func MatchReader(pattern string, r io.RuneReader) (matched bool, err error) {
 
 // MatchString reports whether the string s
 // contains any match of the regular expression pattern.
-// More complicated queries need to use Compile and the full Regexp interface.
+// More complicated queries need to use [Compile] and the full [Regexp] interface.
 func MatchString(pattern string, s string) (matched bool, err error) {
 	re, err := Compile(pattern)
 	if err != nil {
@@ -563,7 +561,7 @@ func MatchString(pattern string, s string) (matched bool, err error) {
 
 // Match reports whether the byte slice b
 // contains any match of the regular expression pattern.
-// More complicated queries need to use Compile and the full Regexp interface.
+// More complicated queries need to use [Compile] and the full [Regexp] interface.
 func Match(pattern string, b []byte) (matched bool, err error) {
 	re, err := Compile(pattern)
 	if err != nil {
@@ -572,9 +570,9 @@ func Match(pattern string, b []byte) (matched bool, err error) {
 	return re.Match(b), nil
 }
 
-// ReplaceAllString returns a copy of src, replacing matches of the Regexp
+// ReplaceAllString returns a copy of src, replacing matches of the [Regexp]
 // with the replacement string repl.
-// Inside repl, $ signs are interpreted as in Expand.
+// Inside repl, $ signs are interpreted as in [Regexp.Expand].
 func (re *Regexp) ReplaceAllString(src, repl string) string {
 	n := 2
 	if strings.Contains(repl, "$") {
@@ -586,9 +584,9 @@ func (re *Regexp) ReplaceAllString(src, repl string) string {
 	return string(b)
 }
 
-// ReplaceAllLiteralString returns a copy of src, replacing matches of the Regexp
+// ReplaceAllLiteralString returns a copy of src, replacing matches of the [Regexp]
 // with the replacement string repl. The replacement repl is substituted directly,
-// without using Expand.
+// without using [Regexp.Expand].
 func (re *Regexp) ReplaceAllLiteralString(src, repl string) string {
 	return string(re.replaceAll(nil, src, 2, func(dst []byte, match []int) []byte {
 		return append(dst, repl...)
@@ -596,9 +594,9 @@ func (re *Regexp) ReplaceAllLiteralString(src, repl string) string {
 }
 
 // ReplaceAllStringFunc returns a copy of src in which all matches of the
-// Regexp have been replaced by the return value of function repl applied
+// [Regexp] have been replaced by the return value of function repl applied
 // to the matched substring. The replacement returned by repl is substituted
-// directly, without using Expand.
+// directly, without using [Regexp.Expand].
 func (re *Regexp) ReplaceAllStringFunc(src string, repl func(string) string) string {
 	b := re.replaceAll(nil, src, 2, func(dst []byte, match []int) []byte {
 		return append(dst, repl(src[match[0]:match[1]])...)
@@ -671,9 +669,9 @@ func (re *Regexp) replaceAll(bsrc []byte, src string, nmatch int, repl func(dst
 	return buf
 }
 
-// ReplaceAll returns a copy of src, replacing matches of the Regexp
+// ReplaceAll returns a copy of src, replacing matches of the [Regexp]
 // with the replacement text repl.
-// Inside repl, $ signs are interpreted as in Expand.
+// Inside repl, $ signs are interpreted as in [Regexp.Expand].
 func (re *Regexp) ReplaceAll(src, repl []byte) []byte {
 	n := 2
 	if bytes.IndexByte(repl, '$') >= 0 {
@@ -689,9 +687,9 @@ func (re *Regexp) ReplaceAll(src, repl []byte) []byte {
 	return b
 }
 
-// ReplaceAllLiteral returns a copy of src, replacing matches of the Regexp
+// ReplaceAllLiteral returns a copy of src, replacing matches of the [Regexp]
 // with the replacement bytes repl. The replacement repl is substituted directly,
-// without using Expand.
+// without using [Regexp.Expand].
 func (re *Regexp) ReplaceAllLiteral(src, repl []byte) []byte {
 	return re.replaceAll(src, "", 2, func(dst []byte, match []int) []byte {
 		return append(dst, repl...)
@@ -699,9 +697,9 @@ func (re *Regexp) ReplaceAllLiteral(src, repl []byte) []byte {
 }
 
 // ReplaceAllFunc returns a copy of src in which all matches of the
-// Regexp have been replaced by the return value of function repl applied
+// [Regexp] have been replaced by the return value of function repl applied
 // to the matched byte slice. The replacement returned by repl is substituted
-// directly, without using Expand.
+// directly, without using [Regexp.Expand].
 func (re *Regexp) ReplaceAllFunc(src []byte, repl func([]byte) []byte) []byte {
 	return re.replaceAll(src, "", 2, func(dst []byte, match []int) []byte {
 		return append(dst, repl(src[match[0]:match[1]])...)
@@ -845,7 +843,7 @@ func (re *Regexp) FindIndex(b []byte) (loc []int) {
 // FindString returns a string holding the text of the leftmost match in s of the regular
 // expression. If there is no match, the return value is an empty string,
 // but it will also be empty if the regular expression successfully matches
-// an empty string. Use FindStringIndex or FindStringSubmatch if it is
+// an empty string. Use [Regexp.FindStringIndex] or [Regexp.FindStringSubmatch] if it is
 // necessary to distinguish these cases.
 func (re *Regexp) FindString(s string) string {
 	var dstCap [2]int
@@ -870,7 +868,7 @@ func (re *Regexp) FindStringIndex(s string) (loc []int) {
 
 // FindReaderIndex returns a two-element slice of integers defining the
 // location of the leftmost match of the regular expression in text read from
-// the RuneReader. The match text was found in the input stream at
+// the [io.RuneReader]. The match text was found in the input stream at
 // byte offset loc[0] through loc[1]-1.
 // A return value of nil indicates no match.
 func (re *Regexp) FindReaderIndex(r io.RuneReader) (loc []int) {
@@ -904,7 +902,7 @@ func (re *Regexp) FindSubmatch(b []byte) [][]byte {
 // Expand appends template to dst and returns the result; during the
 // append, Expand replaces variables in the template with corresponding
 // matches drawn from src. The match slice should have been returned by
-// FindSubmatchIndex.
+// [Regexp.FindSubmatchIndex].
 //
 // In the template, a variable is denoted by a substring of the form
 // $name or ${name}, where name is a non-empty sequence of letters,
@@ -922,7 +920,7 @@ func (re *Regexp) Expand(dst []byte, template []byte, src []byte, match []int) [
 	return re.expand(dst, string(template), src, "", match)
 }
 
-// ExpandString is like Expand but the template and source are strings.
+// ExpandString is like [Regexp.Expand] but the template and source are strings.
 // It appends to and returns a byte slice in order to give the calling
 // code control over allocation.
 func (re *Regexp) ExpandString(dst []byte, template string, src string, match []int) []byte {
@@ -1067,7 +1065,7 @@ func (re *Regexp) FindStringSubmatchIndex(s string) []int {
 
 // FindReaderSubmatchIndex returns a slice holding the index pairs
 // identifying the leftmost match of the regular expression of text read by
-// the RuneReader, and the matches, if any, of its subexpressions, as defined
+// the [io.RuneReader], and the matches, if any, of its subexpressions, as defined
 // by the 'Submatch' and 'Index' descriptions in the package comment. A
 // return value of nil indicates no match.
 func (re *Regexp) FindReaderSubmatchIndex(r io.RuneReader) []int {
@@ -1094,7 +1092,7 @@ func (re *Regexp) FindAll(b []byte, n int) [][]byte {
 	return result
 }
 
-// FindAllIndex is the 'All' version of FindIndex; it returns a slice of all
+// FindAllIndex is the 'All' version of [Regexp.FindIndex]; it returns a slice of all
 // successive matches of the expression, as defined by the 'All' description
 // in the package comment.
 // A return value of nil indicates no match.
@@ -1112,7 +1110,7 @@ func (re *Regexp) FindAllIndex(b []byte, n int) [][]int {
 	return result
 }
 
-// FindAllString is the 'All' version of FindString; it returns a slice of all
+// FindAllString is the 'All' version of [Regexp.FindString]; it returns a slice of all
 // successive matches of the expression, as defined by the 'All' description
 // in the package comment.
 // A return value of nil indicates no match.
@@ -1130,7 +1128,7 @@ func (re *Regexp) FindAllString(s string, n int) []string {
 	return result
 }
 
-// FindAllStringIndex is the 'All' version of FindStringIndex; it returns a
+// FindAllStringIndex is the 'All' version of [Regexp.FindStringIndex]; it returns a
 // slice of all successive matches of the expression, as defined by the 'All'
 // description in the package comment.
 // A return value of nil indicates no match.
@@ -1148,7 +1146,7 @@ func (re *Regexp) FindAllStringIndex(s string, n int) [][]int {
 	return result
 }
 
-// FindAllSubmatch is the 'All' version of FindSubmatch; it returns a slice
+// FindAllSubmatch is the 'All' version of [Regexp.FindSubmatch]; it returns a slice
 // of all successive matches of the expression, as defined by the 'All'
 // description in the package comment.
 // A return value of nil indicates no match.
@@ -1172,7 +1170,7 @@ func (re *Regexp) FindAllSubmatch(b []byte, n int) [][][]byte {
 	return result
 }
 
-// FindAllSubmatchIndex is the 'All' version of FindSubmatchIndex; it returns
+// FindAllSubmatchIndex is the 'All' version of [Regexp.FindSubmatchIndex]; it returns
 // a slice of all successive matches of the expression, as defined by the
 // 'All' description in the package comment.
 // A return value of nil indicates no match.
@@ -1190,7 +1188,7 @@ func (re *Regexp) FindAllSubmatchIndex(b []byte, n int) [][]int {
 	return result
 }
 
-// FindAllStringSubmatch is the 'All' version of FindStringSubmatch; it
+// FindAllStringSubmatch is the 'All' version of [Regexp.FindStringSubmatch]; it
 // returns a slice of all successive matches of the expression, as defined by
 // the 'All' description in the package comment.
 // A return value of nil indicates no match.
@@ -1215,7 +1213,7 @@ func (re *Regexp) FindAllStringSubmatch(s string, n int) [][]string {
 }
 
 // FindAllStringSubmatchIndex is the 'All' version of
-// FindStringSubmatchIndex; it returns a slice of all successive matches of
+// [Regexp.FindStringSubmatchIndex]; it returns a slice of all successive matches of
 // the expression, as defined by the 'All' description in the package
 // comment.
 // A return value of nil indicates no match.
@@ -1237,8 +1235,8 @@ func (re *Regexp) FindAllStringSubmatchIndex(s string, n int) [][]int {
 // the substrings between those expression matches.
 //
 // The slice returned by this method consists of all the substrings of s
-// not contained in the slice returned by FindAllString. When called on an expression
-// that contains no metacharacters, it is equivalent to strings.SplitN.
+// not contained in the slice returned by [Regexp.FindAllString]. When called on an expression
+// that contains no metacharacters, it is equivalent to [strings.SplitN].
 //
 // Example:
 //