io/fs: provide package-level documentation for the package #64374
Labels
Documentation
Issues describing a change to documentation.
NeedsInvestigation
Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
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: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: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 afs.FS
instead of caring whether afs.FS
implementsfs.ReadFileFS
(runtime type assertion) and then calling(fs.ReadFileFS).ReadFile
directly on the asserted value.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.
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, theWalkDir
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.
The text was updated successfully, but these errors were encountered: