Note this also affects things like go doc:

package p

type S struct {
	// Hello

	// Name is a test
	Name string
}

With Go 1.12.6:

$ go doc -all
package p // import "playground.com"


TYPES

type S struct {

        // Name is a test
        Name string
}

With tip:

$ go doc -all

package p // import "playground.com"


TYPES

type S struct {
        // Hello

        // Name is a test
        Name string
}

Tentatively marking as a release blocker therefore.

Thanks for reporting this.

This seems to be a direct consequence of CL 161177 to fix issue #10858.

However, issue #10858 was about godoc not displaying the entire documentation of structs, and I think it should be fixed inside godoc, not by changing go/parser to treat a comment separated by a blank line as part of a comment group.

go/ast.CommentGroup is clearly documented (emphasis mine):

A CommentGroup represents a sequence of comments with no other tokens and no empty lines between.

Unless I'm mistaken, this is too big of a change to low-level primitives like go/parser and go/ast to fix a minor godoc issue that I imagine can be fixed in godoc itself (but I haven't looked into this yet). I suspect many tools may depend on the current meaning of ast.CommentGroup and we should not (and cannot due to Go 1 compatibility promise) change it. But I will defer to @griesemer on this.

Based on my current understanding, I think we should roll back CL 161177 and try to fix #10858 in a less disruptive way.

I see. The CommentGroup thing is indeed an issue. However, the go doc output seems to be more accurate to me, since that was the whole point of #10858. Would you not expect // Hello to be printed ?

In any case, up to @griesemer to take a call.

cc @andybons as an FYI from a release perspective

I'm conscious of the fact that we're likely rapidly approaching beta2.

@agnivade - I think it makes sense to create a CL to revert this change in anticipation of @griesemer's decision. That way, at least, we're ready to hit "submit" (try bots having run etc) and not hold things up any more. Would you agree?

cc @mvdan

Change https://golang.org/cl/185040 mentions this issue: Revert "go/parser: include more comments in a struct or interface"

Looking at this again, I believe @dmitshur is correct; this should perhaps be fixed in godoc. In retrospective, we should not have changed the parser for this. My apologies, I should not have missed this.

@agnivade Thanks for providing the rollback CL.

A bit more on this subject:

1. Changing the parser - while it fixed the godoc issue with a relatively minor change - broke the more fundamental assumption about comment groups documented explicitly. We don't know what other tools/packages make the assumptions that comment groups have no empty lines.

2. It may be harder to fix issue go/doc: comments dropped from interior of interface definition #10858 in go doc, but that is probably the right place. Generally, it's not always 100% clear which comments belong together; so we should make that decision in a place with fewer dependencies (i.e., godoc rather than go/parser), so we can adjust it more easily as needed.

Thank you everyone for helping resolve this issue. I considered sending a CL to add a test so this ast.CommentGroup behavior doesn't regress without us noticing, but then I realized it would have to be a very specific test (comments separated by a blank line within a type declaration) and decided it wouldn't be as helpful as I originally thought. I can still send it if people think it'd be helpful.

I've added issue #10858 to a list of godoc-related issues I'm tracking and will be on the lookout for a way to resolve it in the future. Please feel free to /cc me on any new developments in that area.