all: tidy up deprecation warnings a bit

In APIs like Runtime.Compile, point to non-deprecated alternatives,
rather than pointing to methods which are themselves also deprecated.

While here, tidy up other deprecated notes so that they use doc links.

Also note that Instance.LookupField had two deprecation notices;
only the second seems to have been up to date.

Fixes #1735.

Signed-off-by: Daniel Martí <mvdan@mvdan.cc>
Change-Id: Ie8d8ba3e76855f36d3746a1e65c9d8af17737dbc
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1195013
TryBot-Result: CUEcueckoo <cueckoo@cuelang.org>
Unity-Result: CUE porcuepine <cue.porcuepine@gmail.com>
Reviewed-by: Paul Jolly <paul@myitcv.io>

cue/build.go

@@ -31,7 +31,7 @@ import (
 // The zero value of Runtime works for legacy reasons, but
 // should not be used. It may panic at some point.
 //
-// Deprecated: use Context.
+// Deprecated: use [Context].
 type Runtime runtime.Runtime
 
 func (r *Runtime) runtime() *runtime.Runtime {
@@ -57,7 +57,8 @@ func (r *Runtime) complete(p *build.Instance, v *adt.Vertex) (*Instance, error)
 // name in position information. The source may import builtin packages. Use
 // Build to allow importing non-builtin packages.
 //
-// Deprecated: use Parse or ParseBytes. The use of Instance is being phased out.
+// Deprecated: use [Context] with methods like [Context.CompileString] or [Context.CompileBytes].
+// The use of [Instance] is being phased out.
 func (r *hiddenRuntime) Compile(filename string, source interface{}) (*Instance, error) {
 	cfg := &runtime.Config{Filename: filename}
 	v, p := r.runtime().Compile(cfg, source)
@@ -67,7 +68,7 @@ func (r *hiddenRuntime) Compile(filename string, source interface{}) (*Instance,
 // CompileFile compiles the given source file into an Instance. The source may
 // import builtin packages. Use Build to allow importing non-builtin packages.
 //
-// Deprecated: use BuildFile. The use of Instance is being phased out.
+// Deprecated: use [Context.BuildFile]. The use of [Instance] is being phased out.
 func (r *hiddenRuntime) CompileFile(file *ast.File) (*Instance, error) {
 	v, p := r.runtime().CompileFile(nil, file)
 	return r.complete(p, v)
@@ -77,7 +78,7 @@ func (r *hiddenRuntime) CompileFile(file *ast.File) (*Instance, error) {
 // may import builtin packages. Use Build to allow importing non-builtin
 // packages.
 //
-// Deprecated: use BuildExpr. The use of Instance is being phased out.
+// Deprecated: use [Context.BuildExpr]. The use of [Instance] is being phased out.
 func (r *hiddenRuntime) CompileExpr(expr ast.Expr) (*Instance, error) {
 	f, err := astutil.ToFile(expr)
 	if err != nil {
@@ -148,7 +149,7 @@ func (r *hiddenRuntime) build(instances []*build.Instance) ([]*Instance, error)
 // FromExpr creates an instance from an expression.
 // Any references must be resolved beforehand.
 //
-// Deprecated: use CompileExpr
+// Deprecated: use [Context.BuildExpr]. The use of [Instance] is being phased out.
 func (r *hiddenRuntime) FromExpr(expr ast.Expr) (*Instance, error) {
 	return r.CompileFile(&ast.File{
 		Decls: []ast.Decl{&ast.EmbedDecl{Expr: expr}},

cue/errors/errors.go

@@ -84,7 +84,8 @@ func NewMessagef(format string, args ...interface{}) Message {
 }
 
 // NewMessage creates an error message for human consumption.
-// Deprecated: Use NewMessagef instead.
+//
+// Deprecated: Use [NewMessagef] instead.
 func NewMessage(format string, args []interface{}) Message {
 	return NewMessagef(format, args...)
 }

cue/instance.go

@@ -244,7 +244,7 @@ func Merge(inst ...*Instance) *Instance {
 // identifier to bind to the top-level field in inst. The top-level fields in
 // inst take precedence over predeclared identifier and builtin functions.
 //
-// Deprecated: use Context.Build
+// Deprecated: use [Context.BuildInstance]
 func (inst *hiddenInstance) Build(p *build.Instance) *Instance {
 	p.Complete()
 
@@ -279,7 +279,7 @@ func (inst *hiddenInstance) Build(p *build.Instance) *Instance {
 // empty path returns the top-level configuration struct. Use LookupDef for definitions or LookupField for
 // any kind of field.
 //
-// Deprecated: use Value.LookupPath
+// Deprecated: use [Value.LookupPath]
 func (inst *hiddenInstance) Lookup(path ...string) Value {
 	return inst.Value().Lookup(path...)
 }
@@ -288,7 +288,7 @@ func (inst *hiddenInstance) Lookup(path ...string) Value {
 // Exists method of the returned value will report false if the definition did
 // not exist. The Err method reports if any error occurred during evaluation.
 //
-// Deprecated: use Value.LookupPath
+// Deprecated: use [Value.LookupPath]
 func (inst *hiddenInstance) LookupDef(path string) Value {
 	return inst.Value().LookupDef(path)
 }
@@ -298,10 +298,7 @@ func (inst *hiddenInstance) LookupDef(path string) Value {
 //
 // It cannot look up hidden or unexported fields.
 //
-// Deprecated: this API does not work with new-style definitions. Use
-// FieldByName defined on inst.Value().
-//
-// Deprecated: use Value.LookupPath
+// Deprecated: use [Value.LookupPath]
 func (inst *hiddenInstance) LookupField(path ...string) (f FieldInfo, err error) {
 	v := inst.Value()
 	for _, k := range path {
@@ -329,7 +326,7 @@ func (inst *hiddenInstance) LookupField(path ...string) (f FieldInfo, err error)
 // a Value. In the latter case, it will panic if the Value is not from the same
 // Runtime.
 //
-// Deprecated: use Value.FillPath()
+// Deprecated: use [Value.FillPath]
 func (inst *hiddenInstance) Fill(x interface{}, path ...string) (*Instance, error) {
 	v := inst.Value().Fill(x, path...)
 

cue/types.go

@@ -1304,7 +1304,7 @@ func (v Value) Len() Value {
 
 // Elem returns the value of undefined element types of lists and structs.
 //
-// Deprecated: use LookupPath in combination with "AnyString" or "AnyIndex".
+// Deprecated: use [Value.LookupPath] in combination with "AnyString" or "AnyIndex".
 func (v hiddenValue) Elem() (Value, bool) {
 	sel := AnyString
 	if v.v.IsList() {
@@ -1472,7 +1472,7 @@ func (v Value) structValOpts(ctx *adt.OpContext, o options) (s structValue, err
 // Struct returns the underlying struct of a value or an error if the value
 // is not a struct.
 //
-// Deprecated: use Fields.
+// Deprecated: use [Value.Fields].
 func (v hiddenValue) Struct() (*Struct, error) {
 	ctx := v.ctx()
 	obj, err := v.structValOpts(ctx, options{})
@@ -1641,7 +1641,7 @@ func appendPath(a []Selector, v Value) []Selector {
 
 // LookupDef is equal to LookupPath(MakePath(Def(name))).
 //
-// Deprecated: use LookupPath.
+// Deprecated: use [Value.LookupPath].
 func (v hiddenValue) LookupDef(name string) Value {
 	return v.LookupPath(MakePath(Def(name)))
 }
@@ -1652,7 +1652,7 @@ var errNotFound = errors.Newf(token.NoPos, "field not found")
 // look up a definition or hidden field (starting with `_` or `_#`). Otherwise
 // it interprets name as an arbitrary string for a regular field.
 //
-// Deprecated: use LookupPath.
+// Deprecated: use [Value.LookupPath].
 func (v hiddenValue) FieldByName(name string, isIdent bool) (f FieldInfo, err error) {
 	s, err := v.Struct()
 	if err != nil {
@@ -1663,7 +1663,7 @@ func (v hiddenValue) FieldByName(name string, isIdent bool) (f FieldInfo, err er
 
 // LookupField reports information about a field of v.
 //
-// Deprecated: use LookupPath
+// Deprecated: use [Value.LookupPath].
 func (v hiddenValue) LookupField(name string) (FieldInfo, error) {
 	s, err := v.Struct()
 	if err != nil {
@@ -1701,7 +1701,7 @@ func (v hiddenValue) LookupField(name string) (FieldInfo, error) {
 // Any reference in v referring to the value at the given path will resolve
 // to x in the newly created value. The resulting value is not validated.
 //
-// Deprecated: use FillPath.
+// Deprecated: use [Value.FillPath].
 func (v hiddenValue) Fill(x interface{}, path ...string) Value {
 	if v.v == nil {
 		return v
@@ -1807,7 +1807,7 @@ func (v Value) FillPath(p Path, x interface{}) Value {
 // The returned function returns the value that would be unified with field
 // given its name.
 //
-// Deprecated: use LookupPath in combination with using optional selectors.
+// Deprecated: use [Value.LookupPath] in combination with using optional selectors.
 func (v hiddenValue) Template() func(label string) Value {
 	if v.v == nil {
 		return nil
@@ -2162,7 +2162,7 @@ func DisallowCycles(disallow bool) Option {
 
 // ResolveReferences forces the evaluation of references when outputting.
 //
-// Deprecated: Syntax will now always attempt to resolve dangling references and
+// Deprecated: [Value.Syntax] will now always attempt to resolve dangling references and
 // make the output self-contained. When [Final] or [Concrete] are used,
 // it will already attempt to resolve all references.
 // See also [InlineImports].

pkg/list/sort.go

@@ -211,7 +211,7 @@ func getArc(ctx *adt.OpContext, v *adt.Vertex, s string) *adt.Vertex {
 	return arc
 }
 
-// Deprecated: use Sort, which is always stable
+// Deprecated: use [Sort], which is always stable
 func SortStable(list []cue.Value, cmp cue.Value) (sorted []cue.Value, err error) {
 	s := makeValueSorter(list, cmp)
 	sort.Stable(&s)