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

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

Open
cespare opened this issue Sep 19, 2020 · 3 comments
Open
Labels
Milestone

Comments

@cespare
Copy link
Contributor

@cespare cespare commented Sep 19, 2020

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
Copy link
Contributor

@agnivade agnivade commented Sep 20, 2020

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

@agnivade agnivade changed the title cmd/go: make 'go doc' work better with major module versions greater than 1 cmd/doc: make 'go doc' work better with major module versions greater than 1 Sep 20, 2020
@cespare cespare changed the title cmd/doc: make 'go doc' work better with major module versions greater than 1 cmd/doc: match major module versions greater than 1 without needing a /vN suffix Sep 20, 2020
@cespare
Copy link
Contributor Author

@cespare cespare commented Sep 20, 2020

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.

@bcmills bcmills added the NeedsFix label Sep 20, 2020
@bcmills bcmills added this to the Go1.16 milestone Sep 20, 2020
@mvdan
Copy link
Member

@mvdan mvdan commented Sep 21, 2020

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.

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
5 participants
You can’t perform that action at this time.