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

proposal: cmd/go: stop special-casing the "documentation" package #28162

Closed
heschik opened this issue Oct 11, 2018 · 8 comments

Comments

Projects
None yet
7 participants
@heschik
Copy link
Contributor

commented Oct 11, 2018

cmd/go and various libraries have a special case for files that say they're in the "documentation" package. This special case is not mentioned in any user-facing documentation that I can find. It's not used in any of the runtime/stdlib, and across all of GitHub it's only used once: https://github.com/golang/protobuf/blob/master/protoc-gen-go/doc.go.

This feature seems to date back to before Go 1.0, maybe before the go tool existed. Nobody I talked to knew what it was for. I think it should be removed at least for Go 2. Given the lack of usage, I think even Go 1 might be justifiable.

@griesemer

@gopherbot gopherbot added this to the Proposal milestone Oct 11, 2018

@griesemer

This comment has been minimized.

Copy link
Contributor

commented Oct 11, 2018

cc: @robpike , @rsc

@dmitshur

This comment has been minimized.

Copy link
Member

commented Oct 11, 2018

This special case is documented at https://golang.org/cmd/go/#hdr-Package_lists_and_patterns, in the third paragraph from the end:

Packages in a program need not have unique package names, but there are two reserved package names with special meaning. The name main indicates a command, not a library. Commands are built into binaries and cannot be imported. The name documentation indicates documentation for a non-Go program in the directory. Files in package documentation are ignored by the go command.

It's also mentioned in go/build.Context.Import documentation:

// In the directory containing the package, .go, .c, .h, and .s files are
// considered part of the package except for:
//
//	- .go files in package documentation

In 2015, there was issue #11801 asking if this special case was still worth having or could be removed, and while there was some interest in removing it (see #11801 (comment)), the decision made was to document it and keep it (see #11801 (comment) and CL 17954).

I think we should reconsider the decision for Go 2. This issue is a good place to do so.

@dmitshur dmitshur removed the Documentation label Oct 11, 2018

@griesemer

This comment has been minimized.

Copy link
Contributor

commented Oct 11, 2018

@dmitshur Thanks for tracking this down. I had a vague memory that this used to be there for command documentation, but I couldn't remember the details. We really don't need this mechanism anymore. Regarding the documentation you cited:

The name documentation indicates documentation for a non-Go program in the directory. Files in package documentation are ignored by the go command.

It seems to me that such documentation could just as well be in some other file not ending in .go.

@cznic

This comment has been minimized.

Copy link
Contributor

commented Oct 12, 2018

Given the lack of usage, I think even Go 1 might be justifiable.

I don't think that's possible under the Go 1 compatibility guarantee.

@dsnet

This comment has been minimized.

Copy link
Member

commented Oct 12, 2018

The v2 version of protoc-gen-go does not use the documentation package anymore. In fact, I was surprised to see that special case when poking around the old protoc-gen-go code.

@heschik

This comment has been minimized.

Copy link
Contributor Author

commented Oct 12, 2018

@cznic I agree that this is iffy, but I don't think it's out of line with things we've done before. The files can't contain any actual code, just documentation. I'm not clear on whether that documentation will even show up anywhere. So at best, you just delete the useless file, and at worst you change the package declaration. Yes, that means people might conceivably need to do a little work, but there is recent precedent -- the addition of the WASM port in 1.11 forced people to rename files named _js.go. I wouldn't advocate for this if the feature had widespread usage, but it clearly doesn't. I think it's worth considering.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Oct 17, 2018

I don't believe we can change this. It will invalidate old packages. Let's just accept it and move on. It's not hurting much.

Duplicate of #11801.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Oct 17, 2018

At the most, we could tie this to recognizing a newer Go version for a module tree and then change the behavior in new modules. But we'd have to keep the old logic around indefinitely for old trees. It doesn't seem worth introducing the irregularity of a special case at this point.

@rsc rsc closed this Oct 17, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.