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

Open
eli-darkly opened this issue Jul 1, 2020 · 1 comment

Comments

@eli-darkly
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 pkg.go.dev docs UI better than godoc.org, 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

Screenshot

image

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 godoc.org does it.

What did you see instead?

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

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jul 1, 2020

Thanks for making this suggestion.

/cc @julieqiu per owners.

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
3 participants
You can’t perform that action at this time.