x/pkgsite: missing source files listing

[tooolbox]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/CloudyKit/jet?tab=doc

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.122 Safari/537.36

Screenshot

(See below for screenshots)

What did you do?

Visited the page.

What did you expect to see?

What did you see instead?

I don't see a way anymore to directly access the source files in a package! This has been useful to me in the past. I'm not saying it needs to be in the same spot, but I think it should be kept.

As a comparison, godoc has the "Directories" section, and now pkg.go.dev has the "Subdirectories" tab but dropped the source file listing.

[julieqiu]

Thanks for the feedback, @tooolbox!

One way to access the list of files in the directory is by visiting:
https://pkg.go.dev/github.com/CloudyKit/jet?tab=overview

And clicking on the "Package Source Code" link: https://github.com/CloudyKit/jet/tree/v2.1.2.

Let me know if that achieves what you are looking for. If not - would you mind expanding on your current use case for the Package Files section on godoc.org?

/cc @fflewddur

[julieqiu]

Also related: #37819

[tooolbox]

Hi @julieqiu and thank you!

Yes, I did see that way to access the source files.

It doesn't, not quite. The main difference is that on godoc.org, you see just the .go files, so it's a very precise and filtered way to look at the package. When you link over to GitHub or wherever the source is, you are often confronted with a lot of noise: config files, go.mod and go.sum, scripts, etc. All of these files look the same, so you have to scan for the .go extension to see where they are, then you can look at their names.

A typical use case for me is when I'm looking at how a package works, I will often click on a method signature or two and then click through into the source to see how the function works, then go Back to the docs. After doing this a few times, I may ask, Where am I? Where are these signatures in relation to one another? at which point I will look at the source file listing to see how the package is divided up into chunks, and often click through to scan through and get a grip of the whole file. Since all the files in the listing are .go files you can quickly see the logical parts of the package without having to separate out by filetype. (example)

Hope that makes sense.

[julieqiu]

Yup, thanks for explaining!

We're currently working on addressing various design feedback with our UX team, so I'll make sure this comes up in our discussions as well. I'll update this issue once we have decided on any changes.

[benhoyt]

I noticed this lack too, and I think the individual .go file list under Package Files would still be useful. However, one feature I noticed now but hadn't noticed before (that godoc had as well) was that each name (type, function, etc) is a link to the source code for that definition -- that's great, though not quite as noticeable as the explicit .go files.

[fflewddur]

Hi @tooolbox and @benhoyt, thanks for reporting this! To make sure we understand the issue correctly, it sounds like your goal is to be able to quickly explore relevant parts of a package's source code, so that you can better understand what a package is doing under the hood. Is that accurate? Please let me know if there are also other reasons you're using those links; we want to make sure our solution accounts for them all.