Proposal Details

Related to #64373, I would like to recommend that package fs gets some more top-level package documentation. At present, all that it states is:

Package fs defines basic interfaces to a file system. A file system can be provided by the host operating system but also by other packages.

This provides no information about the package's use and philosophy. There is a proposal document for package fs's design, but that would not be a suitable drop-in replacement to describe use. A couple of things come to mind that are worth mentioning that are not obvious:

1. For casual use, the a user of the package should primarily rely upon the package's top-level functions when they exist versus specialized interface methods. For instance, use function fs.ReadFile on a fs.FS instead of caring whether a fs.FS implements fs.ReadFileFS (runtime type assertion) and then calling (fs.ReadFileFS).ReadFile directly on the asserted value.

2. The package's documentation should suggest/tease a couple of common entrypoints for file system access and creation:

   • os.DirFS creates a filesystem around an ordinary POSIX file system.
   • package embed can provide embedded file systems in the binary.

   Without this information, it leaves a reader to wonder whether there are any batteries included, which is not a good developer experience.

3. The package's top-level documentation should demonstrate some common workflows, too. That would help make many of these points non-issues. There is one package example in the documentation (for WalkDir). If a user's new to this package, the WalkDir example may not be the best foray to demonstrate it.

There are enough symbols floating around in this package's identifier space that it's rather hard to tease apart critical API versus secondary API, which hinders overall comprehension of the package.