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

x/pkgsite: missing source files listing #37863

Closed
tooolbox opened this issue Mar 15, 2020 · 12 comments
Closed

x/pkgsite: missing source files listing #37863

tooolbox opened this issue Mar 15, 2020 · 12 comments

Comments

@tooolbox
Copy link

@tooolbox tooolbox commented Mar 15, 2020

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?

package files

What did you see instead?

no package files

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.

@gopherbot gopherbot added this to the Unreleased milestone Mar 15, 2020
@gopherbot gopherbot added the pkgsite label Mar 15, 2020
@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Mar 16, 2020

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

@julieqiu julieqiu commented Mar 16, 2020

Also related: #37819

@tooolbox
Copy link
Author

@tooolbox tooolbox commented Mar 18, 2020

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

@julieqiu julieqiu commented Mar 18, 2020

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

@benhoyt benhoyt commented Mar 25, 2020

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.

@julieqiu julieqiu changed the title go.dev: Missing Source Files Listing go.dev: missing source files listing Mar 25, 2020
@fflewddur
Copy link

@fflewddur fflewddur commented Mar 25, 2020

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

@benhoyt benhoyt commented Mar 26, 2020

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

@tooolbox tooolbox commented Mar 26, 2020

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

@fflewddur fflewddur commented Mar 26, 2020

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

@julieqiu julieqiu changed the title go.dev: missing source files listing x/pkgsite: missing source files listing Jun 15, 2020
@gopherbot
Copy link

@gopherbot gopherbot commented Jun 26, 2020

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

@gopherbot
Copy link

@gopherbot gopherbot commented Aug 3, 2020

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

gopherbot pushed a commit to golang/pkgsite that referenced this issue Aug 3, 2020
A section for package files containing links to the source code
files was added in CL 240007.

These will now be displayed on pkg.go.dev.

For golang/go#37863

Change-Id: I35a7e74f631aa1f8c0a9775b0d721e7646843291
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/246437
Reviewed-by: Jonathan Amsterdam <jba@google.com>
@tooolbox
Copy link
Author

@tooolbox tooolbox commented Aug 21, 2020

Very much appreciated that this was added!

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
6 participants