Skip to content

x/tools/cmd/godoc: HTML formatting doesn't make association between comments and code clear #16728

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
mkrautz opened this issue Aug 16, 2016 · 5 comments
Closed

x/tools/cmd/godoc: HTML formatting doesn't make association between comments and code clear #16728

mkrautz opened this issue Aug 16, 2016 · 5 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.9

Comments

@mkrautz
Copy link
Contributor

mkrautz commented Aug 16, 2016

screen shot 2016-08-16 at 10 51 42
@mkrautz
Copy link
Contributor Author

mkrautz commented Aug 16, 2016 •
edited
Loading

Hmm. I now see that that's just the way godoc does things.

I was just confused by the paragraph in the context of the "Variables" section.

It's not clear whether it documents what's above it (the errors), or the new context variables below it. Perhaps because neither the first errors section nor the new context section has a comment attached to them.

@bradfitz bradfitz changed the title net/http: Go 1.7 docs for net/http has out-of-place "Errors used by the HTTP server" paragraph x/tools/cmd/godoc: HTML formatting doesn't make association between comments and code clear Aug 16, 2016
@bradfitz bradfitz added this to the Go1.8Maybe milestone Aug 16, 2016
@bradfitz
Copy link
Contributor

/cc @broady

@bradfitz bradfitz mentioned this issue Aug 16, 2016
Closed
@quentinmit quentinmit added the NeedsFix The path to resolution is known, but the work has not been done. label Oct 10, 2016
@rsc rsc modified the milestones: Go1.9, Go1.8Maybe Oct 21, 2016
@gopherbot
Copy link
Contributor

CL https://golang.org/cl/32153 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/32154 mentions this issue.

@gopherbot
Copy link
Contributor

CL https://golang.org/cl/33279 mentions this issue.

@broady broady mentioned this issue Dec 1, 2016
Closed
@golang golang locked and limited conversation to collaborators Nov 23, 2017
henderjon pushed a commit to oggodoc/godoc that referenced this issue Jun 13, 2024
@luigi-riefolo @adonovan
cmd/godoc: show comment before code block
b0881c6 
The existing implementation shows a comment after its code block.
This causes confusion regarding how the comment relates to a code block.
Comments have been moved before their relative code blocks.

Fixes golang/go#16728

Change-Id: Ie07a6dd2f340a2555513662f263d26377060f93b
Reviewed-on: https://go-review.googlesource.com/33279
Reviewed-by: Alan Donovan <adonovan@google.com>
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.
Projects
None yet
Milestone
Go1.9
Development

No branches or pull requests
5 participants
@bradfitz @mkrautz @rsc @quentinmit @gopherbot