go/build: go files in package documentation ignored; still desired behavior?

[tarakju]

I tried to make a package called documentation today. Looks like .go files in any package called documentation are ignored. @aclements helped me do some sleuthing and discovered the original reason for a magic documentation package:

https://codereview.appspot.com/7475048/patch/10001/11001

There is a comment in go/build that mentions this behavior. However, go help packages does not include this behavior in its list of reserved names.

It was unclear if this behavior is still desired (perhaps for backwards compatibility?), or if it should be removed. At the very least, seems like the documentation should be updated if this is still correct.

[aclements]

@tarakju's case was particularly confusing because he was actually in a directory called "documentation" creating a "package documentation" source file and go build was telling him there were no buildable go files. There were no hints that this might be a special case (and no documentation where the other special cases of go build are documented). The original intent of this rule was to let you put a "package documentation" source file alongside "package main" source files in a directory presumably called neither "documentation" or "main", so the user was clearly opting in to some special case.

[rsc]

We should remove this special case.

[adg]

Can we remove the special case while preserving compatibility? I guess we could make the tool ignore .go files in package documentation only if there are files from another package in the same directory.

[rsc]

I chickened out and documented this instead.

[gopherbot]

CL https://golang.org/cl/17954 mentions this issue.