cue/load: clarify the docs for Config.ModuleRoot

The previous docs were a bit unclear and outdated; they still referred
to the old cue.mod file, and it wasn't particularly clear whether
ModuleRoot was the cue.mod directory itself or its parent directory.
The behavior when the field was left empty was also not documented.

While here, point to cue/load from the cue API as it may otherwise
not be clear why APIs like Context.CompileString are not able to load
imports from dependencies declared in cue.mod/module.cue.

Fixes #1380.

Signed-off-by: Daniel Martí <[email protected]>
Change-Id: I73f851f5ca7a2be0b3165f64de7dd369faad6887
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1196662
TryBot-Result: CUEcueckoo <[email protected]>
Reviewed-by: Aram Hăvărneanu <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>

Author: mvdan

cue/context.go

@@ -34,11 +34,7 @@ import (
 // representations of values, and defines the set of supported builtins. Any
 // operation that involves two Values should originate from the same Context.
 //
-// Use
-//
-//	ctx := cuecontext.New()
-//
-// to create a new Context.
+// Use [cuelang.org/go/cue/cuecontext.New] to create a new context.
 type Context runtime.Runtime
 
 func (c *Context) runtime() *runtime.Runtime {

cue/cue.go

@@ -20,14 +20,12 @@
 // 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
+// [Context] defines the set of active packages, the translations of field
+// names to unique codes, as well as the set of builtins.
+// Use [cuelang.org/go/cue/cuecontext.New] to create a new context.
 //
-//	import "cuelang.org/go/cue/cuecontext"
-//
-//	ctx := cuecontext.New()
-//
-// to obtain a context.
+// While a context can be used to build values, note that loading a module and its
+// dependencies should be done with the [cuelang.org/go/cue/load] package.
 //
 // Note that the following types are DEPRECATED and their usage should be
 // avoided if possible:

cue/load/config.go

@@ -128,10 +128,12 @@ type Config struct {
 	// Context specifies the context for the load operation.
 	Context *build.Context
 
-	// A Module is a collection of packages and instances that are within the
-	// directory hierarchy rooted at the module root. The module root can be
-	// marked with a cue.mod file.
-	// If this is a relative path, it will be interpreted relative to [Config.Dir].
+	// ModuleRoot is the directory that contains the cue.mod directory
+	// as well as all the packages which form part of the module being loaded.
+	//
+	// If left as the empty string, a module root is found by walking parent directories
+	// starting from [Config.Dir] until one is found containing a cue.mod directory.
+	// If it is a relative path, it will be interpreted relative to [Config.Dir].
 	ModuleRoot string
 
 	// Module specifies the module prefix. If not empty, this value must match