From 0c7e5d3b8db6668d6bdb16410d59c0ae4133400a Mon Sep 17 00:00:00 2001 From: cui fliter Date: Fri, 3 Nov 2023 19:18:00 +0800 Subject: [PATCH] path: add available godoc link Change-Id: I6d40a59cde4c3f1d5094f5126fdbc1195285195f Reviewed-on: https://go-review.googlesource.com/c/go/+/539577 Reviewed-by: Cherry Mui LUCI-TryBot-Result: Go LUCI Reviewed-by: Rob Pike Reviewed-by: Dmitri Shuralyov Auto-Submit: Dmitri Shuralyov --- src/path/filepath/match.go | 8 ++++---- src/path/filepath/path.go | 34 +++++++++++++++++----------------- src/path/match.go | 2 +- src/path/path.go | 2 +- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/path/filepath/match.go b/src/path/filepath/match.go index b5cc4b8cf3..12f0bfa7d3 100644 --- a/src/path/filepath/match.go +++ b/src/path/filepath/match.go @@ -35,7 +35,7 @@ var ErrBadPattern = errors.New("syntax error in pattern") // lo '-' hi matches character c for lo <= c <= hi // // Match requires pattern to match all of name, not just a substring. -// The only possible returned error is ErrBadPattern, when pattern +// The only possible returned error is [ErrBadPattern], when pattern // is malformed. // // On Windows, escaping is disabled. Instead, '\\' is treated as @@ -233,11 +233,11 @@ func getEsc(chunk string) (r rune, nchunk string, err error) { // 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 Match. The pattern may describe hierarchical names such as -// /usr/*/bin/ed (assuming the Separator is '/'). +// as in [Match]. The pattern may describe hierarchical names such as +// /usr/*/bin/ed (assuming the [Separator] is '/'). // // Glob ignores file system errors such as I/O errors reading directories. -// The only possible returned error is ErrBadPattern, when pattern +// The only possible returned error is [ErrBadPattern], when pattern // is malformed. func Glob(pattern string) (matches []string, err error) { return globWithLimit(pattern, 0) diff --git a/src/path/filepath/path.go b/src/path/filepath/path.go index 3d693f840a..075cea848e 100644 --- a/src/path/filepath/path.go +++ b/src/path/filepath/path.go @@ -73,7 +73,7 @@ const ( // by purely lexical processing. It applies the following rules // iteratively until no further processing can be done: // -// 1. Replace multiple Separator elements with a single one. +// 1. Replace multiple [Separator] elements with a single one. // 2. Eliminate each . path name element (the current directory). // 3. Eliminate each inner .. path name element (the parent directory) // along with the non-.. element that precedes it. @@ -231,7 +231,7 @@ func FromSlash(path string) string { return strings.ReplaceAll(path, "/", string(Separator)) } -// SplitList splits a list of paths joined by the OS-specific ListSeparator, +// SplitList splits a list of paths joined by the OS-specific [ListSeparator], // usually found in PATH or GOPATH environment variables. // Unlike strings.Split, SplitList returns an empty slice when passed an empty // string. @@ -239,7 +239,7 @@ func SplitList(path string) []string { return splitList(path) } -// Split splits path immediately following the final Separator, +// Split splits path immediately following the final [Separator], // separating it into a directory and file name component. // If there is no Separator in path, Split returns an empty dir // and file set to path. @@ -254,7 +254,7 @@ func Split(path string) (dir, file string) { } // Join joins any number of path elements into a single path, -// separating them with an OS specific Separator. Empty elements +// separating them with an OS specific [Separator]. Empty elements // are ignored. The result is Cleaned. However, if the argument // list is empty or all its elements are empty, Join returns // an empty string. @@ -281,7 +281,7 @@ func Ext(path string) string { // links. // If path is relative the result will be relative to the current directory, // unless one of the components is an absolute symbolic link. -// EvalSymlinks calls Clean on the result. +// EvalSymlinks calls [Clean] on the result. func EvalSymlinks(path string) (string, error) { return evalSymlinks(path) } @@ -290,7 +290,7 @@ func EvalSymlinks(path string) (string, error) { // If the path is not absolute it will be joined with the current // working directory to turn it into an absolute path. The absolute // path name for a given file is not guaranteed to be unique. -// Abs calls Clean on the result. +// Abs calls [Clean] on the result. func Abs(path string) (string, error) { return abs(path) } @@ -308,12 +308,12 @@ func unixAbs(path string) (string, error) { // Rel returns a relative path that is lexically equivalent to targpath when // joined to basepath with an intervening separator. That is, -// Join(basepath, Rel(basepath, targpath)) is equivalent to targpath itself. +// [Join](basepath, Rel(basepath, targpath)) is equivalent to targpath itself. // On success, the returned path will always be relative to basepath, // even if basepath and targpath share no elements. // An error is returned if targpath can't be made relative to basepath or if // knowing the current working directory would be necessary to compute it. -// Rel calls Clean on the result. +// Rel calls [Clean] on the result. func Rel(basepath, targpath string) (string, error) { baseVol := VolumeName(basepath) targVol := VolumeName(targpath) @@ -396,7 +396,7 @@ var SkipDir error = fs.SkipDir // as an error by any function. var SkipAll error = fs.SkipAll -// WalkFunc is the type of the function called by Walk to visit each +// WalkFunc is the type of the function called by [Walk] to visit each // file or directory. // // The path argument contains the argument to Walk as a prefix. @@ -412,9 +412,9 @@ var SkipAll error = fs.SkipAll // The info argument is the fs.FileInfo for the named path. // // The error result returned by the function controls how Walk continues. -// If the function returns the special value SkipDir, Walk skips the +// If the function returns the special value [SkipDir], Walk skips the // current directory (path if info.IsDir() is true, otherwise path's -// parent directory). If the function returns the special value SkipAll, +// parent directory). If the function returns the special value [SkipAll], // Walk skips all remaining files and directories. Otherwise, if the function // returns a non-nil error, Walk stops entirely and returns that error. // @@ -425,14 +425,14 @@ var SkipAll error = fs.SkipAll // // Walk calls the function with a non-nil err argument in two cases. // -// First, if an os.Lstat on the root directory or any directory or file +// First, if an [os.Lstat] on the root directory or any directory or file // in the tree fails, Walk calls the function with path set to that // directory or file's path, info set to nil, and err set to the error // from os.Lstat. // // Second, if a directory's Readdirnames method fails, Walk calls the // function with path set to the directory's path, info, set to an -// fs.FileInfo describing the directory, and err set to the error from +// [fs.FileInfo] describing the directory, and err set to the error from // Readdirnames. type WalkFunc func(path string, info fs.FileInfo, err error) error @@ -514,7 +514,7 @@ func walk(path string, info fs.FileInfo, walkFn WalkFunc) error { // directory in the tree, including root. // // All errors that arise visiting files and directories are filtered by fn: -// see the fs.WalkDirFunc documentation for details. +// see the [fs.WalkDirFunc] documentation for details. // // The files are walked in lexical order, which makes the output deterministic // but requires WalkDir to read an entire directory into memory before proceeding @@ -542,7 +542,7 @@ func WalkDir(root string, fn fs.WalkDirFunc) error { // directory in the tree, including root. // // All errors that arise visiting files and directories are filtered by fn: -// see the WalkFunc documentation for details. +// see the [WalkFunc] documentation for details. // // The files are walked in lexical order, which makes the output deterministic // but requires Walk to read an entire directory into memory before proceeding @@ -550,7 +550,7 @@ func WalkDir(root string, fn fs.WalkDirFunc) error { // // Walk does not follow symbolic links. // -// Walk is less efficient than WalkDir, introduced in Go 1.16, +// Walk is less efficient than [WalkDir], introduced in Go 1.16, // which avoids calling os.Lstat on every visited file or directory. func Walk(root string, fn WalkFunc) error { info, err := os.Lstat(root) @@ -611,7 +611,7 @@ func Base(path string) string { } // Dir returns all but the last element of path, typically the path's directory. -// After dropping the final element, Dir calls Clean on the path and trailing +// After dropping the final element, Dir calls [Clean] on the path and trailing // slashes are removed. // If the path is empty, Dir returns ".". // If the path consists entirely of separators, Dir returns a single separator. diff --git a/src/path/match.go b/src/path/match.go index 673bbc7ff6..d8b6809568 100644 --- a/src/path/match.go +++ b/src/path/match.go @@ -32,7 +32,7 @@ var ErrBadPattern = errors.New("syntax error in pattern") // lo '-' hi matches character c for lo <= c <= hi // // Match requires pattern to match all of name, not just a substring. -// The only possible returned error is ErrBadPattern, when pattern +// The only possible returned error is [ErrBadPattern], when pattern // is malformed. func Match(pattern, name string) (matched bool, err error) { Pattern: diff --git a/src/path/path.go b/src/path/path.go index 50065ac731..5149a92c4f 100644 --- a/src/path/path.go +++ b/src/path/path.go @@ -214,7 +214,7 @@ func IsAbs(path string) bool { } // Dir returns all but the last element of path, typically the path's directory. -// After dropping the final element using Split, the path is Cleaned and trailing +// After dropping the final element using [Split], the path is Cleaned and trailing // slashes are removed. // If the path is empty, Dir returns ".". // If the path consists entirely of slashes followed by non-slash bytes, Dir -- 2.48.1