Proposal Details

I would like to propose improving the documentation of the "optional" interfaces in package fs (e.g., fs.ReadDirFS, fs.ReadFileFS, fs.StatFS, and fs.SubFS). Namely, the documentation around these interfaces and the types that use them should be made symmetric.

To demonstrate what I mean by symmetric, look at the documentation of package io with io.Copy and io.WriterTo:

• io.Copy mentions "If src implements the WriterTo interface, the copy is implemented by calling src.WriteTo(dst)."
• io.WriterTo mentions "The Copy function uses WriterTo if available."

We can observe the following in the aforementioned interfaces in package fs:

• fs.ReadFileFS mentions "ReadFileFS is the interface implemented by a file system that provides an optimized implementation of ReadFile." That doesn't directly tell the reader that (package) function ReadFile calls this API if the file system implements this. Note how this is stylistically very different from what io.WriterTo mentions above.
• fs.ReadDirFS is identical to the previous.
• fs.StatFS mentions nothing about how fs.Stat will call this API if it is implemented.
• fs.SubFS identical to the previous, except with fs.Sub.

So the net effect, I think, should be this:

1. All APIs in package fs that act (e.g., type assertions at runtime) on these optional interfaces (documentation for consumers) should mention that they do. The way they do so, probably should be consistent in logical structure and verbiage.
2. All APIs in package fs that define the optional interfaces (documentation for API producers) should mention what consumer APIs act on them. Again, how the APIs that could act differently with these behaviors are enumerated should be consistent in structure.

package io documents this well, and I think can be used as a model here. Without the consistency and symmetry, it's not super clear whether the optional APIs are something that casual API consumers of the package need to consider.