go/doc: Last comment used as example output might start too early #3139
Labels
Comments
The correct way of fixing this is to recognize that the comment starting at the end of the last statement and the comment // Output: ... belong to different comment groups. If the go/parser would recognize this, this issue would not come up. I don't believe this is a Go 1 show stopper. I will file a long-term issue against the go/parser instead. |
|
Labels changed: added priority-later, removed priority-triage. Status changed to Duplicate. Merged into issue #3142. |
|
This issue was closed by revision f26d617. Status changed to Fixed. |
griesemer
added a commit
that referenced
this issue
May 11, 2015
««« backport afbf8db1baf4
go/parser: fix comment grouping (day 1 bug)
Comment groups must end at the end of a line (or the
next non-comment token) if the group started on a line
with non-comment tokens.
This is important for correct computation of "lead"
and "line" comments (Doc and Comment fields in AST nodes).
Without this fix, the "line" comment for F1 in the
following example:
type T struct {
F1 int // comment1
// comment2
F2 int
}
is "// comment1// comment2" rather than just "// comment1".
This bug was present from Day 1 but only visible when
looking at export-filtered ASTs where only comments
associated with AST nodes are printed, and only in rare
cases (e.g, in the case above, if F2 where not exported,
godoc would show "// comment2" anyway because it was
considered part of the "line" comment for F1).
The bug fix is very small (parser.go). The bulk of the
changes are additional test cases (parser_test.go).
The fix exposed a caching bug in go/printer via one of the
existing tests, hence the changes to printer.go.
As an aside, the fix removes the the need for empty lines
before an "// Output" comment for some special cases of
code examples (e.g.: src/pkg/strings/example_test.go, Count
example).
No impact on gofmt formatting of src, misc.
Fixes #3139.
R=rsc
CC=golang-dev
https://golang.org/cl/6209080
»»»
This issue was closed.
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
strings shows this issue: func ExampleCount() { fmt.Println(strings.Count("cheese", "e")) fmt.Println(strings.Count("five", "")) // before & after each rune // Output: // 3 // 5 } The "before & after each rune" hint why 5 is the answer belongs technically to the example output comment group. Thus go/doc does not recorgnise the "Output:" because it is not on the first line and godoc will not show the example output. This could be fixed by eiher adding a blank line to the example or by making go/doc aware of the "last statement may have a comment which does not belong to the example output". As this might be a not uncommon issue for users writing examples it might be worth fixing in go/doc (and not by a blank line in strings/example_test.go). I've got a working fix but it is a bit hacky.The text was updated successfully, but these errors were encountered: