starlark,syntax,repl: improve docs for deprecated functions

repl/repl.go

@@ -27,7 +27,9 @@ import (
 var interrupted = make(chan os.Signal, 1)
 
 // REPL calls [REPLOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [REPLOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func REPL(thread *starlark.Thread, globals starlark.StringDict) {
 	REPLOptions(syntax.LegacyFileOptions(), thread, globals)
 }
@@ -153,7 +155,9 @@ func PrintError(err error) {
 }
 
 // MakeLoad calls [MakeLoadOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [MakeLoadOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func MakeLoad() func(thread *starlark.Thread, module string) (starlark.StringDict, error) {
 	return MakeLoadOptions(syntax.LegacyFileOptions())
 }

resolve/resolve.go

@@ -155,7 +155,9 @@ func REPLChunk(file *syntax.File, isGlobal, isPredeclared, isUniversal func(name
 }
 
 // Expr calls [ExprOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [ExprOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func Expr(expr syntax.Expr, isPredeclared, isUniversal func(name string) bool) ([]*Binding, error) {
 	return ExprOptions(syntax.LegacyFileOptions(), expr, isPredeclared, isUniversal)
 }

starlark/eval.go

@@ -325,7 +325,9 @@ func (prog *Program) Write(out io.Writer) error {
 }
 
 // ExecFile calls [ExecFileOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [ExecFileOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func ExecFile(thread *Thread, filename string, src interface{}, predeclared StringDict) (StringDict, error) {
 	return ExecFileOptions(syntax.LegacyFileOptions(), thread, filename, src, predeclared)
 }
@@ -360,7 +362,9 @@ func ExecFileOptions(opts *syntax.FileOptions, thread *Thread, filename string,
 }
 
 // SourceProgram calls [SourceProgramOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [SourceProgramOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func SourceProgram(filename string, src interface{}, isPredeclared func(string) bool) (*syntax.File, *Program, error) {
 	return SourceProgramOptions(syntax.LegacyFileOptions(), filename, src, isPredeclared)
 }
@@ -524,7 +528,9 @@ func makeToplevelFunction(prog *compile.Program, predeclared StringDict) *Functi
 }
 
 // Eval calls [EvalOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [EvalOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func Eval(thread *Thread, filename string, src interface{}, env StringDict) (Value, error) {
 	return EvalOptions(syntax.LegacyFileOptions(), thread, filename, src, env)
 }
@@ -552,7 +558,9 @@ func EvalOptions(opts *syntax.FileOptions, thread *Thread, filename string, src
 }
 
 // EvalExpr calls [EvalExprOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [EvalExprOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func EvalExpr(thread *Thread, expr syntax.Expr, env StringDict) (Value, error) {
 	return EvalExprOptions(syntax.LegacyFileOptions(), thread, expr, env)
 }
@@ -578,7 +586,9 @@ func EvalExprOptions(opts *syntax.FileOptions, thread *Thread, expr syntax.Expr,
 }
 
 // ExprFunc calls [ExprFuncOptions] using [syntax.LegacyFileOptions].
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [ExprFuncOptions] with [syntax.FileOptions] instead,
+// because this function relies on legacy global variables.
 func ExprFunc(filename string, src interface{}, env StringDict) (*Function, error) {
 	return ExprFuncOptions(syntax.LegacyFileOptions(), filename, src, env)
 }

syntax/parse.go

@@ -24,7 +24,9 @@ const (
 )
 
 // Parse calls the Parse method of LegacyFileOptions().
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [FileOptions.Parse] instead,
+// because this function relies on legacy global variables.
 func Parse(filename string, src interface{}, mode Mode) (f *File, err error) {
 	return LegacyFileOptions().Parse(filename, src, mode)
 }
@@ -54,7 +56,9 @@ func (opts *FileOptions) Parse(filename string, src interface{}, mode Mode) (f *
 }
 
 // ParseCompoundStmt calls the ParseCompoundStmt method of LegacyFileOptions().
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [FileOptions.ParseCompoundStmt] instead,
+// because this function relies on legacy global variables.
 func ParseCompoundStmt(filename string, readline func() ([]byte, error)) (f *File, err error) {
 	return LegacyFileOptions().ParseCompoundStmt(filename, readline)
 }
@@ -95,7 +99,9 @@ func (opts *FileOptions) ParseCompoundStmt(filename string, readline func() ([]b
 }
 
 // ParseExpr calls the ParseExpr method of LegacyFileOptions().
-// Deprecated: relies on legacy global variables.
+//
+// Deprecated: use [FileOptions.ParseExpr] instead,
+// because this function relies on legacy global variables.
 func ParseExpr(filename string, src interface{}, mode Mode) (expr Expr, err error) {
 	return LegacyFileOptions().ParseExpr(filename, src, mode)
 }