cue: explicitly document values are not safe for concurrent use

Users are regularly confused by data races or other panics
caused by the concurrent use of the API in this package,
particularly when making concurrent use of values.

Even though Go APIs are generally not safe for concurrent use
unless documented otherwise, per https://go.dev/issue/30632,
it can be easy to forget that since concurrency is so common in Go.

Add an explicit reminder about it, following our reasoning from
the last time we discussed the current state of concurrency in the API.

While here, make a few godoc link tweaks.

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

Author: mvdan

cue/build.go

@@ -117,7 +117,7 @@ func (r *hiddenRuntime) Build(p *build.Instance) (*Instance, error) {
 	return r.complete(p, v)
 }
 
-// Deprecated: [Context.BuildInstances]. The use of [Instance] is being phased out.
+// Deprecated: use [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/cue.go

@@ -14,9 +14,11 @@
 
 // Package cue is the main API for CUE evaluation.
 //
-// Value is the main type that represents CUE evaluations. Values are created
-// with a cue.Context. Only values created from the same Context can be
-// involved in the same operation.
+// [Value] is the main type that represents CUE evaluations.
+// Values are created with a [cuecontext.Context].
+// Only values created from the same Context can be involved in the same operation.
+// Values created from the same Context are not safe for concurrent use,
+// which we intend to change in the future.
 //
 // A Context defines the set of active packages, the translations of field
 // names to unique codes, as well as the set of builtins. Use
@@ -30,10 +32,10 @@
 // Note that the following types are DEPRECATED and their usage should be
 // avoided if possible:
 //
-//	FieldInfo
-//	Instance
-//	Runtime
-//	Struct
+//	[FieldInfo]
+//	[Instance]
+//	[Runtime]
+//	[Struct]
 //
 // Many types also have deprecated methods. Code that already uses deprecated
 // methods can keep using them for at least some time. We aim to provide a