go.dev: prefers linux/amd64 over another pair even when it results in zero exported identifiers and no package comment, while another GOOS/GOARCH pair has non-zero identifiers

[frazeradam]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/lxn/walk/declarative?tab=doc

What is your user agent?

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

Screenshot

What did you do?

Tried to read documentation for a Windows specific package.

What did you expect to see?

The documentation, or at least some way to set GOOS=windows. Since the package is Windows only, there is nothing for Linux.

What did you see instead?

Claims that the package has no documentation

[dmitshur]

at least some way to set GOOS=windows

Being able to explicitly choose a different value of GOOS or GOARCH is issue #37232, you can leave a 👍 reaction there.

Almost all .go files in that package have a // +build windows build constraint, except this one:

https://github.com/lxn/walk/blob/55ccb3a9f5c1dae7b1c94f70ea4f9db6afcb5021/declarative/nonwin.go

So there is a package for Windows, and it is empty. That is the documentation being shown.

If that file is removed, then there wouldn't be a package available for GOOS=linux, and pkg.go.dev would default to displaying documentation in GOOS=windows mode.

There are a few things that pkg.go.dev could consider doing differently:

• Always display the "documentation rendered using GOOS=foo GOARCH=bar" note at the bottom, even when the default linux/amd64 configuration is used. That would make it easier to tell what documentation one is looking at.
• Consider changing the heuristic of picking GOOS/GOARCH to display the package with. Currently, it picks the first pair that has non-zero .go files available. Maybe it should prefer a different build constraint if it has non-zero exported identifiers over one that has zero exported identifiers and no package comment.

/cc @julieqiu

[julieqiu]

At the moment, if GOOS != linux, we will display Documentation was rendered with GOOS={goos} and GOARCH={goarch} at the bottom of the page.

For example, for https://pkg.go.dev/syscall/js?tab=doc:

We can update this to display for all documentation, if that would be helpful. We are planning to eventually support #37232.

[dmitshur]

We can update this to display for all documentation, if that would be helpful.

I think it would be. I don't see much value in hiding it some of the time. Displaying it always is more predictable, and makes it possible to easily confirm what GOOS/GOARCH pair one is viewing at the moment. People who are not familiar with implementation details can't know for sure that no message means linux/amd64.

(Design-wise, there may be opportunities to present that information in a better location, but the point that it should always be accessible and consistent still applies.)

[frazeradam]

So adding the display will certainly solve the confusion issue, but will just leave the user understanding why they aren't seeing the information they want. Will there be a way to get the docs for a specific OS and/or architecture?

[julieqiu]

@frazeradam would #37232 address the issue of having docs for a specific OS?

[frazeradam]

I think it is exactly what would be needed @julieqiu. It solves the issue of not being able to see non-Linux documentation.

While certainly beyond the minimal viable product, having the Documentation was rendered with GOOS={goos} and GOARCH={goarch} at the bottom suggest that other OS/ARCH combination exist (if there are any build flags that cause some files to be OS/ARCH specific) would make it even better.

[julieqiu]

Great - I just merged a fix to update the Documentation was rendered with GOOS={goos} and GOARCH={goarch} note. It'll be live with the next deployment (sometime next week).

Updates for the feature to support docs for a specific OS and/or architecture will be posted on #37232.

Closing this issue.