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/tools/cmd/godoc: show entities before cross-references #21686

Open
bcmills opened this issue Aug 29, 2017 · 1 comment
Open

x/tools/cmd/godoc: show entities before cross-references #21686

bcmills opened this issue Aug 29, 2017 · 1 comment
Labels
NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Unreleased

Comments

@bcmills
Copy link
Contributor

bcmills commented Aug 29, 2017

(A follow-on from #21685.)

Arguably the most useful godoc results are packages, followed by entities defined within those packages (types, variables, functions, interfaces, and methods). Cross-references are sometimes helpful, but rarely what I'm looking for when I'm searching golang.org.

For example, if I search for rand, odds are good I'm looking for the package documentation for either math/rand or crypto/rand. Unfortunately, at the moment there are so many cross-references that the latter result doesn't even appear above the fold.¹

¹
vaxrdmhgvxp
@gopherbot gopherbot added this to the Unreleased milestone Aug 29, 2017
@agnivade agnivade mentioned this issue Aug 7, 2018
Closed
@bcmills bcmills added the NeedsFix The path to resolution is known, but the work has not been done. label Aug 7, 2018
@gopherbot
Copy link

Change https://golang.org/cl/129135 mentions this issue: godoc: generate TOC from server-side for search page

gopherbot pushed a commit to golang/tools that referenced this issue Oct 19, 2018
@agnivade @bradfitz
godoc: generate TOC from server-side for search page
3e7aa9e 
Currently, we generate the TOC for a page dynamically after page load
through javascript. This is fine for pages with static content.

But for pages with dynamic output like /search, sometimes this causes a
noticeable page jump due to extensive DOM traversal. Also, the heuristics
to calculate the no. of columns is very rudimentary and fills the entire
above-the-fold area if the no. of results is very large.

Therefore, we generate the TOC from server side itself. And improve
the no. of columns heuristic further to accomodate up to 4 columns.

This improves page performance and utilizes real estate appropriately
according to the input.

Some screenshots at laptop (1366x768) resolution.
https://snag.gy/AXz2rP.jpg
https://snag.gy/th3Nn8.jpg

More can be found in the CL comments.

Fixes golang/go#21685
Updates golang/go#21686

Change-Id: Ia9b6dd1e67231d992709e4ba10ebdbedfe38b564
Reviewed-on: https://go-review.googlesource.com/c/129135
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
2 participants
@bcmills @gopherbot