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 · 4 comments
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite UX Issues that involve UXD/UXR input

Comments

@eli-darkly
Copy link

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.

@gopherbot gopherbot added this to the Unreleased milestone Jul 1, 2020
@dmitshur dmitshur added pkgsite NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. UX Issues that involve UXD/UXR input FeatureRequest labels Jul 1, 2020
@dmitshur
Copy link
Contributor

dmitshur commented Jul 1, 2020

Thanks for making this suggestion.

/cc @julieqiu per owners.

@eli-darkly
Copy link
Author

eli-darkly commented Oct 21, 2022

This may be more relevant now that Go 1.19 has doc links— since struct fields don't have their own paragraphs, you can't link to [StructTypeName.Field], and you also can't link to other symbols from the doc comment for a struct field.

@dmitshur
Copy link
Contributor

@eli-darkly Note that it is possible to link to individual fields inside structs or methods in interfaces on pkg.go.dev. For example, here's the DataSource field in ldclient.Config struct or the GetAll method in interfaces.DataStore interface.

@eli-darkly
Copy link
Author

@dmitshur What I meant was that you can't link to [StructTypeName.Field] in a doc comment. You could copy the link with anchor from a browser and paste the whole link URL into a comment, but it doesn't consider struct fields (or interface methods) to be addressable with the doc link syntax as far as I can tell. So you can't write something like "Use this method after setting [Config.DataSource] to..." but instead must write "after setting the DataSource field in [Config]", and conversely, the doc comment for such a field (or for an interface method) can't have something like "For an example of how this is used, see [SomeOtherMethod]".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite UX Issues that involve UXD/UXR input
Projects
None yet
Development

No branches or pull requests

4 participants