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.

[benhoyt]

@fflewddur Yes, that's right (for me). It's an exploratory and learning tool to help you get into the source code, for example how a certain standard library package is implemented, how the code authors split it up by file (which helps give a feel for how "big" the package is), etc.

[tooolbox]

Yes @fflewddur what you said is pretty accurate, with the addition of "able to quickly see a noise-free listing of the source files of a package, to see the logical divisions and better understand the anatomy and architecture of the codebase".

how the code authors split it up by file (which helps give a feel for how "big" the package is), etc.

Yeah, also the ratio of types & method signatures in the Index, to the amount of source files, gives you an idea of how dense the codebase is.

[fflewddur]

Ah, that makes sense. Thank you for the extra details!

[gopherbot]

Change https://golang.org/cl/240007 mentions this issue: internal/fetch: add explicit package file links to doc tab

[gopherbot]

Change https://golang.org/cl/246437 mentions this issue: content: display documentation source files

[tooolbox]

Very much appreciated that this was added!