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

Jump to bottom

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

Open
cespare opened this issue Sep 19, 2020 · 9 comments
Open

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

cespare opened this issue Sep 19, 2020 · 9 comments
Labels
help wanted modules NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Backlog

Comments

@cespare
Copy link
Contributor

cespare commented Sep 19, 2020 •
edited

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

@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
@agnivade agnivade added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label 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 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 The path to resolution is known, but the work has not been done. label Sep 20, 2020
@bcmills bcmills added this to the Go1.16 milestone Sep 20, 2020
@gopherbot gopherbot removed the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Sep 20, 2020
@mvdan
Copy link
Member

mvdan commented Sep 21, 2020 •
edited

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 bcmills added the modules label Oct 6, 2020
@bcmills bcmills mentioned this issue Oct 6, 2020
Open
@bcmills bcmills modified the milestones: Go1.16, Go1.17 Nov 2, 2020
@bcmills
Copy link
Contributor

bcmills commented Nov 2, 2020 •
edited

@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
Copy link
Member

mvdan commented Nov 2, 2020

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

bcmills commented Nov 2, 2020

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

mvdan commented Nov 2, 2020

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

Is something going to happen here for 1.17? Thanks.

@jayconrod jayconrod modified the milestones: Go1.17, Backlog May 17, 2021
@seankhliao seankhliao mentioned this issue Aug 9, 2022
Closed
@gopherbot
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
help wanted modules NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
7 participants
@jayconrod @cespare @agnivade @ianlancetaylor @mvdan @bcmills @gopherbot