io/fs: add godoc links

Change-Id: Icde42bd33d58f75acdede439f7525f9d06554140
Reviewed-on: https://go-review.googlesource.com/c/go/+/534096
Reviewed-by: qiulaidongfeng <2645477756@qq.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>

8 files changed, 43 insertions, 43 deletions

diff --git a/src/io/fs/format.go b/src/io/fs/format.go
index f490341f6c..4da6682f3a 100644
--- a/src/io/fs/format.go
+++ b/src/io/fs/format.go
@@ -52,7 +52,7 @@ func FormatFileInfo(info FileInfo) string {
 }
 
 // FormatDirEntry returns a formatted version of dir for human readability.
-// Implementations of DirEntry can call this from a String method.
+// Implementations of [DirEntry] can call this from a String method.
 // The outputs for a directory named subdir and a file named hello.go are:
 //
 //	d subdir/
diff --git a/src/io/fs/fs.go b/src/io/fs/fs.go
index 4ce4d1a528..09a9dad258 100644
--- a/src/io/fs/fs.go
+++ b/src/io/fs/fs.go
@@ -43,7 +43,7 @@ type FS interface {
 // Note that paths are slash-separated on all systems, even Windows.
 // Paths containing other characters such as backslash and colon
 // are accepted as valid, but those characters must never be
-// interpreted by an FS implementation as path element separators.
+// interpreted by an [FS] implementation as path element separators.
 func ValidPath(name string) bool {
 	if !utf8.ValidString(name) {
 		return false
@@ -73,8 +73,8 @@ func ValidPath(name string) bool {
 
 // A File provides access to a single file.
 // The File interface is the minimum implementation required of the file.
-// Directory files should also implement ReadDirFile.
-// A file may implement io.ReaderAt or io.Seeker as optimizations.
+// Directory files should also implement [ReadDirFile].
+// A file may implement [io.ReaderAt] or [io.Seeker] as optimizations.
 type File interface {
 	Stat() (FileInfo, error)
 	Read([]byte) (int, error)
@@ -82,7 +82,7 @@ type File interface {
 }
 
 // A DirEntry is an entry read from a directory
-// (using the ReadDir function or a ReadDirFile's ReadDir method).
+// (using the ReadDir function or a [ReadDirFile]'s ReadDir method).
 type DirEntry interface {
 	// Name returns the name of the file (or subdirectory) described by the entry.
 	// This name is only the final element of the path (the base name), not the entire path.
@@ -132,7 +132,7 @@ type ReadDirFile interface {
 
 // Generic file system errors.
 // Errors returned by file systems can be tested against these errors
-// using errors.Is.
+// using [errors.Is].
 var (
 	ErrInvalid    = errInvalid()    // "invalid argument"
 	ErrPermission = errPermission() // "permission denied"
@@ -161,10 +161,10 @@ type FileInfo interface {
 // The bits have the same definition on all systems, so that
 // information about files can be moved from one system
 // to another portably. Not all bits apply to all systems.
-// The only required bit is ModeDir for directories.
+// The only required bit is [ModeDir] for directories.
 type FileMode uint32
 
-// The defined file mode bits are the most significant bits of the FileMode.
+// The defined file mode bits are the most significant bits of the [FileMode].
 // The nine least-significant bits are the standard Unix rwxrwxrwx permissions.
 // The values of these bits should be considered part of the public API and
 // may be used in wire protocols or disk representations: they must not be
diff --git a/src/io/fs/glob.go b/src/io/fs/glob.go
index 0e529cd05d..db17156baf 100644
--- a/src/io/fs/glob.go
+++ b/src/io/fs/glob.go
@@ -20,15 +20,15 @@ type GlobFS interface {
 
 // Glob returns the names of all files matching pattern or nil
 // if there is no matching file. The syntax of patterns is the same
-// as in path.Match. The pattern may describe hierarchical names such as
+// as in [path.Match]. The pattern may describe hierarchical names such as
 // usr/*/bin/ed.
 //
 // Glob ignores file system errors such as I/O errors reading directories.
-// The only possible returned error is path.ErrBadPattern, reporting that
+// The only possible returned error is [path.ErrBadPattern], reporting that
 // the pattern is malformed.
 //
-// If fs implements GlobFS, Glob calls fs.Glob.
-// Otherwise, Glob uses ReadDir to traverse the directory tree
+// If fs implements [GlobFS], Glob calls fs.Glob.
+// Otherwise, Glob uses [ReadDir] to traverse the directory tree
 // and look for matches for the pattern.
 func Glob(fsys FS, pattern string) (matches []string, err error) {
 	return globWithLimit(fsys, pattern, 0)
diff --git a/src/io/fs/readdir.go b/src/io/fs/readdir.go
index 42aca49516..22ced48073 100644
--- a/src/io/fs/readdir.go
+++ b/src/io/fs/readdir.go
@@ -10,7 +10,7 @@ import (
 )
 
 // ReadDirFS is the interface implemented by a file system
-// that provides an optimized implementation of ReadDir.
+// that provides an optimized implementation of [ReadDir].
 type ReadDirFS interface {
 	FS
 
@@ -22,7 +22,7 @@ type ReadDirFS interface {
 // ReadDir reads the named directory
 // and returns a list of directory entries sorted by filename.
 //
-// If fs implements ReadDirFS, ReadDir calls fs.ReadDir.
+// If fs implements [ReadDirFS], ReadDir calls fs.ReadDir.
 // Otherwise ReadDir calls fs.Open and uses ReadDir and Close
 // on the returned file.
 func ReadDir(fsys FS, name string) ([]DirEntry, error) {
@@ -71,7 +71,7 @@ func (di dirInfo) String() string {
 	return FormatDirEntry(di)
 }
 
-// FileInfoToDirEntry returns a DirEntry that returns information from info.
+// FileInfoToDirEntry returns a [DirEntry] that returns information from info.
 // If info is nil, FileInfoToDirEntry returns nil.
 func FileInfoToDirEntry(info FileInfo) DirEntry {
 	if info == nil {
diff --git a/src/io/fs/readfile.go b/src/io/fs/readfile.go
index d3c181c0a9..41ca5bfcf6 100644
--- a/src/io/fs/readfile.go
+++ b/src/io/fs/readfile.go
@@ -7,7 +7,7 @@ package fs
 import "io"
 
 // ReadFileFS is the interface implemented by a file system
-// that provides an optimized implementation of ReadFile.
+// that provides an optimized implementation of [ReadFile].
 type ReadFileFS interface {
 	FS
 
@@ -22,13 +22,13 @@ type ReadFileFS interface {
 }
 
 // ReadFile reads the named file from the file system fs and returns its contents.
-// A successful call returns a nil error, not io.EOF.
+// A successful call returns a nil error, not [io.EOF].
 // (Because ReadFile reads the whole file, the expected EOF
 // from the final Read is not treated as an error to be reported.)
 //
-// If fs implements ReadFileFS, ReadFile calls fs.ReadFile.
+// If fs implements [ReadFileFS], ReadFile calls fs.ReadFile.
 // Otherwise ReadFile calls fs.Open and uses Read and Close
-// on the returned file.
+// on the returned [File].
 func ReadFile(fsys FS, name string) ([]byte, error) {
 	if fsys, ok := fsys.(ReadFileFS); ok {
 		return fsys.ReadFile(name)
diff --git a/src/io/fs/stat.go b/src/io/fs/stat.go
index 735a6e3281..bbb91c2eae 100644
--- a/src/io/fs/stat.go
+++ b/src/io/fs/stat.go
@@ -13,10 +13,10 @@ type StatFS interface {
 	Stat(name string) (FileInfo, error)
 }
 
-// Stat returns a FileInfo describing the named file from the file system.
+// Stat returns a [FileInfo] describing the named file from the file system.
 //
-// If fs implements StatFS, Stat calls fs.Stat.
-// Otherwise, Stat opens the file to stat it.
+// If fs implements [StatFS], Stat calls fs.Stat.
+// Otherwise, Stat opens the [File] to stat it.
 func Stat(fsys FS, name string) (FileInfo, error) {
 	if fsys, ok := fsys.(StatFS); ok {
 		return fsys.Stat(name)
diff --git a/src/io/fs/sub.go b/src/io/fs/sub.go
index ae20e030a9..9999e63b26 100644
--- a/src/io/fs/sub.go
+++ b/src/io/fs/sub.go
@@ -17,19 +17,19 @@ type SubFS interface {
 	Sub(dir string) (FS, error)
 }
 
-// Sub returns an FS corresponding to the subtree rooted at fsys's dir.
+// Sub returns an [FS] corresponding to the subtree rooted at fsys's dir.
 //
 // If dir is ".", Sub returns fsys unchanged.
-// Otherwise, if fs implements SubFS, Sub returns fsys.Sub(dir).
-// Otherwise, Sub returns a new FS implementation sub that,
+// Otherwise, if fs implements [SubFS], Sub returns fsys.Sub(dir).
+// Otherwise, Sub returns a new [FS] implementation sub that,
 // in effect, implements sub.Open(name) as fsys.Open(path.Join(dir, name)).
 // The implementation also translates calls to ReadDir, ReadFile, and Glob appropriately.
 //
 // Note that Sub(os.DirFS("/"), "prefix") is equivalent to os.DirFS("/prefix")
 // and that neither of them guarantees to avoid operating system
-// accesses outside "/prefix", because the implementation of os.DirFS
+// accesses outside "/prefix", because the implementation of [os.DirFS]
 // does not check for symbolic links inside "/prefix" that point to
-// other directories. That is, os.DirFS is not a general substitute for a
+// other directories. That is, [os.DirFS] is not a general substitute for a
 // chroot-style security mechanism, and Sub does not change that fact.
 func Sub(fsys FS, dir string) (FS, error) {
 	if !ValidPath(dir) {
diff --git a/src/io/fs/walk.go b/src/io/fs/walk.go
index eb98568cda..06228385d7 100644
--- a/src/io/fs/walk.go
+++ b/src/io/fs/walk.go
@@ -19,50 +19,50 @@ var SkipDir = errors.New("skip this directory")
 // as an error by any function.
 var SkipAll = errors.New("skip everything and stop the walk")
 
-// WalkDirFunc is the type of the function called by WalkDir to visit
+// WalkDirFunc is the type of the function called by [WalkDir] to visit
 // each file or directory.
 //
-// The path argument contains the argument to WalkDir as a prefix.
+// The path argument contains the argument to [WalkDir] as a prefix.
 // That is, if WalkDir is called with root argument "dir" and finds a file
 // named "a" in that directory, the walk function will be called with
 // argument "dir/a".
 //
-// The d argument is the fs.DirEntry for the named path.
+// The d argument is the [DirEntry] for the named path.
 //
-// The error result returned by the function controls how WalkDir
-// continues. If the function returns the special value SkipDir, WalkDir
+// The error result returned by the function controls how [WalkDir]
+// continues. If the function returns the special value [SkipDir], WalkDir
 // skips the current directory (path if d.IsDir() is true, otherwise
 // path's parent directory). If the function returns the special value
-// SkipAll, WalkDir skips all remaining files and directories. Otherwise,
+// [SkipAll], WalkDir skips all remaining files and directories. Otherwise,
 // if the function returns a non-nil error, WalkDir stops entirely and
 // returns that error.
 //
 // The err argument reports an error related to path, signaling that
-// WalkDir will not walk into that directory. The function can decide how
+// [WalkDir] will not walk into that directory. The function can decide how
 // to handle that error; as described earlier, returning the error will
 // cause WalkDir to stop walking the entire tree.
 //
-// WalkDir calls the function with a non-nil err argument in two cases.
+// [WalkDir] calls the function with a non-nil err argument in two cases.
 //
-// First, if the initial fs.Stat on the root directory fails, WalkDir
+// First, if the initial [Stat] on the root directory fails, WalkDir
 // calls the function with path set to root, d set to nil, and err set to
 // the error from fs.Stat.
 //
-// Second, if a directory's ReadDir method fails, WalkDir calls the
+// Second, if a directory's ReadDir method (see [ReadDirFile]) fails, WalkDir calls the
 // function with path set to the directory's path, d set to an
-// fs.DirEntry describing the directory, and err set to the error from
+// [DirEntry] describing the directory, and err set to the error from
 // ReadDir. In this second case, the function is called twice with the
 // path of the directory: the first call is before the directory read is
 // attempted and has err set to nil, giving the function a chance to
-// return SkipDir or SkipAll and avoid the ReadDir entirely. The second call
+// return [SkipDir] or [SkipAll] and avoid the ReadDir entirely. The second call
 // is after a failed ReadDir and reports the error from ReadDir.
 // (If ReadDir succeeds, there is no second call.)
 //
-// The differences between WalkDirFunc compared to filepath.WalkFunc are:
+// The differences between WalkDirFunc compared to [path/filepath.WalkFunc] are:
 //
-//   - The second argument has type fs.DirEntry instead of fs.FileInfo.
-//   - The function is called before reading a directory, to allow SkipDir
-//     or SkipAll to bypass the directory read entirely or skip all remaining
+//   - The second argument has type [DirEntry] instead of [FileInfo].
+//   - The function is called before reading a directory, to allow [SkipDir]
+//     or [SkipAll] to bypass the directory read entirely or skip all remaining
 //     files and directories respectively.
 //   - If a directory read fails, the function is called a second time
 //     for that directory to report the error.