cue: add more godoc links

I was looking at some of the deprecation notices
and it took me a bit of effort to find the referenced APIs.
Use godoc links so they are trivial to find.

While here, I noticed that hiddenValue.Value referenced a missing type,
which seems to have been a mistake when InstanceOrValue was added.

Also add a note to Instance about it being phased out,
which was documented in its constructors, but not the type itself.
We don't want to deprecate the type right away,
as it's still used in some of our user-facing APIs.

Signed-off-by: Daniel Martí <[email protected]>
Change-Id: Ibb1b7de6a1e4a27f4417158559d5857014d922c0
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1171218
TryBot-Result: CUEcueckoo <[email protected]>
Reviewed-by: Roger Peppe <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>

Author: mvdan

cue/build.go

@@ -102,24 +102,22 @@ func (r *hiddenRuntime) CompileExpr(expr ast.Expr) (*Instance, error) {
 // provided as a string, byte slice, or io.Reader. The name is used as the file
 // name in position information. The source may import builtin packages.
 //
-// Deprecated: use CompileString or CompileBytes.  The use of Instance is being
-// phased out.
+// Deprecated: use [Context.CompileString] or [Context.CompileBytes].
+// The use of [Instance] is being phased out.
 func (r *hiddenRuntime) Parse(name string, source interface{}) (*Instance, error) {
 	return r.Compile(name, source)
 }
 
 // Build creates an Instance from the given build.Instance. A returned Instance
 // may be incomplete, in which case its Err field is set.
 //
-// Deprecated: use Context.BuildInstance. The use of Instance is being phased
-// out.
+// Deprecated: use [Context.BuildInstance]. The use of [Instance] is being phased out.
 func (r *hiddenRuntime) Build(p *build.Instance) (*Instance, error) {
 	v, _ := r.runtime().Build(nil, p)
 	return r.complete(p, v)
 }
 
-// Deprecated: use cuecontext.Context.BuildInstances. The use of Instance is
-// being phased out.
+// Deprecated: [Context.BuildInstances]. The use of [Instance] is being phased out.
 func Build(instances []*build.Instance) []*Instance {
 	if len(instances) == 0 {
 		panic("cue: list of instances must not be empty")

cue/instance.go

@@ -24,7 +24,7 @@ import (
 	"cuelang.org/go/internal/core/runtime"
 )
 
-// An InstanceOrValue is implemented by Value and *Instance.
+// An InstanceOrValue is implemented by [Value] and *[Instance].
 //
 // This is a placeholder type that is used to allow Instance-based APIs to
 // transition to Value-based APIs. The goals is to get rid of the Instance
@@ -38,11 +38,15 @@ type InstanceOrValue interface {
 func (Value) internal()     {}
 func (*Instance) internal() {}
 
-// Value implements value.Instance.
+// Value implements [InstanceOrValue].
 func (v hiddenValue) Value() Value { return v }
 
 // An Instance defines a single configuration based on a collection of
 // underlying CUE files.
+//
+// Use of this type is being phased out in favor of [Value].
+// Any APIs currently taking an Instance should use [InstanceOrValue]
+// to transition to the new type without breaking users.
 type Instance struct {
 	index *runtime.Runtime
 

cue/types.go

@@ -1055,7 +1055,7 @@ func (v Value) Doc() []*ast.CommentGroup {
 // split values may fail if actually unified.
 // Source returns a non-nil value.
 //
-// Deprecated: use Expr.
+// Deprecated: use [Value.Expr].
 func (v hiddenValue) Split() []Value {
 	if v.v == nil {
 		return nil
@@ -1947,7 +1947,7 @@ func (v Value) instance() *Instance {
 // a reference. If a reference contains index selection (foo[bar]), it will
 // only return a reference if the index resolves to a concrete value.
 //
-// Deprecated: use ReferencePath
+// Deprecated: use [Value.ReferencePath]
 func (v hiddenValue) Reference() (inst *Instance, path []string) {
 	root, p := v.ReferencePath()
 	if !root.Exists() {