Skip to content

x/pkgsite: missing struct docs #42425

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.

Sign up for GitHub

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
Closed
codyoss opened this issue Nov 6, 2020 · 6 comments
Closed

x/pkgsite: missing struct docs #42425

codyoss opened this issue Nov 6, 2020 · 6 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. pkgsite
Milestone
pkgsite/godoc.org...

Comments

@codyoss
Copy link
Member

codyoss commented Nov 6, 2020

What is the URL of the page with the issue?

https://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/secretmanager/v1#Secret

Screenshot

pkg.go.dev:
Screen Shot 2020-11-06 at 8 29 32 AM

godoc.org:

Screen Shot 2020-11-06 at 8 30 29 AM

What did you do?

Navigate to pkg.go.dev to look up some docs.

What did you expect to see?

Struct field docs.

What did you see instead?

No documentation. Here is the source for the docs: source.
@gopherbot gopherbot added this to the Unreleased milestone Nov 6, 2020
@jba jba added the NeedsFix The path to resolution is known, but the work has not been done. label Nov 6, 2020
@jba jba self-assigned this Nov 6, 2020
@jba jba modified the milestones: Unreleased, pkgsite/unplanned Nov 6, 2020
@jba
Copy link
Contributor

jba commented Nov 6, 2020

Thanks for finding this. I first feared that it was a bug in some recent work we've been doing on documentation rendering, but it actually predates that. It's related to that long field tag on Labels: overly long field tags turn off all other comments in a declaration. Should have a fix by Monday.

@dmitshur
Copy link
Member

dmitshur commented Nov 7, 2020

I think this is related to #38699. This seems like a slightly different type of occurrence (one where godoc.org isn’t affected), but the root problem might be the same. I started working on a fix for it in CL 240217, although there’s a merge conflict to resolve by now.

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/240217 mentions this issue: internal/fetch/dochtml/internal/render: preserve existing doc when trimming

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/276632 mentions this issue: internal/godoc/dochtml/internal/render: fix long-literal comment rendering

gopherbot pushed a commit to golang/pkgsite that referenced this issue Dec 14, 2020
@jba
internal/godoc/dochtml/internal/render: fix long-literal comment rend…
c069bf1 
…ering

The presence of a long literal caused all struct fields comments to be
removed.

This imperfectly fixes the problem by collecting all comments when
walking the declaration AST. Previously, it was thought that the
comments in an ast.CommentedNode would augment the existing comments
instead of replacing them (see golang/go#39219). The fix, as in
https://golang.org/cl/240217 and copied here, is to collect all
comments during the walk.

This isn't sufficient, because using a CommentedNode also turns off
the "contains filtered or unexported" comments that are normally added
during printing. So we have to add them back manually, which is tricky,
and can't be done perfectly (there are extra blank lines).

For golang/go#42425

Change-Id: I0bd8e5ddfc764bc3c7610575e1e3eedf9c0bfd84
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/276632
Trust: Jonathan Amsterdam <[email protected]>
Run-TryBot: Jonathan Amsterdam <[email protected]>
Reviewed-by: Julie Qiu <[email protected]>
@jba
Copy link
Contributor

jba commented Dec 15, 2020

The comments are back but the "contains filtered or unexported fields" message is not in the right place. Leaving this open.

@jba jba mentioned this issue Dec 16, 2020
Closed
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/284235 mentions this issue: internal/godoc/dochtml/internal/render: improve long-literal handling

@golang golang locked and limited conversation to collaborators Jan 20, 2022
@rsc rsc unassigned jba Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. pkgsite
Projects
None yet
Milestone
pkgsite/godoc.org-redirect
Development

No branches or pull requests
5 participants
@dmitshur @julieqiu @codyoss @gopherbot @jba