all: fix up more godocs to use links

While here, fix a number of references to a "syntax" package which
does not exist; we instead have the ast, token, and parser packages.

Signed-off-by: Daniel Martí <[email protected]>
Change-Id: I2729f81d509ddeb17cba8e72215e89dfc52ec356
Dispatch-Trailer: {"type":"trybot","CL":1200920,"patchset":1,"ref":"refs/changes/20/1200920/1","targetBranch":"master"}

cue/build/context.go

@@ -109,7 +109,7 @@ func Loader(f LoadFunc) Option {
 // ParseFile is called to read and parse each file
 // when building syntax tree.
 // It must be safe to call ParseFile simultaneously from multiple goroutines.
-// If ParseFile is nil, the loader will uses parser.ParseFile.
+// If f is nil, the loader will use [cuelang.org/go/cue/parser.ParseFile].
 //
 // ParseFile should parse the source from src and use filename only for
 // recording position information.

cue/errors/errors.go

@@ -31,7 +31,7 @@ import (
 	"cuelang.org/go/cue/token"
 )
 
-// New is a convenience wrapper for errors.New in the core library.
+// New is a convenience wrapper for [errors.New] in the core library.
 // It does not return a CUE error.
 func New(msg string) error {
 	return errors.New(msg)

cue/format/format.go

@@ -79,8 +79,8 @@ func sortImportsOption() Option {
 
 // Node formats node in canonical cue fmt style and writes the result to dst.
 //
-// The node type must be *ast.File, []syntax.Decl, syntax.Expr, syntax.Decl, or
-// syntax.Spec. Node does not modify node. Imports are not sorted for nodes
+// The node type must be [*ast.File], [][ast.Decl], [ast.Expr], [ast.Decl], or
+// [ast.Spec]. 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).
 //
@@ -175,7 +175,7 @@ func (cfg *config) fprint(node interface{}) (out []byte, err error) {
 	return b, nil
 }
 
-// A formatter walks a syntax.Node, interspersed with comments and spacing
+// A formatter walks an [ast.Node], interspersed with comments and spacing
 // directives, in the order that they would occur in printed form.
 type formatter struct {
 	*printer
@@ -248,7 +248,7 @@ func (f *formatter) print(a ...interface{}) {
 	for _, x := range a {
 		f.Print(x)
 		switch x.(type) {
-		case string, token.Token: // , *syntax.BasicLit, *syntax.Ident:
+		case string, token.Token: // , *ast.BasicLit, *ast.Ident:
 			f.current.pos++
 		}
 	}

cue/format/format_test.go

@@ -276,7 +276,7 @@ e2: c*t.z
 	}
 
 	// parse pretty printed original
-	// (//line comments must be interpreted even w/o syntax.ParseComments set)
+	// (//line comments must be interpreted even w/o parser.ParseComments set)
 	f2, err := parser.ParseFile("", b, parser.AllErrors, parser.ParseComments)
 	if err != nil {
 		t.Fatalf("%s\n%s", err, b)

cue/format/node.go

@@ -776,7 +776,7 @@ func walkBinary(e *ast.BinaryExpr) (has6, has7, has8 bool, maxProblem int) {
 	case *ast.BinaryExpr:
 		if l.Op.Precedence() < e.Op.Precedence() {
 			// parens will be inserted.
-			// pretend this is an *syntax.ParenExpr and do nothing.
+			// pretend this is an *ast.ParenExpr and do nothing.
 			break
 		}
 		h6, h7, h8, mp := walkBinary(l)
@@ -792,7 +792,7 @@ func walkBinary(e *ast.BinaryExpr) (has6, has7, has8 bool, maxProblem int) {
 	case *ast.BinaryExpr:
 		if r.Op.Precedence() <= e.Op.Precedence() {
 			// parens will be inserted.
-			// pretend this is an *syntax.ParenExpr and do nothing.
+			// pretend this is an *ast.ParenExpr and do nothing.
 			break
 		}
 		h6, h7, h8, mp := walkBinary(r)
@@ -901,7 +901,7 @@ func (f *formatter) binaryExpr(x *ast.BinaryExpr, prec1, cutoff, depth int) {
 	prec := x.Op.Precedence()
 	if prec < prec1 {
 		// parenthesis needed
-		// Note: The parser inserts a syntax.ParenExpr node; thus this case
+		// Note: The parser inserts a ast.ParenExpr node; thus this case
 		//       can only occur if the AST is created in a different way.
 		// defer p.pushComment(nil).pop()
 		f.print(token.LPAREN, nooverride)
@@ -945,7 +945,7 @@ func (f *formatter) possibleSelectorExpr(expr ast.Expr, prec1, depth int) bool {
 	return false
 }
 
-// selectorExpr handles an *syntax.SelectorExpr node and returns whether x spans
+// selectorExpr handles an [*ast.SelectorExpr] node and returns whether x spans
 // multiple lines.
 func (f *formatter) selectorExpr(x *ast.SelectorExpr, depth int) bool {
 	f.expr1(x.X, token.HighestPrec, depth)

cue/format/printer.go

@@ -39,7 +39,7 @@ type printer struct {
 	pos     token.Position // current pos in AST
 	lineout line
 
-	lastTok token.Token // last token printed (syntax.ILLEGAL if it's whitespace)
+	lastTok token.Token // last token printed (token.ILLEGAL if it's whitespace)
 
 	output           []byte
 	indent           int
@@ -98,7 +98,7 @@ func (p *printer) Print(v interface{}) {
 			// the previous and the current token must be
 			// separated by a blank otherwise they combine
 			// into a different incorrect token sequence
-			// (except for syntax.INT followed by a '.' this
+			// (except for token.INT followed by a '.' this
 			// should never happen because it is taken care
 			// of via binary expression formatting)
 			if p.allowed&blank != 0 {

encoding/gocode/gocodec/codec.go

@@ -54,7 +54,7 @@ func New[Ctx *cue.Runtime | *cue.Context](ctx Ctx, c *Config) *Codec {
 //
 // The type represented by x is converted as the underlying type. Specific
 // values, such as map or slice elements or field values of structs are ignored.
-// If x is of type reflect.Type, the type represented by x is extracted.
+// If x is of type [reflect.Type], the type represented by x is extracted.
 //
 // Fields of structs can be annoted using additional constrains using the 'cue'
 // field tag. The value of the tag is a CUE expression, which may contain
@@ -78,7 +78,7 @@ func (c *Codec) ExtractType(x interface{}) (cue.Value, error) {
 
 // Decode converts x to a CUE value.
 //
-// If x is of type reflect.Value it will convert the value represented by x.
+// If x is of type [reflect.Value] it will convert the value represented by x.
 func (c *Codec) Decode(x interface{}) (cue.Value, error) {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
@@ -147,7 +147,7 @@ func (c *Codec) Validate(v cue.Value, x interface{}) error {
 // initialized.
 //
 // Complete does a JSON round trip. This means that data not preserved in such a
-// round trip, such as the location name of a time.Time, is lost after a
+// round trip, such as the location name of a [time.Time], is lost after a
 // successful update.
 func (c *Codec) Complete(v cue.Value, x interface{}) error {
 	c.mutex.RLock()

encoding/jsonschema/ref.go

@@ -91,7 +91,7 @@ func (s *state) resolveURI(n cue.Value) *url.URL {
 
 // makeCUERef converts a URI into a CUE reference for the current location.
 // The returned identifier (or first expression in a selection chain), is
-// hardwired to point to the resolved value. This will allow astutil.Sanitize
+// hardwired to point to the resolved value. This will allow [astutil.Sanitize]
 // to automatically unshadow any shadowed variables.
 func (s *state) makeCUERef(n cue.Value, u *url.URL, fragmentParts []string) (_e ast.Expr) {
 	switch fn := s.cfg.Map; {
@@ -322,7 +322,7 @@ func (s *state) getNextIdent(v cue.Value, a []string) (resolved *ast.Ident, tail
 }
 
 // linkReferences resolves identifiers to relevant nodes. This allows
-// astutil.Sanitize to unshadow nodes if necessary.
+// [astutil.Sanitize] to unshadow nodes if necessary.
 func (s *state) linkReferences() {
 	for _, r := range s.fieldRefs {
 		if r.field == nil {

encoding/openapi/orderedmap.go

@@ -115,7 +115,7 @@ func (m *OrderedMap) find(key string) *ast.Field {
 
 // Set sets a key value pair. If a pair with the same key already existed, it
 // will be replaced with the new value. Otherwise, the new value is added to
-// the end. The value must be of type string, ast.Expr, or *OrderedMap.
+// the end. The value must be of type string, [ast.Expr], or [*OrderedMap].
 //
 // Deprecated: use cuelang.org/go/cue/ast to manipulate ASTs.
 func (m *OrderedMap) Set(key string, x interface{}) {
@@ -173,7 +173,7 @@ func (m *OrderedMap) getMap(key string) *OrderedMap {
 	return (*OrderedMap)(f.Value.(*ast.StructLit))
 }
 
-// MarshalJSON implements json.Marshaler.
+// MarshalJSON implements [encoding/json.Marshaler].
 func (m *OrderedMap) MarshalJSON() (b []byte, err error) {
 	// This is a pointer receiever to enforce that we only store pointers to
 	// OrderedMap in the output.

encoding/protobuf/protobuf.go

@@ -216,7 +216,7 @@ func NewExtractor(c *Config) *Extractor {
 }
 
 // Err returns the errors accumulated during testing. The returned error may be
-// of type cuelang.org/go/cue/errors.List.
+// of type [errors.List].
 func (b *Extractor) Err() error {
 	return b.errs
 }
@@ -402,7 +402,7 @@ func (b *Extractor) getInst(p *protoConverter) *build.Instance {
 
 // Extract parses a single proto file and returns its contents translated to a CUE
 // file. If src is not nil, it will use this as the contents of the file. It may
-// be a string, []byte or io.Reader. Otherwise Extract will open the given file
+// be a string, []byte or [io.Reader]. Otherwise Extract will open the given file
 // name at the fully qualified path.
 //
 // Extract assumes the proto file compiles with protoc and may not report an error

encoding/protobuf/textproto/decoder.go

@@ -39,14 +39,14 @@ type Option func(*options)
 type options struct {
 }
 
-// NewDecoder returns a new Decoder
+// NewDecoder returns a new [Decoder].
 func NewDecoder(option ...Option) *Decoder {
 	d := &Decoder{}
 	_ = d.m // work around linter bug.
 	return d
 }
 
-// A Decoder caches conversions of cue.Value between calls to its methods.
+// A Decoder caches conversions of [cue.Value] between calls to its methods.
 type Decoder struct {
 	m map[*adt.Vertex]*mapping
 }

pkg/path/os.go

@@ -14,7 +14,7 @@
 
 package path
 
-// OS must be a valid runtime.GOOS value or "unix".
+// OS must be a valid [runtime.GOOS] value or "unix".
 type OS string
 
 const (

tools/fix/fixall.go

@@ -24,7 +24,7 @@ import (
 
 // Instances modifies all files contained in the given build instances at once.
 //
-// It also applies fix.File.
+// It also applies the fixes from [File].
 func Instances(a []*build.Instance, o ...Option) errors.Error {
 	cwd, _ := os.Getwd()