cmd/doc/pkg.go :: func Package.emit() calls format.Node() but the field-centric invocation calls into each struct-field's field.Doc.Text() which calls go/ast/ast.go CommentGroup.Text() which checks isDirective().

cc @robpike

This is surely an issue with the go/doc package, not the cmd/doc command, which just formats what the package provides.

@griesemer

Hi all, this popped up again - is there any way I can help get traction on it?

Change https://go.dev/cl/483055 mentions this issue: cmd/doc: format field doc comments when printing entire struct

Thanks! I tried it at gotip and I see something unexpected:

given this file:

// Package p is a package.
//
//magic:true
package p

// T is a type
//
//magic:true
type T struct {
	// Field is a field
	//magic:true
	Field int
}

go doc shows:

$ go doc --all .
package p // import "hockin.org/p"

Package p is a package.

TYPES

type T struct {
	// Field is a field
	//magic:true
	Field int
}
    T is a type

Note the directive is still present. gotip says:

$ gotip doc --all .
package p // import "hockin.org/p"

Package p is a package.

TYPES

type T struct {
	// Field is a field

	Field int
}
    T is a type

The directive is gone (yay) but there's now a blank like. Is that expected? @ianlancetaylor

@thockin It turns out to be rather painful to avoid. Or to put it more fairly, I was sufficiently exhausted by the effort tracking through all the code that I didn't feel like trying to fix that too.

It's because go/ast records positions for all comments and tokens, and go/format honors those positions to try to recreate the same format as the original file. That means that without extra work, when a comment line disappears, go/format inserts an extra line to get back to the expected position. Just disregarding the positions doesn't work, as that would mean that we lose track of which comments come before a field and which comments appear on the same line as a field. So removing the blank line is non-trivial, or, at least, I haven't seen a simple solution.

I do think that the gotip output is better. But as you say it's perhaps not ideal. By all means open a new issue.

ACK! Thanks.