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>

diff --git a/src/io/fs/fs.go b/src/io/fs/fs.go
index 8f693f2574a5b629b30e74a03f5d8be23c85bdd1..fca07b818c9a3bb658e6121e8eb6900e2f073cd7 100644 (file)
--- 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