all: add godoc link everywhere possible.

_js/README.md

@@ -7,7 +7,7 @@ It is transpiled from Go to JS using https://github.com/gopherjs/gopherjs.
 
 ### Sample usage
 
-```
+```javascript
 const sh = require('mvdan-sh')
 const syntax = sh.syntax
 

_js/main.go

@@ -157,7 +157,7 @@ func throw(err error) {
 	js.Global.Call("$throw", js.MakeFullWrapper(err))
 }
 
-// streamReader is an io.Reader wrapper for Node's stream.Readable. See
+// streamReader is an [io.Reader] wrapper for Node's stream.Readable. See
 // https://nodejs.org/api/stream.html#stream_class_stream_readable
 // TODO: support https://streams.spec.whatwg.org/#rs-class too?
 type streamReader struct {

cmd/shfmt/main.go

@@ -88,7 +88,7 @@ var (
 
 func init() {
 	// TODO: the flag package has constructors like newBoolValue;
-	// if we had access to something like that, we could use flag.Value everywhere,
+	// if we had access to something like that, we could use [flag.Value] everywhere,
 	// and avoid this monstrosity of a type switch.
 	for _, f := range allFlags {
 		switch f := f.(type) {
@@ -356,7 +356,7 @@ func walkPath(path string, entry fs.DirEntry) error {
 	// and we first want to tell if we should skip a path entirely.
 	//
 	// TODO: Should the call to Find with the language name check "ignore" too, then?
-	// Otherwise a [[bash]] section with ignore=true is effectively never used.
+	// Otherwise, a [[bash]] section with ignore=true is effectively never used.
 	//
 	// TODO: Should there be a way to explicitly turn off ignore rules when walking?
 	// Perhaps swapping the default to --apply-ignore=auto and allowing --apply-ignore=false?

expand/environ.go

@@ -120,7 +120,7 @@ func (v Variable) Resolve(env Environ) (string, Variable) {
 }
 
 // FuncEnviron wraps a function mapping variable names to their string values,
-// and implements Environ. Empty strings returned by the function will be
+// and implements [Environ]. Empty strings returned by the function will be
 // treated as unset variables. All variables will be exported.
 //
 // Note that the returned Environ's Each method will be a no-op.
@@ -140,7 +140,7 @@ func (f funcEnviron) Get(name string) Variable {
 
 func (f funcEnviron) Each(func(name string, vr Variable) bool) {}
 
-// ListEnviron returns an Environ with the supplied variables, in the form
+// ListEnviron returns an [Environ] with the supplied variables, in the form
 // "key=value". All variables will be exported. The last value in pairs is used
 // if multiple values are present.
 //
@@ -150,7 +150,7 @@ func ListEnviron(pairs ...string) Environ {
 	return listEnvironWithUpper(runtime.GOOS == "windows", pairs...)
 }
 
-// listEnvironWithUpper implements ListEnviron, but letting the tests specify
+// listEnvironWithUpper implements [ListEnviron], but letting the tests specify
 // whether to uppercase all names or not.
 func listEnvironWithUpper(upper bool, pairs ...string) Environ {
 	list := slices.Clone(pairs)

expand/expand.go

@@ -39,7 +39,7 @@ type Config struct {
 	Env Environ
 
 	// CmdSubst expands a command substitution node, writing its standard
-	// output to the provided io.Writer.
+	// output to the provided [io.Writer].
 	//
 	// If nil, encountering a command substitution will result in an
 	// UnexpectedCommandError.
@@ -58,9 +58,9 @@ type Config struct {
 	// Deprecated: use ReadDir2 instead.
 	ReadDir func(string) ([]fs.FileInfo, error)
 
-	// ReadDir is used for file path globbing.
-	// If nil, and ReadDir is nil as well, globbing is disabled.
-	// Use os.ReadDir to use the filesystem directly.
+	// ReadDir2 is used for file path globbing.
+	// If nil, and [ReadDir] is nil as well, globbing is disabled.
+	// Use [os.ReadDir] to use the filesystem directly.
 	ReadDir2 func(string) ([]fs.DirEntry, error)
 
 	// GlobStar corresponds to the shell option that allows globbing with
@@ -164,7 +164,7 @@ func (cfg *Config) envSet(name, value string) error {
 	return wenv.Set(name, Variable{Kind: String, Str: value})
 }
 
-// Literal expands a single shell word. It is similar to Fields, but the result
+// Literal expands a single shell word. It is similar to [Fields], but the result
 // is a single string. This is the behavior when a word is used as the value in
 // a shell variable assignment, for example.
 //
@@ -781,7 +781,7 @@ func (cfg *Config) expandUser(field string) (prefix, rest string) {
 	if name == "" {
 		// Current user; try via "HOME", otherwise fall back to the
 		// system's appropriate home dir env var. Don't use os/user, as
-		// that's overkill. We can't use os.UserHomeDir, because we want
+		// that's overkill. We can't use [os.UserHomeDir], because we want
 		// to use cfg.Env, and we always want to check "HOME" first.
 
 		if vr := cfg.Env.Get("HOME"); vr.IsSet() {
@@ -883,15 +883,15 @@ func (cfg *Config) glob(base, pat string) ([]string, error) {
 					match = filepath.Join(base, match)
 				}
 				match = pathJoin2(match, part)
-				// We can't use ReadDir2 on the parent and match the directory
+				// We can't use [Config.ReadDir2] on the parent and match the directory
 				// entry by name, because short paths on Windows break that.
-				// Our only option is to ReadDir2 on the directory entry itself,
+				// Our only option is to [Config.ReadDir2] on the directory entry itself,
 				// which can be wasteful if we only want to see if it exists,
 				// but at least it's correct in all scenarios.
 				if _, err := cfg.ReadDir2(match); err != nil {
 					if isWindowsErrPathNotFound(err) {
-						// Unfortunately, os.File.Readdir on a regular file on
-						// Windows returns an error that satisfies ErrNotExist.
+						// Unfortunately, [os.File.Readdir] on a regular file on
+						// Windows returns an error that satisfies [fs.ErrNotExist].
 						// Luckily, it returns a special "path not found" rather
 						// than the normal "file not found" for missing files,
 						// so we can use that knowledge to work around the bug.
@@ -977,10 +977,10 @@ func (cfg *Config) globDir(base, dir string, rx *regexp.Regexp, matchHidden bool
 			// No filtering.
 		} else if mode := info.Type(); mode&os.ModeSymlink != 0 {
 			// We need to know if the symlink points to a directory.
-			// This requires an extra syscall, as ReadDir on the parent directory
+			// This requires an extra syscall, as [Config.ReadDir] on the parent directory
 			// does not follow symlinks for each of the directory entries.
 			// ReadDir is somewhat wasteful here, as we only want its error result,
-			// but we could try to reuse its result as per the TODO in Config.glob.
+			// but we could try to reuse its result as per the TODO in [Config.glob].
 			if _, err := cfg.ReadDir2(filepath.Join(fullDir, info.Name())); err != nil {
 				continue
 			}

fileutil/file.go

@@ -49,8 +49,8 @@ const (
 	ConfNotScript ScriptConfidence = iota
 
 	// ConfIfShebang describes files which might be shell scripts, depending
-	// on the shebang line in the file's contents. Since CouldBeScript only
-	// works on fs.FileInfo, the answer in this case can't be final.
+	// on the shebang line in the file's contents. Since [CouldBeScript] only
+	// works on [fs.FileInfo], the answer in this case can't be final.
 	ConfIfShebang
 
 	// ConfIsScript describes files which are definitely shell scripts,
@@ -60,7 +60,7 @@ const (
 
 // CouldBeScript is a shortcut for CouldBeScript2(fs.FileInfoToDirEntry(info)).
 //
-// Deprecated: prefer CouldBeScript2, which usually requires fewer syscalls.
+// Deprecated: prefer [CouldBeScript2], which usually requires fewer syscalls.
 func CouldBeScript(info fs.FileInfo) ScriptConfidence {
 	return CouldBeScript2(fs.FileInfoToDirEntry(info))
 }

interp/api.go

@@ -75,7 +75,7 @@ type Runner struct {
 	// execHandler is responsible for executing programs. It must not be nil.
 	execHandler ExecHandlerFunc
 
-	// execMiddlewares grows with calls to ExecHandlers,
+	// execMiddlewares grows with calls to [ExecHandlers],
 	// and is used to construct execHandler when Reset is first called.
 	// The slice is needed to preserve the relative order of middlewares.
 	execMiddlewares []func(ExecHandlerFunc) ExecHandlerFunc
@@ -379,12 +379,12 @@ func ExecHandlers(middlewares ...func(next ExecHandlerFunc) ExecHandlerFunc) Run
 	}
 }
 
-// TODO: consider porting the middleware API in ExecHandlers to OpenHandler,
+// TODO: consider porting the middleware API in [ExecHandlers] to [OpenHandler],
 // ReadDirHandler, and StatHandler.
 
-// TODO(v4): now that ExecHandlers allows calling a next handler with changed
-// arguments, one of the two advantages of CallHandler is gone. The other is the
-// ability to work with builtins; if we make ExecHandlers work with builtins, we
+// TODO(v4): now that [ExecHandlers] allows calling a next handler with changed
+// arguments, one of the two advantages of [CallHandler] is gone. The other is the
+// ability to work with builtins; if we make [ExecHandlers] work with builtins, we
 // could join both APIs.
 
 // OpenHandler sets file open handler. See [OpenHandlerFunc] for more info.
@@ -457,7 +457,7 @@ func stdinFile(r io.Reader) (*os.File, error) {
 // Note that providing a non-nil standard input other than [os.File] will require
 // an [os.Pipe] and spawning a goroutine to copy into it,
 // as an [os.File] is the only way to share a reader with subprocesses.
-// See [os/exec.Cmd.Stdin].
+// See os/[exec.Cmd.Stdin].
 func StdIO(in io.Reader, out, err io.Writer) RunnerOption {
 	return func(r *Runner) error {
 		stdin, _err := stdinFile(in)
@@ -632,7 +632,7 @@ var bashOptsTable = [...]bashOpt{
 // know which option we're after at compile time. First come the shell options,
 // then the bash options.
 const (
-	// These correspond to indexes in shellOptsTable
+	// These correspond to indexes in [shellOptsTable]
 	optAllExport = iota
 	optErrExit
 	optNoExec
@@ -642,7 +642,7 @@ const (
 	optPipeFail
 
 	// These correspond to indexes (offset by the above seven items) of
-	// supported options in bashOptsTable
+	// supported options in [bashOptsTable]
 	optExpandAliases
 	optGlobStar
 	optNoCaseGlob
@@ -690,7 +690,7 @@ func (r *Runner) Reset() {
 		readDirHandler: r.readDirHandler,
 		statHandler:    r.statHandler,
 
-		// These can be set by functions like Dir or Params, but
+		// These can be set by functions like [Dir] or [Params], but
 		// builtins can overwrite them; reset the fields to whatever the
 		// constructor set up.
 		Dir:    r.origDir,
@@ -772,15 +772,15 @@ func IsExitStatus(err error) (status uint8, ok bool) {
 	return 0, false
 }
 
-// Run interprets a node, which can be a *File, *Stmt, or Command. If a non-nil
+// Run interprets a node, which can be a [*File], [*Stmt], or [Command]. If a non-nil
 // error is returned, it will typically contain a command's exit status, which
-// can be retrieved with IsExitStatus.
+// can be retrieved with [IsExitStatus].
 //
 // Run can be called multiple times synchronously to interpret programs
-// incrementally. To reuse a Runner without keeping the internal shell state,
+// incrementally. To reuse a [Runner] without keeping the internal shell state,
 // call Reset.
 //
-// Calling Run on an entire *File implies an exit, meaning that an exit trap may
+// Calling Run on an entire [*File] implies an exit, meaning that an exit trap may
 // run.
 func (r *Runner) Run(ctx context.Context, node syntax.Node) error {
 	if !r.didReset {
@@ -825,12 +825,12 @@ func (r *Runner) Exited() bool {
 	return r.shellExited
 }
 
-// Subshell makes a copy of the given Runner, suitable for use concurrently
+// Subshell makes a copy of the given [Runner], suitable for use concurrently
 // with the original. The copy will have the same environment, including
 // variables and functions, but they can all be modified without affecting the
 // original.
 //
-// Subshell is not safe to use concurrently with Run. Orchestrating this is
+// Subshell is not safe to use concurrently with [Run]. Orchestrating this is
 // left up to the caller; no locking is performed.
 //
 // To replace e.g. stdin/out/err, do StdIO(r.stdin, r.stdout, r.stderr)(r) on
@@ -840,7 +840,7 @@ func (r *Runner) Subshell() *Runner {
 		r.Reset()
 	}
 	// Keep in sync with the Runner type. Manually copy fields, to not copy
-	// sensitive ones like errgroup.Group, and to do deep copies of slices.
+	// sensitive ones like [errgroup.Group], and to do deep copies of slices.
 	r2 := &Runner{
 		Dir:            r.Dir,
 		Params:         r.Params,

interp/builtin.go

@@ -947,7 +947,7 @@ func (r *Runner) readLine(ctx context.Context, raw bool) ([]byte, error) {
 	// [cancelreader.NewReader] may fail under some circumstances, such as r.stdin being
 	// a regular file on Linux, in which case epoll returns an "operation not permitted" error
 	// given that regular files can always be read immediately. Polling them makes no sense.
-	// As such, if cancelreader fails, fall back to no cancellation, meaning this is best-effort.
+	// As such, if [cancelreader] fails, fall back to no cancellation, meaning this is best-effort.
 	//
 	// TODO: it would be nice if the cancelreader library classified errors so that we could
 	// safely handle "this file does not need polling" by skipping the polling as we do below

interp/handler.go

@@ -134,8 +134,9 @@ func DefaultExecHandler(killTimeout time.Duration) ExecHandlerFunc {
 
 		switch err := err.(type) {
 		case *exec.ExitError:
-			// Windows and Plan9 do not have support for syscall.WaitStatus
-			// with methods like Signaled and Signal, so for those, waitStatus is a no-op.
+			// Windows and Plan9 do not have support for [syscall.WaitStatus]
+			// with methods like Signaled and Signal, so for those, [waitStatus] is a no-op.
+			// Note: [waitStatus] is an alias [syscall.WaitStatus]
 			if status, ok := err.Sys().(waitStatus); ok && status.Signaled() {
 				if ctx.Err() != nil {
 					return ctx.Err()
@@ -209,7 +210,7 @@ func LookPath(env expand.Environ, file string) (string, error) {
 	return LookPathDir(env.Get("PWD").String(), env, file)
 }
 
-// LookPathDir is similar to [os/exec.LookPath], with the difference that it uses the
+// LookPathDir is similar to os/[exec.LookPath], with the difference that it uses the
 // provided environment. env is used to fetch relevant environment variables
 // such as PWD and PATH.
 //
@@ -218,7 +219,7 @@ func LookPathDir(cwd string, env expand.Environ, file string) (string, error) {
 	return lookPathDir(cwd, env, file, findExecutable)
 }
 
-// findAny defines a function to pass to lookPathDir.
+// findAny defines a function to pass to [lookPathDir].
 type findAny = func(dir string, file string, exts []string) (string, error)
 
 func lookPathDir(cwd string, env expand.Environ, file string, find findAny) (string, error) {
@@ -254,7 +255,7 @@ func lookPathDir(cwd string, env expand.Environ, file string, find findAny) (str
 	return "", fmt.Errorf("%q: executable file not found in $PATH", file)
 }
 
-// scriptFromPathDir is similar to LookPathDir, with the difference that it looks
+// scriptFromPathDir is similar to [LookPathDir], with the difference that it looks
 // for both executable and non-executable files.
 func scriptFromPathDir(cwd string, env expand.Environ, file string) (string, error) {
 	return lookPathDir(cwd, env, file, findFile)

interp/interp_test.go

@@ -26,7 +26,7 @@ import (
 	"mvdan.cc/sh/v3/syntax"
 )
 
-// runnerRunTimeout is the context timeout used by any tests calling Runner.Run.
+// runnerRunTimeout is the context timeout used by any tests calling [Runner.Run].
 // The timeout saves us from hangs or burning too much CPU if there are bugs.
 // All the test cases are designed to be inexpensive and stop in a very short
 // amount of time, so 5s should be plenty even for busy machines.

interp/runner.go

@@ -27,7 +27,7 @@ import (
 
 const (
 	// shellReplyPS3Var, or PS3, is a special variable in Bash used by the select command,
-	// while the shell is awaiting for input. the default value is shellDefaultPS3
+	// while the shell is awaiting for input. the default value is [shellDefaultPS3]
 	shellReplyPS3Var = "PS3"
 	// shellDefaultPS3, or #?, is PS3's default value
 	shellDefaultPS3 = "#? "
@@ -78,7 +78,7 @@ func (r *Runner) fillExpandConfig(ctx context.Context) {
 			dir := os.TempDir()
 
 			// We can't atomically create a random unused temporary FIFO.
-			// Similar to os.CreateTemp,
+			// Similar to [os.CreateTemp],
 			// keep trying new random paths until one does not exist.
 			// We use a uint64 because a uint32 easily runs into retries.
 			var path string
@@ -217,7 +217,7 @@ func (r *Runner) pattern(word *syntax.Word) string {
 	return str
 }
 
-// expandEnviron exposes Runner's variables to the expand package.
+// expandEnviron exposes [Runner]'s variables to the expand package.
 type expandEnv struct {
 	r *Runner
 }
@@ -987,7 +987,7 @@ func (r *Runner) call(ctx context.Context, pos syntax.Pos, args []string) {
 		r.inFunc = true
 
 		// Functions run in a nested scope.
-		// Note that Runner.exec below does something similar.
+		// Note that [Runner.exec] below does something similar.
 		origEnv := r.writeEnv
 		r.writeEnv = &overlayEnviron{parent: r.writeEnv, funcScope: true}
 

interp/test.go

@@ -179,7 +179,7 @@ func (r *Runner) unTest(ctx context.Context, op syntax.UnTestOperator, x string)
 			f = r.stderr
 		}
 		if f, ok := f.(interface{ Fd() uintptr }); ok {
-			// Support Fd methods such as the one on *os.File.
+			// Support [os.File.Fd] methods such as the one on [*os.File].
 			return term.IsTerminal(int(f.Fd()))
 		}
 		// TODO: allow term.IsTerminal here too if running in the

interp/unix_test.go

@@ -54,7 +54,7 @@ func TestRunnerTerminalStdIO(t *testing.T) {
 
 			r, _ := interp.New(interp.StdIO(secondaryReader, secondary, secondary))
 			go func() {
-				// To mimic os/exec.Cmd.Start, use a goroutine.
+				// To mimic os/[exec.Cmd.Start], use a goroutine.
 				if err := r.Run(context.Background(), file); err != nil {
 					t.Error(err)
 				}

interp/vars.go

@@ -276,7 +276,7 @@ func stringIndex(index syntax.ArithmExpr) bool {
 	return false
 }
 
-// TODO: make assignVal and setVar consistent with the WriteEnviron interface
+// TODO: make assignVal and [setVar] consistent with the [expand.WriteEnviron] interface
 
 func (r *Runner) assignVal(as *syntax.Assign, valType string) expand.Variable {
 	prev := r.lookupVar(as.Name.Value)

syntax/lexer.go

@@ -397,7 +397,7 @@ func (p *Parser) extendedGlob() bool {
 func (p *Parser) peekBytes(s string) bool {
 	peekEnd := int(p.bsp) + len(s)
 	// TODO: This should loop for slow readers, e.g. those providing one byte at
-	// a time. Use a loop and test it with testing/iotest.OneByteReader.
+	// a time. Use a loop and test it with [testing/iotest.OneByteReader].
 	if peekEnd > len(p.bs) {
 		p.fill()
 	}
@@ -818,7 +818,7 @@ func (p *Parser) newLit(r rune) {
 		w := utf8.RuneLen(r)
 		p.litBs = append(p.litBuf[:0], p.bs[p.bsp-uint(w):p.bsp]...)
 	default:
-		// don't let r == utf8.RuneSelf go to the second case as RuneLen
+		// don't let r == utf8.RuneSelf go to the second case as [utf8.RuneLen]
 		// would return -1
 		p.litBs = p.litBuf[:0]
 	}