go/ast: TypeSpec.Doc is nil? Have to grab documentation at GenDecl

[xibz]

What version of Go are you using (go version)?

1.11

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

darwin

Question

Noticed in the AST for type instantiated structures, that if I go to the Doc field in ast.TypeSpec the value is nil. I have to visit the ast.GenDecl node instead to grab doc fields.

Is this intended?
If so, why does ast.TypeSpec have a Doc field? Should Doc along with Comment be deprecated, as in mentioned in the docs, since comments/documentation really do not have anything to do with the type specification?

This can reproduce by parsing the code sample below

package foo

// documentation goes here
type Foo struct{}

func main() {
    f := Foo{}
}

expectation

ast.TypeSpec contain non-nil value for Doc when documentation is provided.

[ianlancetaylor]

CC @griesemer

[griesemer]

This is working as intended. A type declaration of the form

// comment
type T struct{}

is simply a shortcut for

// comment
type (
   T struct{}
)

since the comment is before the type keyword. If you want the the comment in TypeSpec.Doc field, then you need to write:

type (
   // comment
   T struct {}
)

There is really not much choice here: The AST needs to be able to represent both these cases (for gofmt), so it needs to be able to attach comments both with the grouped type declaration (GenDecl) and each individual type declaration (TypeSpec). For instance, in:

// comment1
type (
   // comment2
   T struct{}
)

there needs to be space for both comments.

Closing.

[xibz]

Thanks for the clarification @griesemer. That makes a lot of sense. I did not know you could shorthand structure definitions like that. Cheers :)