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
Assignees
Milestone

Comments

@dmitshur
Copy link
Member

@dmitshur 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

This comment has been minimized.

Copy link
Member Author

@dmitshur dmitshur commented Sep 17, 2018

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 label Sep 12, 2019
@dmitshur

This comment has been minimized.

Copy link
Member Author

@dmitshur dmitshur commented Sep 27, 2019

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

/cc @jayconrod FYI.

@dmitshur dmitshur added NeedsFix and removed NeedsDecision 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.