x/pkgsite: display struct field & interface method doc comments in a less code-ish way?

[eli-darkly]

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

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]

Thanks for making this suggestion.

/cc @julieqiu per owners.

[eli-darkly]

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]

@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]

@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]".