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: exported variables should appear in the index and be anchored #42855

Open
myitcv opened this issue Nov 27, 2020 · 2 comments
Open

x/pkgsite: exported variables should appear in the index and be anchored #42855

myitcv opened this issue Nov 27, 2020 · 2 comments

Comments

@myitcv
Copy link
Member

@myitcv myitcv commented Nov 27, 2020

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/frankban/quicktest@v1.11.2

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.67 Safari/537.36

Screenshot

See below

What did you do?

Related to #42652

What did you expect to see?

I expected to be able to:

  • quickly and discover all variables exported by this package
  • quickly and easily find the IsNil exported variable (in this case I knew it existed), read its documentation, and be able to link to its anchor for reference

What did you see instead?

  • The variable not listed in the index
  • No anchored heading for the variable
  • The documentation buried in the documentation for the Checker type, with the IsNil documentation seemingly being a continuation of the IsFalse variable

Screen Shot 2020-11-27 at 10 24 56

To my mind there's a real discoverability problem here because IsNil and friends are exported precisely because they are intended to be used.

@rogpeppe
Copy link
Contributor

@rogpeppe rogpeppe commented Nov 27, 2020

FWIW it's for exactly this reason that we ended up having to duplicate all the variable doc comments into the package-level doc comment - the discoverability of the variables, a crucial part of this package's API, was poor enough that people complained that they were unable to find out how the package worked. This was with godoc.org, not with pkgsite, but the issue remains.

@dmitshur
Copy link
Contributor

@dmitshur dmitshur commented Nov 27, 2020

Issue #38575 seems to be related.

@julieqiu julieqiu removed this from the Unreleased milestone Nov 30, 2020
@julieqiu julieqiu added this to the pkgsite/dochtml milestone Nov 30, 2020
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
5 participants