improve doc comments using links

Author: itchyny

compiler.go

@@ -30,10 +30,10 @@ type Code struct {
 }
 
 // Run runs the code with the variable values (which should be in the
-// same order as the given variables using WithVariables) and returns
+// same order as the given variables using [WithVariables]) and returns
 // a result iterator.
 //
-// It is safe to call this method of a *Code in multiple goroutines.
+// It is safe to call this method in goroutines, to reuse a compiled [*Code].
 func (c *Code) Run(v interface{}, values ...interface{}) Iter {
 	return c.RunWithContext(context.Background(), v, values...)
 }

error.go

@@ -5,7 +5,7 @@ import "strconv"
 // ValueError is an interface for errors with a value for internal function.
 // Return an error implementing this interface when you want to catch error
 // values (not error messages) by try-catch, just like built-in error function.
-// Refer to WithFunction to add a custom internal function.
+// Refer to [WithFunction] to add a custom internal function.
 type ValueError interface {
 	error
 	Value() interface{}

gojq.go

@@ -1,5 +1,5 @@
-// Package gojq provides the parser and interpreter of gojq.
+// Package gojq provides the parser and the interpreter of gojq.
+// Please refer to [Usage as a library] for introduction.
 //
-// Please refer to https://github.com/itchyny/gojq#usage-as-a-library for
-// introduction of the usage as a library.
+// [Usage as a library]: https://github.com/itchyny/gojq#usage-as-a-library
 package gojq

iter.go

@@ -5,7 +5,7 @@ type Iter interface {
 	Next() (interface{}, bool)
 }
 
-// NewIter creates a new Iter from values.
+// NewIter creates a new [Iter] from values.
 func NewIter(values ...interface{}) Iter {
 	switch len(values) {
 	case 0:

module_loader.go

@@ -11,7 +11,7 @@ import (
 
 // ModuleLoader is the interface for loading modules.
 //
-// Implement following optional methods. Use NewModuleLoader to load local modules.
+// Implement following optional methods. Use [NewModuleLoader] to load local modules.
 //
 //	LoadModule(string) (*Query, error)
 //	LoadModuleWithMeta(string, map[string]interface{}) (*Query, error)
@@ -20,7 +20,7 @@ import (
 //	LoadJSONWithMeta(string, map[string]interface{}) (interface{}, error)
 type ModuleLoader interface{}
 
-// NewModuleLoader creates a new ModuleLoader reading local modules in the paths.
+// NewModuleLoader creates a new [ModuleLoader] reading local modules in the paths.
 func NewModuleLoader(paths []string) ModuleLoader {
 	return &moduleLoader{expandHomeDir(paths)}
 }

operator.go

@@ -37,7 +37,7 @@ const (
 	OpUpdateAlt
 )
 
-// String implements Stringer.
+// String implements [fmt.Stringer].
 func (op Operator) String() string {
 	switch op {
 	case OpPipe:
@@ -93,7 +93,7 @@ func (op Operator) String() string {
 	}
 }
 
-// GoString implements GoStringer.
+// GoString implements [fmt.GoStringer].
 func (op Operator) GoString() (str string) {
 	defer func() { str = "gojq." + str }()
 	switch op {

option.go

@@ -6,7 +6,7 @@ import "fmt"
 type CompilerOption func(*compiler)
 
 // WithModuleLoader is a compiler option for module loader.
-// If you want to load modules from the filesystem, use NewModuleLoader.
+// If you want to load modules from the filesystem, use [NewModuleLoader].
 func WithModuleLoader(moduleLoader ModuleLoader) CompilerOption {
 	return func(c *compiler) {
 		c.moduleLoader = moduleLoader
@@ -15,15 +15,15 @@ func WithModuleLoader(moduleLoader ModuleLoader) CompilerOption {
 
 // WithEnvironLoader is a compiler option for environment variables loader.
 // The OS environment variables are not accessible by default due to security
-// reason. You can pass os.Environ if you allow to access it.
+// reasons. You can specify [os.Environ] as argument if you allow to access.
 func WithEnvironLoader(environLoader func() []string) CompilerOption {
 	return func(c *compiler) {
 		c.environLoader = environLoader
 	}
 }
 
 // WithVariables is a compiler option for variable names. The variables can be
-// used in the query. You have to give the values to code.Run in the same order.
+// used in the query. You have to give the values to [*Code.Run] in the same order.
 func WithVariables(variables []string) CompilerOption {
 	return func(c *compiler) {
 		c.variables = variables
@@ -35,20 +35,20 @@ func WithVariables(variables []string) CompilerOption {
 // values should satisfy 0 <= minarity <= maxarity <= 30, otherwise panics.
 // On handling numbers, you should take account to int, float64 and *big.Int.
 // These are the number types you are allowed to return, so do not return int64.
-// Refer to ValueError to return a value error just like built-in error function.
-// If you want to emit multiple values, call the empty function, accept a filter
-// for its argument, or call another built-in function, then use LoadInitModules
-// of the module loader.
+// Refer to [ValueError] to return a value error just like built-in error
+// function. If you want to emit multiple values, call the empty function,
+// accept a filter for its argument, or call another built-in function, then
+// use LoadInitModules of the module loader.
 func WithFunction(name string, minarity, maxarity int,
 	f func(interface{}, []interface{}) interface{}) CompilerOption {
 	return withFunction(name, minarity, maxarity, false, f)
 }
 
 // WithIterFunction is a compiler option for adding a custom iterator function.
-// This is like the WithFunction option, but you can add a function which
+// This is like the [WithFunction] option, but you can add a function which
 // returns an Iter to emit multiple values. You cannot define both iterator and
 // non-iterator functions of the same name (with possibly different arities).
-// See also NewIter, which can be used to convert values or an error to an Iter.
+// See also [NewIter], which can be used to convert values or an error to an Iter.
 func WithIterFunction(name string, minarity, maxarity int,
 	f func(interface{}, []interface{}) Iter) CompilerOption {
 	return withFunction(name, minarity, maxarity, true,
@@ -91,7 +91,7 @@ func withFunction(name string, minarity, maxarity int, iter bool,
 // Note that input and inputs functions are not allowed by default. We have
 // to distinguish the query input and the values for input(s) functions. For
 // example, consider using inputs with --null-input. If you want to allow
-// input(s) functions, create an Iter and use WithInputIter option.
+// input(s) functions, create an [Iter] and use WithInputIter option.
 func WithInputIter(inputIter Iter) CompilerOption {
 	return func(c *compiler) {
 		c.inputIter = inputIter

preview.go

@@ -3,8 +3,8 @@ package gojq
 import "unicode/utf8"
 
 // Preview returns the preview string of v. The preview string is basically the
-// same as the jq-flavored JSON encoding returned by Marshal, but is truncated
-// by 30 bytes, and more efficient than truncating the result of Marshal.
+// same as the jq-flavored JSON encoding returned by [Marshal], but is truncated
+// by 30 bytes, and more efficient than truncating the result of [Marshal].
 //
 // This method is used by error messages of built-in operators and functions,
 // and accepts only limited types (nil, bool, int, float64, *big.Int, string,

query.go

@@ -19,7 +19,7 @@ type Query struct {
 
 // Run the query.
 //
-// It is safe to call this method of a *Query in multiple goroutines.
+// It is safe to call this method in goroutines, to reuse a parsed [*Query].
 func (e *Query) Run(v interface{}) Iter {
 	return e.RunWithContext(context.Background(), v)
 }

term_type.go

@@ -1,6 +1,6 @@
 package gojq
 
-// TermType represents the type of Term.
+// TermType represents the type of [Term].
 type TermType int
 
 // TermType list.
@@ -27,7 +27,7 @@ const (
 	TermTypeQuery
 )
 
-// GoString implements GoStringer.
+// GoString implements [fmt.GoStringer].
 func (termType TermType) GoString() (str string) {
 	defer func() { str = "gojq." + str }()
 	switch termType {