Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
dmitshur opened this issue Sep 17, 2018 · 2 comments
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@dmitshur
Copy link
Contributor

dmitshur commented Sep 17, 2018

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 dmitshur added Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Sep 17, 2018
@gopherbot gopherbot added this to the Unreleased milestone Sep 17, 2018
@dmitshur
Copy link
Contributor Author

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 dmitshur changed the title x/tools/godoc/vfs: path separator character(s) in FileSystem interface is not specified x/tools/godoc/vfs: path separator character(s) in FileSystem, Opener interfaces is not specified Sep 17, 2018
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
@dmitshur
Copy link
Contributor Author

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

/cc @jayconrod FYI.

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Sep 27, 2019
@dmitshur dmitshur self-assigned this Nov 6, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

2 participants