cc: @robpike , @rsc

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 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.

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.

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.

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

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.

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.