From: cui fliter <imcusg@gmail.com>
Date: Fri, 13 Oct 2023 16:45:28 +0000 (+0800)
Subject: go: add available godoc link
X-Git-Tag: go1.22rc1~554
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=28f1bf61b7383bd4079d77090e67b3198b75be12;p=gostls13.git

go: add available godoc link

Change-Id: Ie2e8b56225292ef0a28a25f96b0a57cc198a13e7
Reviewed-on: https://go-review.googlesource.com/c/go/+/535195
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Than McIntosh <thanm@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
---

diff --git a/src/go/ast/ast.go b/src/go/ast/ast.go
index e65ff880ba..ef96cc4a6d 100644
--- a/src/go/ast/ast.go
+++ b/src/go/ast/ast.go
@@ -59,7 +59,7 @@ type Decl interface {
 //
 // The Text field contains the comment text without carriage returns (\r) that
 // may have been present in the source. Because a comment's end position is
-// computed using len(Text), the position reported by End() does not match the
+// computed using len(Text), the position reported by [Comment.End] does not match the
 // true source end position for comments containing carriage returns.
 type Comment struct {
 	Slash token.Pos // position of "/" starting the comment
@@ -192,7 +192,7 @@ func isDirective(c string) bool {
 // A Field represents a Field declaration list in a struct type,
 // a method list in an interface type, or a parameter/result declaration
 // in a signature.
-// Field.Names is nil for unnamed parameters (parameter lists which only contain types)
+// [Field.Names] is nil for unnamed parameters (parameter lists which only contain types)
 // and embedded struct fields. In the latter case, the field name is the type name.
 type Field struct {
 	Doc     *CommentGroup // associated documentation; or nil
@@ -257,7 +257,7 @@ func (f *FieldList) End() token.Pos {
 	return token.NoPos
 }
 
-// NumFields returns the number of parameters or struct fields represented by a FieldList.
+// NumFields returns the number of parameters or struct fields represented by a [FieldList].
 func (f *FieldList) NumFields() int {
 	n := 0
 	if f != nil {
@@ -575,7 +575,7 @@ func (*ChanType) exprNode()      {}
 // ----------------------------------------------------------------------------
 // Convenience functions for Idents
 
-// NewIdent creates a new Ident without position.
+// NewIdent creates a new [Ident] without position.
 // Useful for ASTs generated by code other than the Go parser.
 func NewIdent(name string) *Ident { return &Ident{token.NoPos, name, nil} }
 
@@ -1028,12 +1028,12 @@ func (*FuncDecl) declNode() {}
 // when a File's syntax tree is modified: For printing, comments are interspersed
 // between tokens based on their position. If syntax tree nodes are
 // removed or moved, relevant comments in their vicinity must also be removed
-// (from the File.Comments list) or moved accordingly (by updating their
-// positions). A CommentMap may be used to facilitate some of these operations.
+// (from the [File.Comments] list) or moved accordingly (by updating their
+// positions). A [CommentMap] may be used to facilitate some of these operations.
 //
 // Whether and how a comment is associated with a node depends on the
 // interpretation of the syntax tree by the manipulating program: Except for Doc
-// and Comment comments directly associated with nodes, the remaining comments
+// and [Comment] comments directly associated with nodes, the remaining comments
 // are "free-floating" (see also issues #18593, #20744).
 type File struct {
 	Doc     *CommentGroup // associated documentation; or nil
diff --git a/src/go/ast/commentmap.go b/src/go/ast/commentmap.go
index 4196e475d9..a9488f5072 100644
--- a/src/go/ast/commentmap.go
+++ b/src/go/ast/commentmap.go
@@ -29,7 +29,7 @@ func sortComments(list []*CommentGroup) {
 }
 
 // A CommentMap maps an AST node to a list of comment groups
-// associated with it. See NewCommentMap for a description of
+// associated with it. See [NewCommentMap] for a description of
 // the association.
 type CommentMap map[Node][]*CommentGroup
 
diff --git a/src/go/ast/filter.go b/src/go/ast/filter.go
index c9e733a5a5..5c12ed1614 100644
--- a/src/go/ast/filter.go
+++ b/src/go/ast/filter.go
@@ -21,7 +21,7 @@ func exportFilter(name string) bool {
 // only exported nodes remain: all top-level identifiers which are not exported
 // and their associated information (such as type, initial value, or function
 // body) are removed. Non-exported fields and methods of exported types are
-// stripped. The File.Comments list is not changed.
+// stripped. The [File.Comments] list is not changed.
 //
 // FileExports reports whether there are exported declarations.
 func FileExports(src *File) bool {
@@ -246,7 +246,7 @@ func filterDecl(decl Decl, f Filter, export bool) bool {
 // interface method names, but not from parameter lists) that don't
 // pass through the filter f. If the declaration is empty afterwards,
 // the declaration is removed from the AST. Import declarations are
-// always removed. The File.Comments list is not changed.
+// always removed. The [File.Comments] list is not changed.
 //
 // FilterFile reports whether there are any top-level declarations
 // left after filtering.
@@ -293,7 +293,7 @@ func filterPackage(pkg *Package, f Filter, export bool) bool {
 // ----------------------------------------------------------------------------
 // Merging of package files
 
-// The MergeMode flags control the behavior of MergePackageFiles.
+// The MergeMode flags control the behavior of [MergePackageFiles].
 type MergeMode uint
 
 const (
diff --git a/src/go/ast/print.go b/src/go/ast/print.go
index 85e6943928..d1aad50103 100644
--- a/src/go/ast/print.go
+++ b/src/go/ast/print.go
@@ -14,7 +14,7 @@ import (
 	"reflect"
 )
 
-// A FieldFilter may be provided to Fprint to control the output.
+// A FieldFilter may be provided to [Fprint] to control the output.
 type FieldFilter func(name string, value reflect.Value) bool
 
 // NotNilFilter returns true for field values that are not nil;
@@ -32,7 +32,7 @@ func NotNilFilter(_ string, v reflect.Value) bool {
 // to that file set. Otherwise positions are printed as integer
 // values (file set specific offsets).
 //
-// A non-nil FieldFilter f may be provided to control the output:
+// A non-nil [FieldFilter] f may be provided to control the output:
 // struct fields for which f(fieldname, fieldvalue) is true are
 // printed; all others are filtered from the output. Unexported
 // struct fields are never printed.
diff --git a/src/go/ast/resolve.go b/src/go/ast/resolve.go
index 8d543b450a..b1d0bae12c 100644
--- a/src/go/ast/resolve.go
+++ b/src/go/ast/resolve.go
@@ -58,20 +58,20 @@ func resolve(scope *Scope, ident *Ident) bool {
 // check the map to see if it is already present in the imports map.
 // If so, the Importer can return the map entry. Otherwise, the
 // Importer should load the package data for the given path into
-// a new *Object (pkg), record pkg in the imports map, and then
+// a new *[Object] (pkg), record pkg in the imports map, and then
 // return pkg.
 //
 // Deprecated: use the type checker [go/types] instead; see [Object].
 type Importer func(imports map[string]*Object, path string) (pkg *Object, err error)
 
-// NewPackage creates a new Package node from a set of File nodes. It resolves
+// NewPackage creates a new [Package] node from a set of [File] nodes. It resolves
 // unresolved identifiers across files and updates each file's Unresolved list
 // accordingly. If a non-nil importer and universe scope are provided, they are
 // used to resolve identifiers not declared in any of the package files. Any
 // remaining unresolved identifiers are reported as undeclared. If the files
 // belong to different packages, one package name is selected and files with
 // different package names are reported and then ignored.
-// The result is a package node and a scanner.ErrorList if there were errors.
+// The result is a package node and a [scanner.ErrorList] if there were errors.
 //
 // Deprecated: use the type checker [go/types] instead; see [Object].
 func NewPackage(fset *token.FileSet, files map[string]*File, importer Importer, universe *Scope) (*Package, error) {
diff --git a/src/go/ast/walk.go b/src/go/ast/walk.go
index a293c99a10..87e190f08a 100644
--- a/src/go/ast/walk.go
+++ b/src/go/ast/walk.go
@@ -6,8 +6,8 @@ package ast
 
 import "fmt"
 
-// A Visitor's Visit method is invoked for each node encountered by Walk.
-// If the result visitor w is not nil, Walk visits each of the children
+// A Visitor's Visit method is invoked for each node encountered by [Walk].
+// If the result visitor w is not nil, [Walk] visits each of the children
 // of node with the visitor w, followed by a call of w.Visit(nil).
 type Visitor interface {
 	Visit(node Node) (w Visitor)
diff --git a/src/go/build/build.go b/src/go/build/build.go
index f517138061..9ce3700dc4 100644
--- a/src/go/build/build.go
+++ b/src/go/build/build.go
@@ -495,13 +495,13 @@ func (p *Package) IsCommand() bool {
 	return p.Name == "main"
 }
 
-// ImportDir is like Import but processes the Go package found in
+// ImportDir is like [Import] but processes the Go package found in
 // the named directory.
 func (ctxt *Context) ImportDir(dir string, mode ImportMode) (*Package, error) {
 	return ctxt.Import(".", dir, mode)
 }
 
-// NoGoError is the error used by Import to describe a directory
+// NoGoError is the error used by [Import] to describe a directory
 // containing no buildable Go source files. (It may still contain
 // test files, files hidden by build tags, and so on.)
 type NoGoError struct {
@@ -549,7 +549,7 @@ var installgoroot = godebug.New("installgoroot")
 //   - files with build constraints not satisfied by the context
 //
 // If an error occurs, Import returns a non-nil error and a non-nil
-// *Package containing partial information.
+// *[Package] containing partial information.
 func (ctxt *Context) Import(path string, srcDir string, mode ImportMode) (*Package, error) {
 	p := &Package{
 		ImportPath: path,
@@ -1389,7 +1389,7 @@ func parseWord(data []byte) (word, rest []byte) {
 }
 
 // MatchFile reports whether the file with the given name in the given directory
-// matches the context and would be included in a Package created by ImportDir
+// matches the context and would be included in a [Package] created by [ImportDir]
 // of that directory.
 //
 // MatchFile considers the name of the file and may use ctxt.OpenFile to
diff --git a/src/go/build/constraint/expr.go b/src/go/build/constraint/expr.go
index 505cbffa4c..e59012361b 100644
--- a/src/go/build/constraint/expr.go
+++ b/src/go/build/constraint/expr.go
@@ -17,7 +17,7 @@ import (
 )
 
 // An Expr is a build tag constraint expression.
-// The underlying concrete type is *AndExpr, *OrExpr, *NotExpr, or *TagExpr.
+// The underlying concrete type is *[AndExpr], *[OrExpr], *[NotExpr], or *[TagExpr].
 type Expr interface {
 	// String returns the string form of the expression,
 	// using the boolean syntax used in //go:build lines.
@@ -33,7 +33,7 @@ type Expr interface {
 	isExpr()
 }
 
-// A TagExpr is an Expr for the single tag Tag.
+// A TagExpr is an [Expr] for the single tag Tag.
 type TagExpr struct {
 	Tag string // for example, “linux” or “cgo”
 }
diff --git a/src/go/build/doc.go b/src/go/build/doc.go
index cd1d3fd33e..da11e49f63 100644
--- a/src/go/build/doc.go
+++ b/src/go/build/doc.go
@@ -93,6 +93,6 @@
 // as end-user documentation.
 //
 // "go build" and other commands no longer support binary-only-packages.
-// Import and ImportDir will still set the BinaryOnly flag in packages
+// [Import] and [ImportDir] will still set the BinaryOnly flag in packages
 // containing these comments for use in tools and error messages.
 package build
diff --git a/src/go/constant/value.go b/src/go/constant/value.go
index ae300c7c13..3f1fd3cac8 100644
--- a/src/go/constant/value.go
+++ b/src/go/constant/value.go
@@ -25,7 +25,7 @@ import (
 
 //go:generate stringer -type Kind
 
-// Kind specifies the kind of value represented by a Value.
+// Kind specifies the kind of value represented by a [Value].
 type Kind int
 
 const (
@@ -379,13 +379,13 @@ func smallFloat(x *big.Float) bool {
 // ----------------------------------------------------------------------------
 // Factories
 
-// MakeUnknown returns the Unknown value.
+// MakeUnknown returns the [Unknown] value.
 func MakeUnknown() Value { return unknownVal{} }
 
-// MakeBool returns the Bool value for b.
+// MakeBool returns the [Bool] value for b.
 func MakeBool(b bool) Value { return boolVal(b) }
 
-// MakeString returns the String value for s.
+// MakeString returns the [String] value for s.
 func MakeString(s string) Value {
 	if s == "" {
 		return &emptyString // common case
@@ -395,10 +395,10 @@ func MakeString(s string) Value {
 
 var emptyString stringVal
 
-// MakeInt64 returns the Int value for x.
+// MakeInt64 returns the [Int] value for x.
 func MakeInt64(x int64) Value { return int64Val(x) }
 
-// MakeUint64 returns the Int value for x.
+// MakeUint64 returns the [Int] value for x.
 func MakeUint64(x uint64) Value {
 	if x < 1<<63 {
 		return int64Val(int64(x))
@@ -406,9 +406,9 @@ func MakeUint64(x uint64) Value {
 	return intVal{newInt().SetUint64(x)}
 }
 
-// MakeFloat64 returns the Float value for x.
+// MakeFloat64 returns the [Float] value for x.
 // If x is -0.0, the result is 0.0.
-// If x is not finite, the result is an Unknown.
+// If x is not finite, the result is an [Unknown].
 func MakeFloat64(x float64) Value {
 	if math.IsInf(x, 0) || math.IsNaN(x) {
 		return unknownVal{}
@@ -421,9 +421,9 @@ func MakeFloat64(x float64) Value {
 
 // MakeFromLiteral returns the corresponding integer, floating-point,
 // imaginary, character, or string value for a Go literal string. The
-// tok value must be one of token.INT, token.FLOAT, token.IMAG,
-// token.CHAR, or token.STRING. The final argument must be zero.
-// If the literal string syntax is invalid, the result is an Unknown.
+// tok value must be one of [token.INT], [token.FLOAT], [token.IMAG],
+// [token.CHAR], or [token.STRING]. The final argument must be zero.
+// If the literal string syntax is invalid, the result is an [Unknown].
 func MakeFromLiteral(lit string, tok token.Token, zero uint) Value {
 	if zero != 0 {
 		panic("MakeFromLiteral called with non-zero last argument")
@@ -475,8 +475,8 @@ func MakeFromLiteral(lit string, tok token.Token, zero uint) Value {
 // For unknown arguments the result is the zero value for the respective
 // accessor type, except for Sign, where the result is 1.
 
-// BoolVal returns the Go boolean value of x, which must be a Bool or an Unknown.
-// If x is Unknown, the result is false.
+// BoolVal returns the Go boolean value of x, which must be a [Bool] or an [Unknown].
+// If x is [Unknown], the result is false.
 func BoolVal(x Value) bool {
 	switch x := x.(type) {
 	case boolVal:
@@ -488,8 +488,8 @@ func BoolVal(x Value) bool {
 	}
 }
 
-// StringVal returns the Go string value of x, which must be a String or an Unknown.
-// If x is Unknown, the result is "".
+// StringVal returns the Go string value of x, which must be a [String] or an [Unknown].
+// If x is [Unknown], the result is "".
 func StringVal(x Value) string {
 	switch x := x.(type) {
 	case *stringVal:
@@ -502,8 +502,8 @@ func StringVal(x Value) string {
 }
 
 // Int64Val returns the Go int64 value of x and whether the result is exact;
-// x must be an Int or an Unknown. If the result is not exact, its value is undefined.
-// If x is Unknown, the result is (0, false).
+// x must be an [Int] or an [Unknown]. If the result is not exact, its value is undefined.
+// If x is [Unknown], the result is (0, false).
 func Int64Val(x Value) (int64, bool) {
 	switch x := x.(type) {
 	case int64Val:
@@ -518,8 +518,8 @@ func Int64Val(x Value) (int64, bool) {
 }
 
 // Uint64Val returns the Go uint64 value of x and whether the result is exact;
-// x must be an Int or an Unknown. If the result is not exact, its value is undefined.
-// If x is Unknown, the result is (0, false).
+// x must be an [Int] or an [Unknown]. If the result is not exact, its value is undefined.
+// If x is [Unknown], the result is (0, false).
 func Uint64Val(x Value) (uint64, bool) {
 	switch x := x.(type) {
 	case int64Val:
@@ -533,7 +533,7 @@ func Uint64Val(x Value) (uint64, bool) {
 	}
 }
 
-// Float32Val is like Float64Val but for float32 instead of float64.
+// Float32Val is like [Float64Val] but for float32 instead of float64.
 func Float32Val(x Value) (float32, bool) {
 	switch x := x.(type) {
 	case int64Val:
@@ -555,10 +555,10 @@ func Float32Val(x Value) (float32, bool) {
 }
 
 // Float64Val returns the nearest Go float64 value of x and whether the result is exact;
-// x must be numeric or an Unknown, but not Complex. For values too small (too close to 0)
-// to represent as float64, Float64Val silently underflows to 0. The result sign always
+// x must be numeric or an [Unknown], but not [Complex]. For values too small (too close to 0)
+// to represent as float64, [Float64Val] silently underflows to 0. The result sign always
 // matches the sign of x, even for 0.
-// If x is Unknown, the result is (0, false).
+// If x is [Unknown], the result is (0, false).
 func Float64Val(x Value) (float64, bool) {
 	switch x := x.(type) {
 	case int64Val:
@@ -609,7 +609,7 @@ func Val(x Value) any {
 	}
 }
 
-// Make returns the Value for x.
+// Make returns the [Value] for x.
 //
 //	type of x        result Kind
 //	----------------------------
@@ -640,8 +640,8 @@ func Make(x any) Value {
 }
 
 // BitLen returns the number of bits required to represent
-// the absolute value x in binary representation; x must be an Int or an Unknown.
-// If x is Unknown, the result is 0.
+// the absolute value x in binary representation; x must be an [Int] or an [Unknown].
+// If x is [Unknown], the result is 0.
 func BitLen(x Value) int {
 	switch x := x.(type) {
 	case int64Val:
@@ -660,8 +660,8 @@ func BitLen(x Value) int {
 }
 
 // Sign returns -1, 0, or 1 depending on whether x < 0, x == 0, or x > 0;
-// x must be numeric or Unknown. For complex values x, the sign is 0 if x == 0,
-// otherwise it is != 0. If x is Unknown, the result is 1.
+// x must be numeric or [Unknown]. For complex values x, the sign is 0 if x == 0,
+// otherwise it is != 0. If x is [Unknown], the result is 1.
 func Sign(x Value) int {
 	switch x := x.(type) {
 	case int64Val:
@@ -698,7 +698,7 @@ const (
 )
 
 // Bytes returns the bytes for the absolute value of x in little-
-// endian binary representation; x must be an Int.
+// endian binary representation; x must be an [Int].
 func Bytes(x Value) []byte {
 	var t intVal
 	switch x := x.(type) {
@@ -729,7 +729,7 @@ func Bytes(x Value) []byte {
 	return bytes[:i]
 }
 
-// MakeFromBytes returns the Int value given the bytes of its little-endian
+// MakeFromBytes returns the [Int] value given the bytes of its little-endian
 // binary representation. An empty byte slice argument represents 0.
 func MakeFromBytes(bytes []byte) Value {
 	words := make([]big.Word, (len(bytes)+(wordSize-1))/wordSize)
@@ -759,9 +759,9 @@ func MakeFromBytes(bytes []byte) Value {
 	return makeInt(newInt().SetBits(words[:i]))
 }
 
-// Num returns the numerator of x; x must be Int, Float, or Unknown.
-// If x is Unknown, or if it is too large or small to represent as a
-// fraction, the result is Unknown. Otherwise the result is an Int
+// Num returns the numerator of x; x must be [Int], [Float], or [Unknown].
+// If x is [Unknown], or if it is too large or small to represent as a
+// fraction, the result is [Unknown]. Otherwise the result is an [Int]
 // with the same sign as x.
 func Num(x Value) Value {
 	switch x := x.(type) {
@@ -782,9 +782,9 @@ func Num(x Value) Value {
 	return unknownVal{}
 }
 
-// Denom returns the denominator of x; x must be Int, Float, or Unknown.
-// If x is Unknown, or if it is too large or small to represent as a
-// fraction, the result is Unknown. Otherwise the result is an Int >= 1.
+// Denom returns the denominator of x; x must be [Int], [Float], or [Unknown].
+// If x is [Unknown], or if it is too large or small to represent as a
+// fraction, the result is [Unknown]. Otherwise the result is an [Int] >= 1.
 func Denom(x Value) Value {
 	switch x := x.(type) {
 	case int64Val, intVal:
@@ -804,9 +804,9 @@ func Denom(x Value) Value {
 	return unknownVal{}
 }
 
-// MakeImag returns the Complex value x*i;
-// x must be Int, Float, or Unknown.
-// If x is Unknown, the result is Unknown.
+// MakeImag returns the [Complex] value x*i;
+// x must be [Int], [Float], or [Unknown].
+// If x is [Unknown], the result is [Unknown].
 func MakeImag(x Value) Value {
 	switch x.(type) {
 	case unknownVal:
@@ -819,7 +819,7 @@ func MakeImag(x Value) Value {
 }
 
 // Real returns the real part of x, which must be a numeric or unknown value.
-// If x is Unknown, the result is Unknown.
+// If x is [Unknown], the result is [Unknown].
 func Real(x Value) Value {
 	switch x := x.(type) {
 	case unknownVal, int64Val, intVal, ratVal, floatVal:
@@ -832,7 +832,7 @@ func Real(x Value) Value {
 }
 
 // Imag returns the imaginary part of x, which must be a numeric or unknown value.
-// If x is Unknown, the result is Unknown.
+// If x is [Unknown], the result is [Unknown].
 func Imag(x Value) Value {
 	switch x := x.(type) {
 	case unknownVal:
@@ -849,8 +849,8 @@ func Imag(x Value) Value {
 // ----------------------------------------------------------------------------
 // Numeric conversions
 
-// ToInt converts x to an Int value if x is representable as an Int.
-// Otherwise it returns an Unknown.
+// ToInt converts x to an [Int] value if x is representable as an [Int].
+// Otherwise it returns an [Unknown].
 func ToInt(x Value) Value {
 	switch x := x.(type) {
 	case int64Val, intVal:
@@ -903,8 +903,8 @@ func ToInt(x Value) Value {
 	return unknownVal{}
 }
 
-// ToFloat converts x to a Float value if x is representable as a Float.
-// Otherwise it returns an Unknown.
+// ToFloat converts x to a [Float] value if x is representable as a [Float].
+// Otherwise it returns an [Unknown].
 func ToFloat(x Value) Value {
 	switch x := x.(type) {
 	case int64Val:
@@ -924,8 +924,8 @@ func ToFloat(x Value) Value {
 	return unknownVal{}
 }
 
-// ToComplex converts x to a Complex value if x is representable as a Complex.
-// Otherwise it returns an Unknown.
+// ToComplex converts x to a [Complex] value if x is representable as a [Complex].
+// Otherwise it returns an [Unknown].
 func ToComplex(x Value) Value {
 	switch x := x.(type) {
 	case int64Val, intVal, ratVal, floatVal:
@@ -954,7 +954,7 @@ func is63bit(x int64) bool {
 // UnaryOp returns the result of the unary expression op y.
 // The operation must be defined for the operand.
 // If prec > 0 it specifies the ^ (xor) result size in bits.
-// If y is Unknown, the result is Unknown.
+// If y is [Unknown], the result is [Unknown].
 func UnaryOp(op token.Token, y Value, prec uint) Value {
 	switch op {
 	case token.ADD:
@@ -1093,12 +1093,12 @@ func match0(x, y Value) (_, _ Value) {
 
 // BinaryOp returns the result of the binary expression x op y.
 // The operation must be defined for the operands. If one of the
-// operands is Unknown, the result is Unknown.
-// BinaryOp doesn't handle comparisons or shifts; use Compare
-// or Shift instead.
+// operands is [Unknown], the result is [Unknown].
+// BinaryOp doesn't handle comparisons or shifts; use [Compare]
+// or [Shift] instead.
 //
-// To force integer division of Int operands, use op == token.QUO_ASSIGN
-// instead of token.QUO; the result is guaranteed to be Int in this case.
+// To force integer division of [Int] operands, use op == [token.QUO_ASSIGN]
+// instead of [token.QUO]; the result is guaranteed to be [Int] in this case.
 // Division by zero leads to a run-time panic.
 func BinaryOp(x_ Value, op token.Token, y_ Value) Value {
 	x, y := match(x_, y_)
@@ -1277,8 +1277,8 @@ func mul(x, y Value) Value { return BinaryOp(x, token.MUL, y) }
 func quo(x, y Value) Value { return BinaryOp(x, token.QUO, y) }
 
 // Shift returns the result of the shift expression x op s
-// with op == token.SHL or token.SHR (<< or >>). x must be
-// an Int or an Unknown. If x is Unknown, the result is x.
+// with op == [token.SHL] or [token.SHR] (<< or >>). x must be
+// an [Int] or an [Unknown]. If x is [Unknown], the result is x.
 func Shift(x Value, op token.Token, s uint) Value {
 	switch x := x.(type) {
 	case unknownVal:
@@ -1332,7 +1332,7 @@ func cmpZero(x int, op token.Token) bool {
 
 // Compare returns the result of the comparison x op y.
 // The comparison must be defined for the operands.
-// If one of the operands is Unknown, the result is
+// If one of the operands is [Unknown], the result is
 // false.
 func Compare(x_ Value, op token.Token, y_ Value) bool {
 	x, y := match(x_, y_)
diff --git a/src/go/doc/comment/html.go b/src/go/doc/comment/html.go
index bc076f6a58..9244509e00 100644
--- a/src/go/doc/comment/html.go
+++ b/src/go/doc/comment/html.go
@@ -10,13 +10,13 @@ import (
 	"strconv"
 )
 
-// An htmlPrinter holds the state needed for printing a Doc as HTML.
+// An htmlPrinter holds the state needed for printing a [Doc] as HTML.
 type htmlPrinter struct {
 	*Printer
 	tight bool
 }
 
-// HTML returns an HTML formatting of the Doc.
+// HTML returns an HTML formatting of the [Doc].
 // See the [Printer] documentation for ways to customize the HTML output.
 func (p *Printer) HTML(d *Doc) []byte {
 	hp := &htmlPrinter{Printer: p}
diff --git a/src/go/doc/comment/parse.go b/src/go/doc/comment/parse.go
index dd001ec398..4d5784a8b4 100644
--- a/src/go/doc/comment/parse.go
+++ b/src/go/doc/comment/parse.go
@@ -176,7 +176,7 @@ type DocLink struct {
 func (*DocLink) text() {}
 
 // A Parser is a doc comment parser.
-// The fields in the struct can be filled in before calling Parse
+// The fields in the struct can be filled in before calling [Parser.Parse]
 // in order to customize the details of the parsing process.
 type Parser struct {
 	// Words is a map of Go identifier words that
@@ -265,7 +265,7 @@ func isStdPkg(path string) bool {
 }
 
 // DefaultLookupPackage is the default package lookup
-// function, used when [Parser].LookupPackage is nil.
+// function, used when [Parser.LookupPackage] is nil.
 // It recognizes names of the packages from the standard
 // library with single-element import paths, such as math,
 // which would otherwise be impossible to name.
@@ -279,7 +279,7 @@ func DefaultLookupPackage(name string) (importPath string, ok bool) {
 	return "", false
 }
 
-// Parse parses the doc comment text and returns the *Doc form.
+// Parse parses the doc comment text and returns the *[Doc] form.
 // Comment markers (/* // and */) in the text must have already been removed.
 func (p *Parser) Parse(text string) *Doc {
 	lines := unindent(strings.Split(text, "\n"))
diff --git a/src/go/doc/comment/print.go b/src/go/doc/comment/print.go
index e1c070d5a5..a6ae8210b6 100644
--- a/src/go/doc/comment/print.go
+++ b/src/go/doc/comment/print.go
@@ -150,7 +150,7 @@ type commentPrinter struct {
 	*Printer
 }
 
-// Comment returns the standard Go formatting of the Doc,
+// Comment returns the standard Go formatting of the [Doc],
 // without any comment markers.
 func (p *Printer) Comment(d *Doc) []byte {
 	cp := &commentPrinter{Printer: p}
diff --git a/src/go/doc/comment/text.go b/src/go/doc/comment/text.go
index 6f9c2e201d..4e4214e08e 100644
--- a/src/go/doc/comment/text.go
+++ b/src/go/doc/comment/text.go
@@ -21,7 +21,7 @@ type textPrinter struct {
 	width      int
 }
 
-// Text returns a textual formatting of the Doc.
+// Text returns a textual formatting of the [Doc].
 // See the [Printer] documentation for ways to customize the text output.
 func (p *Printer) Text(d *Doc) []byte {
 	tp := &textPrinter{
diff --git a/src/go/doc/doc.go b/src/go/doc/doc.go
index eefadfa932..4d01ae458b 100644
--- a/src/go/doc/doc.go
+++ b/src/go/doc/doc.go
@@ -96,7 +96,7 @@ type Note struct {
 	Body     string    // note body text
 }
 
-// Mode values control the operation of New and NewFromFiles.
+// Mode values control the operation of [New] and [NewFromFiles].
 type Mode int
 
 const (
@@ -116,7 +116,7 @@ const (
 
 // New computes the package documentation for the given package AST.
 // New takes ownership of the AST pkg and may edit or overwrite it.
-// To have the Examples fields populated, use NewFromFiles and include
+// To have the [Examples] fields populated, use [NewFromFiles] and include
 // the package's _test.go files.
 func New(pkg *ast.Package, importPath string, mode Mode) *Package {
 	var r reader
@@ -198,9 +198,9 @@ func (p *Package) collectFuncs(funcs []*Func) {
 // Examples found in _test.go files are associated with the corresponding
 // type, function, method, or the package, based on their name.
 // If the example has a suffix in its name, it is set in the
-// Example.Suffix field. Examples with malformed names are skipped.
+// [Example.Suffix] field. [Examples] with malformed names are skipped.
 //
-// Optionally, a single extra argument of type Mode can be provided to
+// Optionally, a single extra argument of type [Mode] can be provided to
 // control low-level aspects of the documentation extraction behavior.
 //
 // NewFromFiles takes ownership of the AST files and may edit them,
diff --git a/src/go/doc/example.go b/src/go/doc/example.go
index 65ca88540f..6687ba8614 100644
--- a/src/go/doc/example.go
+++ b/src/go/doc/example.go
@@ -35,7 +35,7 @@ type Example struct {
 // Examples returns the examples found in testFiles, sorted by Name field.
 // The Order fields record the order in which the examples were encountered.
 // The Suffix field is not populated when Examples is called directly, it is
-// only populated by NewFromFiles for examples it finds in _test.go files.
+// only populated by [NewFromFiles] for examples it finds in _test.go files.
 //
 // Playable Examples must be in a package whose name ends in "_test".
 // An Example is "playable" (the Play field is non-nil) in either of these
diff --git a/src/go/doc/synopsis.go b/src/go/doc/synopsis.go
index 3c9e7e9b9e..159bed5539 100644
--- a/src/go/doc/synopsis.go
+++ b/src/go/doc/synopsis.go
@@ -54,7 +54,7 @@ var IllegalPrefixes = []string{
 // That sentence ends after the first period followed by space and not
 // preceded by exactly one uppercase letter, or at the first paragraph break.
 // The result string has no \n, \r, or \t characters and uses only single
-// spaces between words. If text starts with any of the IllegalPrefixes,
+// spaces between words. If text starts with any of the [IllegalPrefixes],
 // the result is the empty string.
 func (p *Package) Synopsis(text string) string {
 	text = firstSentence(text)
diff --git a/src/go/format/format.go b/src/go/format/format.go
index 3837cb4617..01e3f00410 100644
--- a/src/go/format/format.go
+++ b/src/go/format/format.go
@@ -42,11 +42,11 @@ const parserMode = parser.ParseComments | parser.SkipObjectResolution
 
 // Node formats node in canonical gofmt style and writes the result to dst.
 //
-// The node type must be *ast.File, *printer.CommentedNode, []ast.Decl,
-// []ast.Stmt, or assignment-compatible to ast.Expr, ast.Decl, ast.Spec,
-// or ast.Stmt. Node does not modify node. Imports are not sorted for
+// The node type must be *[ast.File], *[printer.CommentedNode], [][ast.Decl],
+// [][ast.Stmt], or assignment-compatible to [ast.Expr], [ast.Decl], [ast.Spec],
+// or [ast.Stmt]. Node does not modify node. Imports are not sorted for
 // nodes representing partial source files (for instance, if the node is
-// not an *ast.File or a *printer.CommentedNode not wrapping an *ast.File).
+// not an *[ast.File] or a *[printer.CommentedNode] not wrapping an *[ast.File]).
 //
 // The function may return early (before the entire result is written)
 // and return a formatting error, for instance due to an incorrect AST.
diff --git a/src/go/importer/importer.go b/src/go/importer/importer.go
index 23118d366e..8a8fb0ec04 100644
--- a/src/go/importer/importer.go
+++ b/src/go/importer/importer.go
@@ -69,16 +69,16 @@ func ForCompiler(fset *token.FileSet, compiler string, lookup Lookup) types.Impo
 	return nil
 }
 
-// For calls ForCompiler with a new FileSet.
+// For calls [ForCompiler] with a new FileSet.
 //
-// Deprecated: Use ForCompiler, which populates a FileSet
+// Deprecated: Use [ForCompiler], which populates a FileSet
 // with the positions of objects created by the importer.
 func For(compiler string, lookup Lookup) types.Importer {
 	return ForCompiler(token.NewFileSet(), compiler, lookup)
 }
 
 // Default returns an Importer for the compiler that built the running binary.
-// If available, the result implements types.ImporterFrom.
+// If available, the result implements [types.ImporterFrom].
 func Default() types.Importer {
 	return For(runtime.Compiler, nil)
 }
diff --git a/src/go/parser/interface.go b/src/go/parser/interface.go
index d695162f2c..11d42642f0 100644
--- a/src/go/parser/interface.go
+++ b/src/go/parser/interface.go
@@ -58,16 +58,16 @@ const (
 )
 
 // ParseFile parses the source code of a single Go source file and returns
-// the corresponding ast.File node. The source code may be provided via
+// the corresponding [ast.File] node. The source code may be provided via
 // the filename of the source file, or via the src parameter.
 //
 // If src != nil, ParseFile parses the source from src and the filename is
 // only used when recording position information. The type of the argument
-// for the src parameter must be string, []byte, or io.Reader.
+// for the src parameter must be string, []byte, or [io.Reader].
 // If src == nil, ParseFile parses the file specified by filename.
 //
 // The mode parameter controls the amount of source text parsed and
-// other optional parser functionality. If the SkipObjectResolution
+// other optional parser functionality. If the [SkipObjectResolution]
 // mode bit is set (recommended), the object resolution phase of
 // parsing will be skipped, causing File.Scope, File.Unresolved, and
 // all Ident.Obj fields to be nil. Those fields are deprecated; see
@@ -78,7 +78,7 @@ const (
 //
 // If the source couldn't be read, the returned AST is nil and the error
 // indicates the specific failure. If the source was read but syntax
-// errors were found, the result is a partial AST (with ast.Bad* nodes
+// errors were found, the result is a partial AST (with [ast.Bad]* nodes
 // representing the fragments of erroneous source code). Multiple errors
 // are returned via a scanner.ErrorList which is sorted by source position.
 func ParseFile(fset *token.FileSet, filename string, src any, mode Mode) (f *ast.File, err error) {
@@ -126,13 +126,13 @@ func ParseFile(fset *token.FileSet, filename string, src any, mode Mode) (f *ast
 	return
 }
 
-// ParseDir calls ParseFile for all files with names ending in ".go" in the
+// ParseDir calls [ParseFile] for all files with names ending in ".go" in the
 // directory specified by path and returns a map of package name -> package
 // AST with all the packages found.
 //
-// If filter != nil, only the files with fs.FileInfo entries passing through
+// If filter != nil, only the files with [fs.FileInfo] entries passing through
 // the filter (and ending in ".go") are considered. The mode bits are passed
-// to ParseFile unchanged. Position information is recorded in fset, which
+// to [ParseFile] unchanged. Position information is recorded in fset, which
 // must not be nil.
 //
 // If the directory couldn't be read, a nil map and the respective error are
@@ -179,13 +179,13 @@ func ParseDir(fset *token.FileSet, path string, filter func(fs.FileInfo) bool, m
 }
 
 // ParseExprFrom is a convenience function for parsing an expression.
-// The arguments have the same meaning as for ParseFile, but the source must
+// The arguments have the same meaning as for [ParseFile], but the source must
 // be a valid Go (type or value) expression. Specifically, fset must not
 // be nil.
 //
 // If the source couldn't be read, the returned AST is nil and the error
 // indicates the specific failure. If the source was read but syntax
-// errors were found, the result is a partial AST (with ast.Bad* nodes
+// errors were found, the result is a partial AST (with [ast.Bad]* nodes
 // representing the fragments of erroneous source code). Multiple errors
 // are returned via a scanner.ErrorList which is sorted by source position.
 func ParseExprFrom(fset *token.FileSet, filename string, src any, mode Mode) (expr ast.Expr, err error) {
@@ -232,7 +232,7 @@ func ParseExprFrom(fset *token.FileSet, filename string, src any, mode Mode) (ex
 // The position information recorded in the AST is undefined. The filename used
 // in error messages is the empty string.
 //
-// If syntax errors were found, the result is a partial AST (with ast.Bad* nodes
+// If syntax errors were found, the result is a partial AST (with [ast.Bad]* nodes
 // representing the fragments of erroneous source code). Multiple errors are
 // returned via a scanner.ErrorList which is sorted by source position.
 func ParseExpr(x string) (ast.Expr, error) {
diff --git a/src/go/printer/printer.go b/src/go/printer/printer.go
index ff36d58140..32be3d67dd 100644
--- a/src/go/printer/printer.go
+++ b/src/go/printer/printer.go
@@ -1410,7 +1410,7 @@ func (cfg *Config) fprint(output io.Writer, fset *token.FileSet, node any, nodeS
 }
 
 // A CommentedNode bundles an AST node and corresponding comments.
-// It may be provided as argument to any of the Fprint functions.
+// It may be provided as argument to any of the [Fprint] functions.
 type CommentedNode struct {
 	Node     any // *ast.File, or ast.Expr, ast.Decl, ast.Spec, or ast.Stmt
 	Comments []*ast.CommentGroup
@@ -1418,14 +1418,14 @@ type CommentedNode struct {
 
 // Fprint "pretty-prints" an AST node to output for a given configuration cfg.
 // Position information is interpreted relative to the file set fset.
-// The node type must be *ast.File, *CommentedNode, []ast.Decl, []ast.Stmt,
-// or assignment-compatible to ast.Expr, ast.Decl, ast.Spec, or ast.Stmt.
+// The node type must be *[ast.File], *[CommentedNode], [][ast.Decl], [][ast.Stmt],
+// or assignment-compatible to [ast.Expr], [ast.Decl], [ast.Spec], or [ast.Stmt].
 func (cfg *Config) Fprint(output io.Writer, fset *token.FileSet, node any) error {
 	return cfg.fprint(output, fset, node, make(map[ast.Node]int))
 }
 
 // Fprint "pretty-prints" an AST node to output.
-// It calls Config.Fprint with default settings.
+// It calls [Config.Fprint] with default settings.
 // Note that gofmt uses tabs for indentation but spaces for alignment;
 // use format.Node (package go/format) for output that matches gofmt.
 func Fprint(output io.Writer, fset *token.FileSet, node any) error {
diff --git a/src/go/scanner/errors.go b/src/go/scanner/errors.go
index 3e9c365cca..3230f1339a 100644
--- a/src/go/scanner/errors.go
+++ b/src/go/scanner/errors.go
@@ -11,7 +11,7 @@ import (
 	"sort"
 )
 
-// In an ErrorList, an error is represented by an *Error.
+// In an [ErrorList], an error is represented by an *Error.
 // The position Pos, if valid, points to the beginning of
 // the offending token, and the error condition is described
 // by Msg.
@@ -34,15 +34,15 @@ func (e Error) Error() string {
 // The zero value for an ErrorList is an empty ErrorList ready to use.
 type ErrorList []*Error
 
-// Add adds an Error with given position and error message to an ErrorList.
+// Add adds an [Error] with given position and error message to an [ErrorList].
 func (p *ErrorList) Add(pos token.Position, msg string) {
 	*p = append(*p, &Error{pos, msg})
 }
 
-// Reset resets an ErrorList to no errors.
+// Reset resets an [ErrorList] to no errors.
 func (p *ErrorList) Reset() { *p = (*p)[0:0] }
 
-// ErrorList implements the sort Interface.
+// [ErrorList] implements the sort Interface.
 func (p ErrorList) Len() int      { return len(p) }
 func (p ErrorList) Swap(i, j int) { p[i], p[j] = p[j], p[i] }
 
@@ -64,14 +64,14 @@ func (p ErrorList) Less(i, j int) bool {
 	return p[i].Msg < p[j].Msg
 }
 
-// Sort sorts an ErrorList. *Error entries are sorted by position,
-// other errors are sorted by error message, and before any *Error
+// Sort sorts an [ErrorList]. *[Error] entries are sorted by position,
+// other errors are sorted by error message, and before any *[Error]
 // entry.
 func (p ErrorList) Sort() {
 	sort.Sort(p)
 }
 
-// RemoveMultiples sorts an ErrorList and removes all but the first error per line.
+// RemoveMultiples sorts an [ErrorList] and removes all but the first error per line.
 func (p *ErrorList) RemoveMultiples() {
 	sort.Sort(p)
 	var last token.Position // initial last.Line is != any legal error line
@@ -86,7 +86,7 @@ func (p *ErrorList) RemoveMultiples() {
 	*p = (*p)[0:i]
 }
 
-// An ErrorList implements the error interface.
+// An [ErrorList] implements the error interface.
 func (p ErrorList) Error() string {
 	switch len(p) {
 	case 0:
@@ -107,7 +107,7 @@ func (p ErrorList) Err() error {
 }
 
 // PrintError is a utility function that prints a list of errors to w,
-// one error per line, if the err parameter is an ErrorList. Otherwise
+// one error per line, if the err parameter is an [ErrorList]. Otherwise
 // it prints the err string.
 func PrintError(w io.Writer, err error) {
 	if list, ok := err.(ErrorList); ok {
diff --git a/src/go/scanner/scanner.go b/src/go/scanner/scanner.go
index 8742c29906..8ca74667fc 100644
--- a/src/go/scanner/scanner.go
+++ b/src/go/scanner/scanner.go
@@ -17,7 +17,7 @@ import (
 	"unicode/utf8"
 )
 
-// An ErrorHandler may be provided to Scanner.Init. If a syntax error is
+// An ErrorHandler may be provided to [Scanner.Init]. If a syntax error is
 // encountered and a handler was installed, the handler is called with a
 // position and an error message. The position points to the beginning of
 // the offending token.
@@ -25,7 +25,7 @@ type ErrorHandler func(pos token.Position, msg string)
 
 // A Scanner holds the scanner's internal state while processing
 // a given text. It can be allocated as part of another data
-// structure but must be initialized via Init before use.
+// structure but must be initialized via [Scanner.Init] before use.
 type Scanner struct {
 	// immutable state
 	file *token.File  // source file handle
@@ -113,9 +113,9 @@ const (
 // line information which is already present is ignored. Init causes a
 // panic if the file size does not match the src size.
 //
-// Calls to Scan will invoke the error handler err if they encounter a
+// Calls to [Scanner.Scan] will invoke the error handler err if they encounter a
 // syntax error and err is not nil. Also, for each error encountered,
-// the Scanner field ErrorCount is incremented by one. The mode parameter
+// the [Scanner] field ErrorCount is incremented by one. The mode parameter
 // determines how comments are handled.
 //
 // Note that Init may call err if there is an error in the first character
@@ -759,20 +759,20 @@ func (s *Scanner) switch4(tok0, tok1 token.Token, ch2 rune, tok2, tok3 token.Tok
 
 // Scan scans the next token and returns the token position, the token,
 // and its literal string if applicable. The source end is indicated by
-// token.EOF.
+// [token.EOF].
 //
-// If the returned token is a literal (token.IDENT, token.INT, token.FLOAT,
-// token.IMAG, token.CHAR, token.STRING) or token.COMMENT, the literal string
+// If the returned token is a literal ([token.IDENT], [token.INT], [token.FLOAT],
+// [token.IMAG], [token.CHAR], [token.STRING]) or [token.COMMENT], the literal string
 // has the corresponding value.
 //
 // If the returned token is a keyword, the literal string is the keyword.
 //
-// If the returned token is token.SEMICOLON, the corresponding
+// If the returned token is [token.SEMICOLON], the corresponding
 // literal string is ";" if the semicolon was present in the source,
 // and "\n" if the semicolon was inserted because of a newline or
 // at EOF.
 //
-// If the returned token is token.ILLEGAL, the literal string is the
+// If the returned token is [token.ILLEGAL], the literal string is the
 // offending character.
 //
 // In all other cases, Scan returns an empty literal string.
diff --git a/src/go/token/position.go b/src/go/token/position.go
index a644382886..0b2ace0b69 100644
--- a/src/go/token/position.go
+++ b/src/go/token/position.go
@@ -54,7 +54,7 @@ func (pos Position) String() string {
 }
 
 // Pos is a compact encoding of a source position within a file set.
-// It can be converted into a Position for a more convenient, but much
+// It can be converted into a [Position] for a more convenient, but much
 // larger, representation.
 //
 // The Pos value for a given file is a number in the range [base, base+size],
@@ -65,9 +65,9 @@ func (pos Position) String() string {
 // representing the first byte in the file.
 //
 // To create the Pos value for a specific source offset (measured in bytes),
-// first add the respective file to the current file set using FileSet.AddFile
-// and then call File.Pos(offset) for that file. Given a Pos value p
-// for a specific file set fset, the corresponding Position value is
+// first add the respective file to the current file set using [FileSet.AddFile]
+// and then call [File.Pos](offset) for that file. Given a Pos value p
+// for a specific file set fset, the corresponding [Position] value is
 // obtained by calling fset.Position(p).
 //
 // Pos values can be compared directly with the usual comparison operators:
@@ -77,10 +77,10 @@ func (pos Position) String() string {
 // to the respective file set before the file implied by q.
 type Pos int
 
-// The zero value for Pos is NoPos; there is no file and line information
+// The zero value for [Pos] is NoPos; there is no file and line information
 // associated with it, and NoPos.IsValid() is false. NoPos is always
-// smaller than any other Pos value. The corresponding Position value
-// for NoPos is the zero value for Position.
+// smaller than any other [Pos] value. The corresponding [Position] value
+// for NoPos is the zero value for [Position].
 const NoPos Pos = 0
 
 // IsValid reports whether the position is valid.
@@ -91,7 +91,7 @@ func (p Pos) IsValid() bool {
 // -----------------------------------------------------------------------------
 // File
 
-// A File is a handle for a file belonging to a FileSet.
+// A File is a handle for a file belonging to a [FileSet].
 // A File has a name, size, and line offset table.
 type File struct {
 	name string // file name as provided to AddFile
@@ -140,7 +140,7 @@ func (f *File) AddLine(offset int) {
 
 // MergeLine merges a line with the following line. It is akin to replacing
 // the newline character at the end of the line with a space (to not change the
-// remaining offsets). To obtain the line number, consult e.g. Position.Line.
+// remaining offsets). To obtain the line number, consult e.g. [Position.Line].
 // MergeLine will panic if given an invalid line number.
 func (f *File) MergeLine(line int) {
 	if line < 1 {
@@ -160,7 +160,7 @@ func (f *File) MergeLine(line int) {
 	f.lines = f.lines[:len(f.lines)-1]
 }
 
-// Lines returns the effective line offset table of the form described by SetLines.
+// Lines returns the effective line offset table of the form described by [File.SetLines].
 // Callers must not mutate the result.
 func (f *File) Lines() []int {
 	f.mutex.Lock()
@@ -214,8 +214,8 @@ func (f *File) SetLinesForContent(content []byte) {
 	f.mutex.Unlock()
 }
 
-// LineStart returns the Pos value of the start of the specified line.
-// It ignores any alternative positions set using AddLineColumnInfo.
+// LineStart returns the [Pos] value of the start of the specified line.
+// It ignores any alternative positions set using [File.AddLineColumnInfo].
 // LineStart panics if the 1-based line number is invalid.
 func (f *File) LineStart(line int) Pos {
 	if line < 1 {
@@ -239,7 +239,7 @@ type lineInfo struct {
 	Line, Column int
 }
 
-// AddLineInfo is like AddLineColumnInfo with a column = 1 argument.
+// AddLineInfo is like [File.AddLineColumnInfo] with a column = 1 argument.
 // It is here for backward-compatibility for code prior to Go 1.11.
 func (f *File) AddLineInfo(offset int, filename string, line int) {
 	f.AddLineColumnInfo(offset, filename, line, 1)
@@ -272,7 +272,7 @@ func (f *File) Pos(offset int) Pos {
 }
 
 // Offset returns the offset for the given file position p;
-// p must be a valid Pos value in that file.
+// p must be a valid [Pos] value in that file.
 // f.Offset(f.Pos(offset)) == offset.
 func (f *File) Offset(p Pos) int {
 	if int(p) < f.base || int(p) > f.base+f.size {
@@ -282,7 +282,7 @@ func (f *File) Offset(p Pos) int {
 }
 
 // Line returns the line number for the given file position p;
-// p must be a Pos value in that file or NoPos.
+// p must be a [Pos] value in that file or [NoPos].
 func (f *File) Line(p Pos) int {
 	return f.Position(p).Line
 }
@@ -365,21 +365,21 @@ func (f *File) Position(p Pos) (pos Position) {
 //
 // The byte offsets for each file in a file set are mapped into
 // distinct (integer) intervals, one interval [base, base+size]
-// per file. Base represents the first byte in the file, and size
-// is the corresponding file size. A Pos value is a value in such
-// an interval. By determining the interval a Pos value belongs
+// per file. [FileSet.Base] represents the first byte in the file, and size
+// is the corresponding file size. A [Pos] value is a value in such
+// an interval. By determining the interval a [Pos] value belongs
 // to, the file, its file base, and thus the byte offset (position)
-// the Pos value is representing can be computed.
+// the [Pos] value is representing can be computed.
 //
 // When adding a new file, a file base must be provided. That can
 // be any integer value that is past the end of any interval of any
-// file already in the file set. For convenience, FileSet.Base provides
+// file already in the file set. For convenience, [FileSet.Base] provides
 // such a value, which is simply the end of the Pos interval of the most
 // recently added file, plus one. Unless there is a need to extend an
-// interval later, using the FileSet.Base should be used as argument
-// for FileSet.AddFile.
+// interval later, using the [FileSet.Base] should be used as argument
+// for [FileSet.AddFile].
 //
-// A File may be removed from a FileSet when it is no longer needed.
+// A [File] may be removed from a FileSet when it is no longer needed.
 // This may reduce memory usage in a long-running application.
 type FileSet struct {
 	mutex sync.RWMutex         // protects the file set
@@ -396,7 +396,7 @@ func NewFileSet() *FileSet {
 }
 
 // Base returns the minimum base offset that must be provided to
-// AddFile when adding the next file.
+// [FileSet.AddFile] when adding the next file.
 func (s *FileSet) Base() int {
 	s.mutex.RLock()
 	b := s.base
@@ -406,18 +406,18 @@ func (s *FileSet) Base() int {
 
 // AddFile adds a new file with a given filename, base offset, and file size
 // to the file set s and returns the file. Multiple files may have the same
-// name. The base offset must not be smaller than the FileSet's Base(), and
+// name. The base offset must not be smaller than the [FileSet.Base], and
 // size must not be negative. As a special case, if a negative base is provided,
-// the current value of the FileSet's Base() is used instead.
+// the current value of the [FileSet.Base] is used instead.
 //
-// Adding the file will set the file set's Base() value to base + size + 1
+// Adding the file will set the file set's [FileSet.Base] value to base + size + 1
 // as the minimum base value for the next file. The following relationship
-// exists between a Pos value p for a given file offset offs:
+// exists between a [Pos] value p for a given file offset offs:
 //
 //	int(p) = base + offs
 //
 // with offs in the range [0, size] and thus p in the range [base, base+size].
-// For convenience, File.Pos may be used to create file-specific position
+// For convenience, [File.Pos] may be used to create file-specific position
 // values from a file offset.
 func (s *FileSet) AddFile(filename string, base, size int) *File {
 	// Allocate f outside the critical section.
@@ -447,9 +447,9 @@ func (s *FileSet) AddFile(filename string, base, size int) *File {
 	return f
 }
 
-// RemoveFile removes a file from the FileSet so that subsequent
-// queries for its Pos interval yield a negative result.
-// This reduces the memory usage of a long-lived FileSet that
+// RemoveFile removes a file from the [FileSet] so that subsequent
+// queries for its [Pos] interval yield a negative result.
+// This reduces the memory usage of a long-lived [FileSet] that
 // encounters an unbounded stream of files.
 //
 // Removing a file that does not belong to the set has no effect.
@@ -510,7 +510,7 @@ func (s *FileSet) file(p Pos) *File {
 }
 
 // File returns the file that contains the position p.
-// If no such file is found (for instance for p == NoPos),
+// If no such file is found (for instance for p == [NoPos]),
 // the result is nil.
 func (s *FileSet) File(p Pos) (f *File) {
 	if p != NoPos {
@@ -519,10 +519,10 @@ func (s *FileSet) File(p Pos) (f *File) {
 	return
 }
 
-// PositionFor converts a Pos p in the fileset into a Position value.
+// PositionFor converts a [Pos] p in the fileset into a [Position] value.
 // If adjusted is set, the position may be adjusted by position-altering
 // //line comments; otherwise those comments are ignored.
-// p must be a Pos value in s or NoPos.
+// p must be a [Pos] value in s or [NoPos].
 func (s *FileSet) PositionFor(p Pos, adjusted bool) (pos Position) {
 	if p != NoPos {
 		if f := s.file(p); f != nil {
@@ -532,7 +532,7 @@ func (s *FileSet) PositionFor(p Pos, adjusted bool) (pos Position) {
 	return
 }
 
-// Position converts a Pos p in the fileset into a Position value.
+// Position converts a [Pos] p in the fileset into a Position value.
 // Calling s.Position(p) is equivalent to calling s.PositionFor(p, true).
 func (s *FileSet) Position(p Pos) (pos Position) {
 	return s.PositionFor(p, true)
diff --git a/src/go/token/token.go b/src/go/token/token.go
index 3ae10d823c..aa5d6e02a6 100644
--- a/src/go/token/token.go
+++ b/src/go/token/token.go
@@ -235,9 +235,9 @@ var tokens = [...]string{
 
 // String returns the string corresponding to the token tok.
 // For operators, delimiters, and keywords the string is the actual
-// token character sequence (e.g., for the token ADD, the string is
+// token character sequence (e.g., for the token [ADD], the string is
 // "+"). For all other tokens the string corresponds to the token
-// constant name (e.g. for the token IDENT, the string is "IDENT").
+// constant name (e.g. for the token [IDENT], the string is "IDENT").
 func (tok Token) String() string {
 	s := ""
 	if 0 <= tok && tok < Token(len(tokens)) {
@@ -288,7 +288,7 @@ func init() {
 	}
 }
 
-// Lookup maps an identifier to its keyword token or IDENT (if not a keyword).
+// Lookup maps an identifier to its keyword token or [IDENT] (if not a keyword).
 func Lookup(ident string) Token {
 	if tok, is_keyword := keywords[ident]; is_keyword {
 		return tok
diff --git a/src/go/types/api.go b/src/go/types/api.go
index a9d6ec02fd..33633ea83c 100644
--- a/src/go/types/api.go
+++ b/src/go/types/api.go
@@ -4,23 +4,23 @@
 
 // Package types declares the data types and implements
 // the algorithms for type-checking of Go packages. Use
-// Config.Check to invoke the type checker for a package.
-// Alternatively, create a new type checker with NewChecker
-// and invoke it incrementally by calling Checker.Files.
+// [Config.Check] to invoke the type checker for a package.
+// Alternatively, create a new type checker with [NewChecker]
+// and invoke it incrementally by calling [Checker.Files].
 //
 // Type-checking consists of several interdependent phases:
 //
 // Name resolution maps each identifier (ast.Ident) in the program to the
-// language object (Object) it denotes.
-// Use Info.{Defs,Uses,Implicits} for the results of name resolution.
+// language object ([Object]) it denotes.
+// Use [Info].{Defs,Uses,Implicits} for the results of name resolution.
 //
 // Constant folding computes the exact constant value (constant.Value)
 // for every expression (ast.Expr) that is a compile-time constant.
 // Use Info.Types[expr].Value for the results of constant folding.
 //
-// Type inference computes the type (Type) of every expression (ast.Expr)
+// [Type] inference computes the type ([Type]) of every expression ([ast.Expr])
 // and checks for compliance with the language specification.
-// Use Info.Types[expr].Type for the results of type inference.
+// Use [Info.Types][expr].Type for the results of type inference.
 //
 // For a tutorial, see https://golang.org/s/types-tutorial.
 package types
@@ -73,7 +73,7 @@ func (e *ArgumentError) Unwrap() error { return e.Err }
 //
 // CAUTION: This interface does not support the import of locally
 // vendored packages. See https://golang.org/s/go15vendor.
-// If possible, external implementations should implement ImporterFrom.
+// If possible, external implementations should implement [ImporterFrom].
 type Importer interface {
 	// Import returns the imported package for the given import path.
 	// The semantics is like for ImporterFrom.ImportFrom except that
@@ -314,8 +314,8 @@ func (info *Info) TypeOf(e ast.Expr) Type {
 // ObjectOf returns the object denoted by the specified id,
 // or nil if not found.
 //
-// If id is an embedded struct field, ObjectOf returns the field (*Var)
-// it defines, not the type (*TypeName) it uses.
+// If id is an embedded struct field, [Info.ObjectOf] returns the field (*[Var])
+// it defines, not the type (*[TypeName]) it uses.
 //
 // Precondition: the Uses and Defs maps are populated.
 func (info *Info) ObjectOf(id *ast.Ident) Object {
@@ -386,8 +386,8 @@ func (tv TypeAndValue) HasOk() bool {
 }
 
 // Instance reports the type arguments and instantiated type for type and
-// function instantiations. For type instantiations, Type will be of dynamic
-// type *Named. For function instantiations, Type will be of dynamic type
+// function instantiations. For type instantiations, [Type] will be of dynamic
+// type *[Named]. For function instantiations, [Type] will be of dynamic type
 // *Signature.
 type Instance struct {
 	TypeArgs *TypeList
@@ -417,10 +417,10 @@ func (init *Initializer) String() string {
 
 // Check type-checks a package and returns the resulting package object and
 // the first error if any. Additionally, if info != nil, Check populates each
-// of the non-nil maps in the Info struct.
+// of the non-nil maps in the [Info] struct.
 //
 // The package is marked as complete if no errors occurred, otherwise it is
-// incomplete. See Config.Error for controlling behavior in the presence of
+// incomplete. See [Config.Error] for controlling behavior in the presence of
 // errors.
 //
 // The package is specified by a list of *ast.Files and corresponding
@@ -494,14 +494,14 @@ func Satisfies(V Type, T *Interface) bool {
 }
 
 // Identical reports whether x and y are identical types.
-// Receivers of Signature types are ignored.
+// Receivers of [Signature] types are ignored.
 func Identical(x, y Type) bool {
 	var c comparer
 	return c.identical(x, y, nil)
 }
 
 // IdenticalIgnoreTags reports whether x and y are identical types if tags are ignored.
-// Receivers of Signature types are ignored.
+// Receivers of [Signature] types are ignored.
 func IdenticalIgnoreTags(x, y Type) bool {
 	var c comparer
 	c.ignoreTags = true
diff --git a/src/go/types/check.go b/src/go/types/check.go
index 28515aea23..99696de496 100644
--- a/src/go/types/check.go
+++ b/src/go/types/check.go
@@ -90,7 +90,7 @@ type actionDesc struct {
 }
 
 // A Checker maintains the state of the type checker.
-// It must be created with NewChecker.
+// It must be created with [NewChecker].
 type Checker struct {
 	// package information
 	// (initialized by NewChecker, valid for the life-time of checker)
@@ -221,8 +221,8 @@ func (check *Checker) needsCleanup(c cleaner) {
 	check.cleaners = append(check.cleaners, c)
 }
 
-// NewChecker returns a new Checker instance for a given package.
-// Package files may be added incrementally via checker.Files.
+// NewChecker returns a new [Checker] instance for a given package.
+// [Package] files may be added incrementally via checker.Files.
 func NewChecker(conf *Config, fset *token.FileSet, pkg *Package, info *Info) *Checker {
 	// make sure we have a configuration
 	if conf == nil {
diff --git a/src/go/types/eval.go b/src/go/types/eval.go
index ff2af58b30..36184415f1 100644
--- a/src/go/types/eval.go
+++ b/src/go/types/eval.go
@@ -18,7 +18,7 @@ import (
 // set.
 //
 // The meaning of the parameters fset, pkg, and pos is the
-// same as in CheckExpr. An error is returned if expr cannot
+// same as in [CheckExpr]. An error is returned if expr cannot
 // be parsed successfully, or the resulting expr AST cannot be
 // type-checked.
 func Eval(fset *token.FileSet, pkg *Package, pos token.Pos, expr string) (_ TypeAndValue, err error) {
@@ -36,11 +36,11 @@ func Eval(fset *token.FileSet, pkg *Package, pos token.Pos, expr string) (_ Type
 }
 
 // CheckExpr type checks the expression expr as if it had appeared at position
-// pos of package pkg. Type information about the expression is recorded in
+// pos of package pkg. [Type] information about the expression is recorded in
 // info. The expression may be an identifier denoting an uninstantiated generic
 // function or type.
 //
-// If pkg == nil, the Universe scope is used and the provided
+// If pkg == nil, the [Universe] scope is used and the provided
 // position pos is ignored. If pkg != nil, and pos is invalid,
 // the package scope is used. Otherwise, pos must belong to the
 // package.
@@ -48,7 +48,7 @@ func Eval(fset *token.FileSet, pkg *Package, pos token.Pos, expr string) (_ Type
 // An error is returned if pos is not within the package or
 // if the node cannot be type-checked.
 //
-// Note: Eval and CheckExpr should not be used instead of running Check
+// Note: [Eval] and CheckExpr should not be used instead of running Check
 // to compute types and values, but in addition to Check, as these
 // functions ignore the context in which an expression is used (e.g., an
 // assignment). Thus, top-level untyped constants will return an
diff --git a/src/go/types/interface.go b/src/go/types/interface.go
index 0a258ce867..40a0baedd3 100644
--- a/src/go/types/interface.go
+++ b/src/go/types/interface.go
@@ -94,16 +94,16 @@ func (t *Interface) MarkImplicit() {
 func (t *Interface) NumExplicitMethods() int { return len(t.methods) }
 
 // ExplicitMethod returns the i'th explicitly declared method of interface t for 0 <= i < t.NumExplicitMethods().
-// The methods are ordered by their unique Id.
+// The methods are ordered by their unique [Id].
 func (t *Interface) ExplicitMethod(i int) *Func { return t.methods[i] }
 
 // NumEmbeddeds returns the number of embedded types in interface t.
 func (t *Interface) NumEmbeddeds() int { return len(t.embeddeds) }
 
-// Embedded returns the i'th embedded defined (*Named) type of interface t for 0 <= i < t.NumEmbeddeds().
+// Embedded returns the i'th embedded defined (*[Named]) type of interface t for 0 <= i < t.NumEmbeddeds().
 // The result is nil if the i'th embedded type is not a defined type.
 //
-// Deprecated: Use EmbeddedType which is not restricted to defined (*Named) types.
+// Deprecated: Use [Interface.EmbeddedType] which is not restricted to defined (*[Named]) types.
 func (t *Interface) Embedded(i int) *Named { return asNamed(t.embeddeds[i]) }
 
 // EmbeddedType returns the i'th embedded type of interface t for 0 <= i < t.NumEmbeddeds().
@@ -130,7 +130,7 @@ func (t *Interface) IsMethodSet() bool { return t.typeSet().IsMethodSet() }
 func (t *Interface) IsImplicit() bool { return t.implicit }
 
 // Complete computes the interface's type set. It must be called by users of
-// NewInterfaceType and NewInterface after the interface's embedded types are
+// [NewInterfaceType] and [NewInterface] after the interface's embedded types are
 // fully defined and before using the interface type in any way other than to
 // form other types. The interface must not contain duplicate methods or a
 // panic occurs. Complete returns the receiver.
diff --git a/src/go/types/methodset.go b/src/go/types/methodset.go
index 7d272df5f3..ac8f0bdd28 100644
--- a/src/go/types/methodset.go
+++ b/src/go/types/methodset.go
@@ -13,7 +13,7 @@ import (
 )
 
 // A MethodSet is an ordered set of concrete or abstract (interface) methods;
-// a method is a MethodVal selection, and they are ordered by ascending m.Obj().Id().
+// a method is a [MethodVal] selection, and they are ordered by ascending m.Obj().Id().
 // The zero value for a MethodSet is a ready-to-use empty method set.
 type MethodSet struct {
 	list []*Selection
diff --git a/src/go/types/signature.go b/src/go/types/signature.go
index 3c67fd9f15..e34db602f3 100644
--- a/src/go/types/signature.go
+++ b/src/go/types/signature.go
@@ -34,7 +34,7 @@ type Signature struct {
 // is variadic, it must have at least one parameter, and the last parameter
 // must be of unnamed slice type.
 //
-// Deprecated: Use NewSignatureType instead which allows for type parameters.
+// Deprecated: Use [NewSignatureType] instead which allows for type parameters.
 func NewSignature(recv *Var, params, results *Tuple, variadic bool) *Signature {
 	return NewSignatureType(recv, nil, nil, params, results, variadic)
 }
@@ -76,7 +76,7 @@ func NewSignatureType(recv *Var, recvTypeParams, typeParams []*TypeParam, params
 // function. It is ignored when comparing signatures for identity.
 //
 // For an abstract method, Recv returns the enclosing interface either
-// as a *Named or an *Interface. Due to embedding, an interface may
+// as a *[Named] or an *[Interface]. Due to embedding, an interface may
 // contain methods whose receiver type is a different interface.
 func (s *Signature) Recv() *Var { return s.recv }
 
diff --git a/src/go/types/typestring.go b/src/go/types/typestring.go
index cb735f2b49..cab36e4c59 100644
--- a/src/go/types/typestring.go
+++ b/src/go/types/typestring.go
@@ -17,18 +17,18 @@ import (
 )
 
 // A Qualifier controls how named package-level objects are printed in
-// calls to TypeString, ObjectString, and SelectionString.
+// calls to [TypeString], [ObjectString], and [SelectionString].
 //
 // These three formatting routines call the Qualifier for each
 // package-level object O, and if the Qualifier returns a non-empty
 // string p, the object is printed in the form p.O.
 // If it returns an empty string, only the object name O is printed.
 //
-// Using a nil Qualifier is equivalent to using (*Package).Path: the
+// Using a nil Qualifier is equivalent to using (*[Package]).Path: the
 // object is qualified by the import path, e.g., "encoding/json.Marshal".
 type Qualifier func(*Package) string
 
-// RelativeTo returns a Qualifier that fully qualifies members of
+// RelativeTo returns a [Qualifier] that fully qualifies members of
 // all packages other than pkg.
 func RelativeTo(pkg *Package) Qualifier {
 	if pkg == nil {
@@ -43,7 +43,7 @@ func RelativeTo(pkg *Package) Qualifier {
 }
 
 // TypeString returns the string representation of typ.
-// The Qualifier controls the printing of
+// The [Qualifier] controls the printing of
 // package-level objects, and may be nil.
 func TypeString(typ Type, qf Qualifier) string {
 	var buf bytes.Buffer
@@ -52,14 +52,14 @@ func TypeString(typ Type, qf Qualifier) string {
 }
 
 // WriteType writes the string representation of typ to buf.
-// The Qualifier controls the printing of
+// The [Qualifier] controls the printing of
 // package-level objects, and may be nil.
 func WriteType(buf *bytes.Buffer, typ Type, qf Qualifier) {
 	newTypeWriter(buf, qf).typ(typ)
 }
 
 // WriteSignature writes the representation of the signature sig to buf,
-// without a leading "func" keyword. The Qualifier controls the printing
+// without a leading "func" keyword. The [Qualifier] controls the printing
 // of package-level objects, and may be nil.
 func WriteSignature(buf *bytes.Buffer, sig *Signature, qf Qualifier) {
 	newTypeWriter(buf, qf).signature(sig)
diff --git a/src/go/types/union.go b/src/go/types/union.go
index f2cfd6a737..30365e30bc 100644
--- a/src/go/types/union.go
+++ b/src/go/types/union.go
@@ -18,7 +18,7 @@ type Union struct {
 	terms []*Term // list of syntactical terms (not a canonicalized termlist)
 }
 
-// NewUnion returns a new Union type with the given terms.
+// NewUnion returns a new [Union] type with the given terms.
 // It is an error to create an empty union; they are syntactically not possible.
 func NewUnion(terms []*Term) *Union {
 	if len(terms) == 0 {
@@ -33,7 +33,7 @@ func (u *Union) Term(i int) *Term { return u.terms[i] }
 func (u *Union) Underlying() Type { return u }
 func (u *Union) String() string   { return TypeString(u, nil) }
 
-// A Term represents a term in a Union.
+// A Term represents a term in a [Union].
 type Term term
 
 // NewTerm returns a new union term.