From 9711908a12e2384bca5f938bf0d8693d19fd973a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Tue, 10 Sep 2024 10:12:23 +0100 Subject: [PATCH] all: fix up more godocs to use links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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í Change-Id: I2729f81d509ddeb17cba8e72215e89dfc52ec356 Dispatch-Trailer: {"type":"trybot","CL":1200920,"patchset":1,"ref":"refs/changes/20/1200920/1","targetBranch":"master"} --- cue/build/context.go | 2 +- cue/errors/errors.go | 2 +- cue/format/format.go | 8 ++++---- cue/format/format_test.go | 2 +- cue/format/node.go | 8 ++++---- cue/format/printer.go | 4 ++-- encoding/gocode/gocodec/codec.go | 6 +++--- encoding/jsonschema/ref.go | 4 ++-- encoding/openapi/orderedmap.go | 4 ++-- encoding/protobuf/protobuf.go | 4 ++-- encoding/protobuf/textproto/decoder.go | 4 ++-- pkg/path/os.go | 2 +- tools/fix/fixall.go | 2 +- 13 files changed, 26 insertions(+), 26 deletions(-) diff --git a/cue/build/context.go b/cue/build/context.go index dc1e347c9..c8eadbf29 100644 --- a/cue/build/context.go +++ b/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. diff --git a/cue/errors/errors.go b/cue/errors/errors.go index 666b0e4f3..83ac815d6 100644 --- a/cue/errors/errors.go +++ b/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) diff --git a/cue/format/format.go b/cue/format/format.go index 39d0357d6..4fb52e63b 100644 --- a/cue/format/format.go +++ b/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++ } } diff --git a/cue/format/format_test.go b/cue/format/format_test.go index 4fef971cd..ce97380ec 100644 --- a/cue/format/format_test.go +++ b/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) diff --git a/cue/format/node.go b/cue/format/node.go index b886a4958..4d0e943b1 100644 --- a/cue/format/node.go +++ 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) diff --git a/cue/format/printer.go b/cue/format/printer.go index 3509afe44..83b8202fb 100644 --- a/cue/format/printer.go +++ b/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 { diff --git a/encoding/gocode/gocodec/codec.go b/encoding/gocode/gocodec/codec.go index d5b4e5809..b596889af 100644 --- a/encoding/gocode/gocodec/codec.go +++ b/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() diff --git a/encoding/jsonschema/ref.go b/encoding/jsonschema/ref.go index 4c2338d83..bccbbde96 100644 --- a/encoding/jsonschema/ref.go +++ b/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 { diff --git a/encoding/openapi/orderedmap.go b/encoding/openapi/orderedmap.go index 22966841b..dc504a14e 100644 --- a/encoding/openapi/orderedmap.go +++ b/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. diff --git a/encoding/protobuf/protobuf.go b/encoding/protobuf/protobuf.go index efb7924e8..477f98a93 100644 --- a/encoding/protobuf/protobuf.go +++ b/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 diff --git a/encoding/protobuf/textproto/decoder.go b/encoding/protobuf/textproto/decoder.go index 4092405b4..d8962bef6 100644 --- a/encoding/protobuf/textproto/decoder.go +++ b/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 } diff --git a/pkg/path/os.go b/pkg/path/os.go index 08592c3df..f55193977 100644 --- a/pkg/path/os.go +++ b/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 ( diff --git a/tools/fix/fixall.go b/tools/fix/fixall.go index c2fa2aec5..a1abda477 100644 --- a/tools/fix/fixall.go +++ b/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()