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

Jump to bottom

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

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

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

myitcv opened this issue Nov 27, 2020 · 3 comments
Labels
help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite/dochtml Issues related to package documentation in pkgsite pkgsite
Milestone
pkgsite/dochtml

Comments

@myitcv
Copy link
Member

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.
@myitcv myitcv added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite labels Nov 27, 2020
@gopherbot gopherbot added this to the Unreleased milestone Nov 27, 2020
@rogpeppe
Copy link
Contributor

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

Issue #38575 seems to be related.

@julieqiu julieqiu modified the milestones: Unreleased, pkgsite/dochtml Nov 30, 2020
@hyangah hyangah added the pkgsite/dochtml Issues related to package documentation in pkgsite label May 20, 2022
@willfaught
Copy link
Contributor

Same issue for go doc, really. You can't do go doc os | grep ErrExist because it's not listed. You have to guess which var group it's in.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite/dochtml Issues related to package documentation in pkgsite pkgsite
Projects
None yet
Milestone
pkgsite/dochtml
Development

No branches or pull requests
7 participants
@willfaught @rogpeppe @dmitshur @myitcv @hyangah @julieqiu @gopherbot