diff options
| author | Damien Neil <dneil@google.com> | 2025-10-02 10:45:01 -0700 |
|---|---|---|
| committer | Gopher Robot <gobot@golang.org> | 2025-10-02 12:36:34 -0700 |
| commit | 4008e07080ef215e46f48e5e2f6b5d37d6d9cb9f (patch) | |
| tree | d8c91400487a27481d37d3c80793acbf388a2377 /src | |
| parent | 0e4e2e68323df08d9e4c876e5abc5b549bd247f5 (diff) | |
| download | go-4008e07080ef215e46f48e5e2f6b5d37d6d9cb9f.tar.xz | |
io/fs: move path name documentation up to the package doc comment
Perhaps surprisingly to users, io/fs path names are slash-separated.
Move the documentation for path names up to the top of the package
rather than burying it in the ValidPath documentation.
Change-Id: Id338df07c74a16be74c687ac4c45e0513ee40a8c
Reviewed-on: https://go-review.googlesource.com/c/go/+/708616
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
Auto-Submit: Damien Neil <dneil@google.com>
Diffstat (limited to 'src')
| -rw-r--r-- | src/io/fs/fs.go | 22 |
1 files changed, 16 insertions, 6 deletions
diff --git a/src/io/fs/fs.go b/src/io/fs/fs.go index 8f693f2574..fca07b818c 100644 --- a/src/io/fs/fs.go +++ b/src/io/fs/fs.go @@ -6,6 +6,19 @@ // A file system can be provided by the host operating system // but also by other packages. // +// # Path Names +// +// The interfaces in this package all operate on the same +// path name syntax, regardless of the host operating system. +// +// Path names are UTF-8-encoded, +// unrooted, slash-separated sequences of path elements, like “x/y/z”. +// Path names must not contain an element that is “.” or “..” or the empty string, +// except for the special case that the name "." may be used for the root directory. +// Paths must not start or end with a slash: “/x” and “x/” are invalid. +// +// # Testing +// // See the [testing/fstest] package for support with testing // implementations of file systems. package fs @@ -41,16 +54,13 @@ type FS interface { // ValidPath reports whether the given path name // is valid for use in a call to Open. // -// Path names passed to open are UTF-8-encoded, -// unrooted, slash-separated sequences of path elements, like “x/y/z”. -// Path names must not contain an element that is “.” or “..” or the empty string, -// except for the special case that the name "." may be used for the root directory. -// Paths must not start or end with a slash: “/x” and “x/” are invalid. -// // 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. +// See the [Path Names] section for more details. +// +// [Path Names]: https://pkg.go.dev/io/fs#hdr-Path_Names func ValidPath(name string) bool { if !utf8.ValidString(name) { return false |