x/pkgsite: APIs that are not present on linux-amd64 are difficult to discover

[glycerine]

What is the URL of the page with the issue?

https://pkg.go.dev/golang.org/x/sys/unix

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36; I am on MacOS Sonoma 14.0 on amd64/intel hardware.

Screenshot

()

What did you do?

The ~/go/pkg/mod/golang.org/x/sys@v0.31.0/unix/fcntl_darwin.go has the following, Darwin specific, API:

// FcntlFstore performs a fcntl syscall for the F_PREALLOCATE command.                                
func FcntlFstore(fd uintptr, cmd int, fstore *Fstore_t) error {
    _, err := fcntl(int(fd), cmd, int(uintptr(unsafe.Pointer(fstore))))
    return err
}

However, it was hidden from me, I did not discover it, because pkg.go.dev does not display it.

(Incognito mode or not in Chrome does not seem to matter; darwin specific call is missing either way).

What did you see happen?

The list of functions available in golang.org/x/sys@v0.31.0/unix does not include FcntlFstore.

What did you expect to see?

The list of functions available in golang.org/x/sys@v0.31.0/unix should include FcntlFstore, despite it being Darwin-only, in the fcntl_darwin.go file.

@julieqiu

[prattmic]

Packages on pkg.go.dev are rendered as the package appears on linux-amd64. See https://pkg.go.dev/about#build-context for details.

The upper right corner of the "Documentation" section (https://pkg.go.dev/golang.org/x/sys/unix#section-documentation) has a drop-down to render for other common configurations.

[ianlancetaylor]

We could consider a different approach, like showing all the functions but labeling them with the system on which they are supported.

[glycerine]

We could consider a different approach, like showing all the functions but labeling them with the system on which they are supported.

Agreed. This would provide a much better user experience.

The choice of "rendered for" is pretty hidden. Another good option would
be to make is super clear even as you scroll, so it is always visible at the top. Either:

Or:

(edit: this need only happen for packages that are actually different on different platforms, of course.)

@prattmic Closing this was pre-mature. I consider myself a pretty sophisticated Go user, and if I am tripped up by this, and need Ian's help to figure it out, how are newbies ever going to navigate these waters? Please, re-open.

[prattmic]

Sure, apologies, I was overeager since the headline issue is technically working as intended. I agree this could be easier to use and I don't see an overarching issue for this, though #45298 is one usability suggestion.

[prattmic]

cc @golang/pkgsite

[glycerine]

Thanks Michael.

Also while someone is in the website code, there is a bug in the javascript that executes the change of display from linux to darwin. It fails to update the url address bar consistently, so that the URL may still say
https://pkg.go.dev/golang.org/x/sys/unix#section-readme (the default for linux/amd64) while the docs below are for Darwin. It should add the GOOS parameter to the URL,
so that it reads https://pkg.go.dev/golang.org/x/sys/unix?GOOS=darwin instead of just https://pkg.go.dev/golang.org/x/sys/unix#section-readme.

screenshot after using the drop-down selector to change from Linux/amd64 to Darwin/amd64:

Apologies for tacking one bug onto another, but there is so much context above, and it is such a related and small thing, might as well knock out both at once.