From 4008e07080ef215e46f48e5e2f6b5d37d6d9cb9f Mon Sep 17 00:00:00 2001 From: Damien Neil Date: Thu, 2 Oct 2025 10:45:01 -0700 Subject: [PATCH] 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 Reviewed-by: Alan Donovan Auto-Submit: Damien Neil --- src/io/fs/fs.go | 22 ++++++++++++++++------ 1 file 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 -- 2.52.0