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: Why does pkg.golang.org refer to "directories" when Go more commonly use the term "packages" #45495

Open
lazyhacker opened this issue Apr 10, 2021 · 6 comments

Comments

@lazyhacker
Copy link

@lazyhacker lazyhacker commented Apr 10, 2021

What is the URL of the page with the issue?

(example) https://pkg.go.dev/net/http

What is your user agent?

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.114 Safari/537.36

Screenshot

image

What did you do?

Visit pkg.golang.org to look at package/module documentation.

What did you expect to see?

On the left menu, a link called "Packages" that links to a module's package documentation.

What did you see instead?

Instead of calling it "packages", it refers to it as "Directories". Go generally refers to "packages". "Directories" gives the impression that it's for browsing the source files. Even the summary description all say "Package xyz implements ..." since the rules is to have the document say "Package xyz...", but the UI says

Directories

cgi
   Package cgi implements CGI (Common Gateway Interface) as specified in RFC 3875.

cookiejar
   Package cookiejar implements an in-memory RFC 6265-compliant http.CookieJar.

Would it make more sense to say "Packages" instead?

@gopherbot gopherbot added this to the Unreleased milestone Apr 10, 2021
@lazyhacker lazyhacker changed the title x/pkgsite: Why does pkg.golang.org refer to "directories" when Go thinks in term of "packages" x/pkgsite: Why does pkg.golang.org refer to "directories" when Go more commonly use the term "packages" Apr 10, 2021
@jba
Copy link
Contributor

@jba jba commented Apr 11, 2021

They're not always packages; sometimes they are directories that hold packages at a deeper level. We couldn't come up with a better term.

Loading

@jba jba removed this from the Unreleased milestone Apr 11, 2021
@jba jba added this to the pkgsite/unplanned milestone Apr 11, 2021
@bcmills
Copy link
Member

@bcmills bcmills commented Apr 12, 2021

Duplicate of #43327?

Loading

@fzipp
Copy link
Contributor

@fzipp fzipp commented Apr 13, 2021

Technically not all of them are packages, but all leaves of the shown tree are packages, and only packages are linked. The sole purpose of the non-package directories is to group packages. Tree components in user interfaces are usually titled according to the type of the target objects, not the type of the structuring objects.

Loading

@lazyhacker
Copy link
Author

@lazyhacker lazyhacker commented Apr 16, 2021

It seems like the intention of the section is to show the packages of the module and its package documentation so seems like "Packages" makes sense. Even the sub-directory section on the page looks like its primary intention is allow navigation to sub-package documentation rather then to actually expose the sub-"directories".

Loading

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Apr 27, 2021

This section doesn't just show packages - it also shows nested modules. For example, https://pkg.go.dev/golang.org/x/tools#section-directories shows gopls with a module label.

Loading

@fzipp
Copy link
Contributor

@fzipp fzipp commented May 1, 2021

Maybe it makes sense to split the "Directories" section into three separate sections:

  • Packages
  • Commands
  • Nested Modules

Loading

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