search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
123.98k stars 17.67k forks source link

x/pkgsite: Why does pkg.golang.org refer to "directories" when Go more commonly use the term "packages" #45495

Open lazyhacker opened 3 years ago

lazyhacker commented 3 years ago

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?

jba commented 3 years ago

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.

bcmills commented 3 years ago

Duplicate of #43327?

fzipp commented 3 years ago

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.

lazyhacker commented 3 years ago

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".

julieqiu commented 3 years ago

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.

fzipp commented 3 years ago

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