From 286dfcb833fc924aa0582f18efeb1e95618bc73c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Wed, 25 Oct 2023 11:41:41 +0100 Subject: [PATCH] cue: add more godoc links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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í Change-Id: Ibb1b7de6a1e4a27f4417158559d5857014d922c0 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1171218 TryBot-Result: CUEcueckoo Reviewed-by: Roger Peppe Unity-Result: CUE porcuepine --- cue/build.go | 10 ++++------ cue/instance.go | 8 ++++++-- cue/types.go | 4 ++-- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/cue/build.go b/cue/build.go index 8de928753b6..6dea7a78fe0 100644 --- a/cue/build.go +++ b/cue/build.go @@ -102,8 +102,8 @@ 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) } @@ -111,15 +111,13 @@ func (r *hiddenRuntime) Parse(name string, source interface{}) (*Instance, error // 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") diff --git a/cue/instance.go b/cue/instance.go index 3eeebf0d70a..ee1f74faf3e 100644 --- a/cue/instance.go +++ b/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 diff --git a/cue/types.go b/cue/types.go index d8261c272c6..9e0bfac59a5 100644 --- a/cue/types.go +++ b/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() {