io/fs: document optional interfaces in manner consistent with package io #64373
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
I would like to propose improving the documentation of the "optional" interfaces in
package fs
(e.g.,fs.ReadDirFS
,fs.ReadFileFS
,fs.StatFS
, andfs.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
withio.Copy
andio.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 whatio.WriterTo
mentions above.fs.ReadDirFS
is identical to the previous.fs.StatFS
mentions nothing about howfs.Stat
will call this API if it is implemented.fs.SubFS
identical to the previous, except withfs.Sub
.So the net effect, I think, should be this:
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.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.The text was updated successfully, but these errors were encountered: