x/tools/godoc/vfs: path separator character(s) in FileSystem, Opener interfaces is not specified

[dmitshur]

Problem

Documentation for net/http.FileSystem reads:

A FileSystem implements access to a collection of named files. The elements in a file path are separated by slash ('/', U+002F) characters, regardless of host operating system convention.

However, the FileSystem interface in golang.org/x/tools/godoc/vfs does not clearly specify what the path separator character is expected or allowed to be:

The FileSystem interface specifies the methods godoc is using to access the file system for which it serves documentation.

Edit: vfs.Opener interface is affected too:

Opener is a minimal virtual filesystem that can only open regular files.

We need to document it so this is clear to the users and implementors of the interfaces.

Proposed Resolution

Following logic, I expect that it has to be slash, regardless of host OS conventions, since it's meant to be a virtual filesystem that works across platform boundaries, just like http.FileSystem. (Of course, implementations may use non-slash separator paths to access underlying physical filesystems.)

Applying NeedsDecision label because I want someone else to confirm my reasoning that this is a documentation bug and that we must specify / as the only allowed path separator element. /cc @andybons @bradfitz

[dmitshur]

Actually, in the vfs.OS documentation, it says:

... because the slash-separated path passed to Open ...

Which implies that the paths are indeed slash-separated (at least to Open, but presumably that applies to all other methods). But this is very indirect and hard to spot.

[dmitshur]

I'll decide here that my analysis was right and this documentation issue needs to be fixed.

/cc @jayconrod FYI.

[seankhliao]

is this still relevant?

[dmitshur]

This issue is still valid and relevant to the package, but the package itself is probably less relevant now that io/fs exists. It should probably be deprecated in favor of that as part of #59056.