cmd/doc: match major module versions greater than 1 without needing a /vN suffix

[cespare]

What version of Go are you using (go version)?

I'm using Go 1.15, but I confirmed that none of the behavior I describe below is any different as of

go version devel +a3868028ac Sat Sep 19 09:43:15 2020 +0000 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

N/A

What did you do?

I have a module which uses github.com/go-chi/chi/v4 as a dependency. The go.mod contains

require (
        // ...
        github.com/go-chi/chi/v4 v4.0.0-rc1
        // ...
)

(And it doesn't involve any other module or package named chi.)

Inside this module, I was trying to use go doc to review some documentation for this dependency.

What did you expect to see?

I should be able to use the name chi to call up package docs for github.com/go-chi/chi/v4:

$ go doc chi.get
package chi // import "github.com/go-chi/chi/v4"

func (mx *Mux) Get(pattern string, handlerFn http.HandlerFunc)
    Get adds the route `pattern` that matches a GET http method to execute the
    `handlerFn` http.HandlerFunc.

What did you see instead?

The name chi is not enough to get go doc to bring up package docs for github.com/go-chi/chi/v4. I need to refer to it as chi/v4:

$ go doc chi.get
doc: symbol chi is not a type in package main installed in "."
exit status 1
$ go doc chi/v4.get
package chi // import "github.com/go-chi/chi/v4"

func (mx *Mux) Get(pattern string, handlerFn http.HandlerFunc)
    Get adds the route `pattern` that matches a GET http method to execute the
    `handlerFn` http.HandlerFunc.

By the way, is there some other issue tracking more general go doc improvements to better work with modules? I notice that go help doc only mentions GOPATH, not modules, so I suspect that there might be more work required in this area.

[agnivade]

@robpike @mvdan

By the way, is there some other issue tracking more general go doc improvements to better work with modules?

Not that I know of. Maybe you can file individual issues? Or are there too many of them?

[cespare]

Maybe you can file individual issues? Or are there too many of them?

I will file more issues as I find them. I was just wondering if there was a larger meta-issue I had missed.

To be clear, I haven't found other problems yet. It might all be working fine.

[mvdan]

I'm really surprised that noone has spotted this before. I assume this is a mix of not enough people knowing how to use go doc with short queries, and not many modules having post-v1 import paths in general.

I agree this needs a fix. At first glance it doesn't sound too complex, so perhaps it's a good first issue for someone wanting to get into cmd/doc.

In terms of a fix, perhaps we can use the package name for the lookup. That way, go doc foo.Bar will find test.tld/foo/v2 thanks to package foo, and in a similar case go doc foo.Bar would still find test.tld/foobar if named package foo.

[bcmills]

@mvdan, I like the idea of using the package statement for the lookup, but I worry that it would be too expensive (since it requires opening source files, instead of just reading listing them).

[mvdan]

since it requires opening source files, instead of just reading them

Sorry, what do you mean? Reading or parsing source files seems strictly more expensive than just opening the files.

As far as I know, go doc already has access to the package name without adding any extra work, but I might be wrong.

[bcmills]

Sorry, s/reading/listing/.

I think go doc examines the package name only after it has identified a candidate package. So that would work for your test.tld/foo/v2 example (if we hard-coded a /vN heuristic, which seems reasonable), but probably not your test.tld/foobar example.

[mvdan]

Simply using the last component of the package path, with a heuristic to remove /vN, also seems reasonable to me. Packages which use a package path differing from their package name should be rare and not particularly encouraged, anyway.

[ianlancetaylor]

Is something going to happen here for 1.17? Thanks.

[gopherbot]

Change https://go.dev/cl/457195 mentions this issue: cmd/doc: match major module versions without needing a /vN suffix