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: display struct field & interface method doc comments in a less code-ish way? #39963

eli-darkly opened this issue Jul 1, 2020 · 1 comment
FeatureRequest NeedsInvestigation pkgsite UX


Copy link

@eli-darkly eli-darkly commented Jul 1, 2020

Apologies if this is something that's been suggested a million times, but... while I like the docs UI better than, it keeps the same way of presenting struct and interface documentation, which I find awkward. The definitions are displayed literally as Go code, with all the doc comments looking like just that: code comments. To me, there are several problems with this:

  1. It's unlike how any of the other doc content is displayed. Everything else is formatted as paragraphs of text, with distinct headings.
  2. In particular, the comment lines are rendered exactly as is, so if there's a too-long line you'll have to scroll right, and if the developer manually wrapped some lines much shorter than others it looks pretty ragged. All other doc content is rendered as wrapping paragraphs.
  3. Other than linking the names of types, none of the usual godoc formatting is applied: in particular, code examples look just like the other comment lines except for the extra indentation, and URLs are not linked.
  4. While the HTML does contain anchor IDs for these items, there's no visible indication of that - you would have to inspect the page source or make assumptions about how the anchors correspond to the symbol names.

I can't think of any conceptual reason why the doc comments for struct fields and interface methods should be treated so differently from types and implementation methods. If someone really wants to see what these definitions look like in their original Go code format, there's already a link to the source code right there.

What is the URL of the page with the issue?

Any page with a struct or an interface on it, for instance this or this.

What is your user agent?

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



What did you do?

Viewed the documentation for some structs and interfaces.

What did you expect to see?

No particular expectations, but it would've been nice to see something other than the way does it.

What did you see instead?

A block of Go code, the same way does it.

@gopherbot gopherbot added this to the Unreleased milestone Jul 1, 2020
@dmitshur dmitshur added pkgsite NeedsInvestigation UX FeatureRequest labels Jul 1, 2020
Copy link

@dmitshur dmitshur commented Jul 1, 2020

Thanks for making this suggestion.

/cc @julieqiu per owners.

@julieqiu julieqiu removed this from the Unreleased milestone Aug 27, 2020
@julieqiu julieqiu added this to the pkgsite/unreleased milestone Aug 27, 2020
@julieqiu julieqiu removed the website label Sep 19, 2020
@julieqiu julieqiu removed the website label Sep 22, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
FeatureRequest NeedsInvestigation pkgsite UX
None yet

No branches or pull requests

4 participants