runtime: more godoc links

Change-Id: I8fe66326994894b17ce0eda991bba942844d26b0
Reviewed-on: https://go-review.googlesource.com/c/go/+/541475
Reviewed-by: Michael Knyszek <mknyszek@google.com>
Reviewed-by: Michael Pratt <mpratt@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

8 files changed, 26 insertions, 25 deletions

diff --git a/src/runtime/cpuprof.go b/src/runtime/cpuprof.go
index 331484b1ff..b2898ba909 100644
--- a/src/runtime/cpuprof.go
+++ b/src/runtime/cpuprof.go
@@ -62,8 +62,8 @@ var cpuprof cpuProfile
 // If hz <= 0, SetCPUProfileRate turns off profiling.
 // If the profiler is on, the rate cannot be changed without first turning it off.
 //
-// Most clients should use the runtime/pprof package or
-// the testing package's -test.cpuprofile flag instead of calling
+// Most clients should use the [runtime/pprof] package or
+// the [testing] package's -test.cpuprofile flag instead of calling
 // SetCPUProfileRate directly.
 func SetCPUProfileRate(hz int) {
 	// Clamp hz to something reasonable.
@@ -204,7 +204,7 @@ func (p *cpuProfile) addExtra() {
 //
 // Deprecated: Use the [runtime/pprof] package,
 // or the handlers in the [net/http/pprof] package,
-// or the testing package's -test.cpuprofile flag instead.
+// or the [testing] package's -test.cpuprofile flag instead.
 func CPUProfile() []byte {
 	panic("CPUProfile no longer available")
 }
diff --git a/src/runtime/extern.go b/src/runtime/extern.go
index b7bf0a505b..4b3ae63fb5 100644
--- a/src/runtime/extern.go
+++ b/src/runtime/extern.go
@@ -28,7 +28,7 @@ program. GOMEMLIMIT is a numeric value in bytes with an optional unit suffix.
 The supported suffixes include B, KiB, MiB, GiB, and TiB. These suffixes
 represent quantities of bytes as defined by the IEC 80000-13 standard. That is,
 they are based on powers of two: KiB means 2^10 bytes, MiB means 2^20 bytes,
-and so on. The default setting is math.MaxInt64, which effectively disables the
+and so on. The default setting is [math.MaxInt64], which effectively disables the
 memory limit. [runtime/debug.SetMemoryLimit] allows changing this limit at run
 time.
 
@@ -215,17 +215,17 @@ It is a comma-separated list of name=val pairs setting these named variables:
 	because it also disables the conservative stack scanning used
 	for asynchronously preempted goroutines.
 
-The net and net/http packages also refer to debugging variables in GODEBUG.
+The [net] and [net/http] packages also refer to debugging variables in GODEBUG.
 See the documentation for those packages for details.
 
 The GOMAXPROCS variable limits the number of operating system threads that
 can execute user-level Go code simultaneously. There is no limit to the number of threads
 that can be blocked in system calls on behalf of Go code; those do not count against
-the GOMAXPROCS limit. This package's GOMAXPROCS function queries and changes
+the GOMAXPROCS limit. This package's [GOMAXPROCS] function queries and changes
 the limit.
 
 The GORACE variable configures the race detector, for programs built using -race.
-See https://golang.org/doc/articles/race_detector.html for details.
+See the [Race Detector article] for details.
 
 The GOTRACEBACK variable controls the amount of output generated when a Go
 program fails due to an unrecovered panic or an unexpected runtime condition.
@@ -244,14 +244,13 @@ SIGABRT to trigger a core dump.
 GOTRACEBACK=wer is like “crash” but doesn't disable Windows Error Reporting (WER).
 For historical reasons, the GOTRACEBACK settings 0, 1, and 2 are synonyms for
 none, all, and system, respectively.
-The runtime/debug package's SetTraceback function allows increasing the
+The [runtime/debug.SetTraceback] function allows increasing the
 amount of output at run time, but it cannot reduce the amount below that
 specified by the environment variable.
-See https://golang.org/pkg/runtime/debug/#SetTraceback.
 
 The GOARCH, GOOS, GOPATH, and GOROOT environment variables complete
 the set of Go environment variables. They influence the building of Go programs
-(see https://golang.org/cmd/go and https://golang.org/pkg/go/build).
+(see [cmd/go] and [go/build]).
 GOARCH, GOOS, and GOROOT are recorded at compile time and made available by
 constants or functions in this package, but they do not influence the execution
 of the run-time system.
@@ -274,6 +273,8 @@ things:
     encounters an unrecoverable panic that would otherwise override the value
     of GOTRACEBACK, the goroutine stack, registers, and other memory related
     information are omitted.
+
+[Race Detector article]: https://go.dev/doc/articles/race_detector
 */
 package runtime
 
@@ -285,7 +286,7 @@ import (
 // Caller reports file and line number information about function invocations on
 // the calling goroutine's stack. The argument skip is the number of stack frames
 // to ascend, with 0 identifying the caller of Caller.  (For historical reasons the
-// meaning of skip differs between Caller and Callers.) The return values report the
+// meaning of skip differs between Caller and [Callers].) The return values report the
 // program counter, file name, and line number within the file of the corresponding
 // call. The boolean ok is false if it was not possible to recover the information.
 func Caller(skip int) (pc uintptr, file string, line int, ok bool) {
diff --git a/src/runtime/mprof.go b/src/runtime/mprof.go
index e5c11c58c9..abdd2f3e8c 100644
--- a/src/runtime/mprof.go
+++ b/src/runtime/mprof.go
@@ -981,8 +981,8 @@ type BlockProfileRecord struct {
 // If len(p) >= n, BlockProfile copies the profile into p and returns n, true.
 // If len(p) < n, BlockProfile does not change p and returns n, false.
 //
-// Most clients should use the runtime/pprof package or
-// the testing package's -test.blockprofile flag instead
+// Most clients should use the [runtime/pprof] package or
+// the [testing] package's -test.blockprofile flag instead
 // of calling BlockProfile directly.
 func BlockProfile(p []BlockProfileRecord) (n int, ok bool) {
 	lock(&profBlockLock)
diff --git a/src/runtime/pinner.go b/src/runtime/pinner.go
index ea5b909aea..1ede1113ee 100644
--- a/src/runtime/pinner.go
+++ b/src/runtime/pinner.go
@@ -10,8 +10,8 @@ import (
 )
 
 // A Pinner is a set of Go objects each pinned to a fixed location in memory. The
-// [Pin] method pins one object, while [Unpin] unpins all pinned objects. See their
-// comments for more information.
+// [Pinner.Pin] method pins one object, while [Pinner.Unpin] unpins all pinned
+// objects. See their comments for more information.
 type Pinner struct {
 	*pinner
 }
diff --git a/src/runtime/proc.go b/src/runtime/proc.go
index c487da652e..c2676c43b2 100644
--- a/src/runtime/proc.go
+++ b/src/runtime/proc.go
@@ -5166,7 +5166,7 @@ func dolockOSThread() {
 // The calling goroutine will always execute in that thread,
 // and no other goroutine will execute in it,
 // until the calling goroutine has made as many calls to
-// UnlockOSThread as to LockOSThread.
+// [UnlockOSThread] as to LockOSThread.
 // If the calling goroutine exits without unlocking the thread,
 // the thread will be terminated.
 //
diff --git a/src/runtime/symtab.go b/src/runtime/symtab.go
index 8b878525d0..edf800f519 100644
--- a/src/runtime/symtab.go
+++ b/src/runtime/symtab.go
@@ -23,7 +23,7 @@ type Frames struct {
 	frameStore [2]Frame
 }
 
-// Frame is the information returned by Frames for each call frame.
+// Frame is the information returned by [Frames] for each call frame.
 type Frame struct {
 	// PC is the program counter for the location in this frame.
 	// For a frame that calls another frame, this will be the
@@ -79,15 +79,15 @@ func CallersFrames(callers []uintptr) *Frames {
 	return f
 }
 
-// Next returns a Frame representing the next call frame in the slice
+// Next returns a [Frame] representing the next call frame in the slice
 // of PC values. If it has already returned all call frames, Next
-// returns a zero Frame.
+// returns a zero [Frame].
 //
 // The more result indicates whether the next call to Next will return
-// a valid Frame. It does not necessarily indicate whether this call
+// a valid [Frame]. It does not necessarily indicate whether this call
 // returned one.
 //
-// See the Frames example for idiomatic usage.
+// See the [Frames] example for idiomatic usage.
 func (ci *Frames) Next() (frame Frame, more bool) {
 	for len(ci.frames) < 2 {
 		// Find the next frame.
diff --git a/src/runtime/trace.go b/src/runtime/trace.go
index b4ad9a638c..a9cfa22337 100644
--- a/src/runtime/trace.go
+++ b/src/runtime/trace.go
@@ -324,9 +324,9 @@ func traceRelease(tl traceLocker) {
 }
 
 // StartTrace enables tracing for the current process.
-// While tracing, the data will be buffered and available via ReadTrace.
+// While tracing, the data will be buffered and available via [ReadTrace].
 // StartTrace returns an error if tracing is already enabled.
-// Most clients should use the runtime/trace package or the testing package's
+// Most clients should use the [runtime/trace] package or the [testing] package's
 // -test.trace flag instead of calling StartTrace directly.
 func StartTrace() error {
 	// Stop the world so that we can take a consistent snapshot
diff --git a/src/runtime/trace2.go b/src/runtime/trace2.go
index c2a1c1ca1e..5fd09ed1ea 100644
--- a/src/runtime/trace2.go
+++ b/src/runtime/trace2.go
@@ -123,9 +123,9 @@ var (
 )
 
 // StartTrace enables tracing for the current process.
-// While tracing, the data will be buffered and available via ReadTrace.
+// While tracing, the data will be buffered and available via [ReadTrace].
 // StartTrace returns an error if tracing is already enabled.
-// Most clients should use the runtime/trace package or the testing package's
+// Most clients should use the [runtime/trace] package or the [testing] package's
 // -test.trace flag instead of calling StartTrace directly.
 func StartTrace() error {
 	if traceEnabled() || traceShuttingDown() {