go/printer: adjust formatting of structs with unexported fields

[dsnet]

The documentation for sql.NamedArg currently looks like:

type NamedArg struct {

    // Name of the parameter placeholder. If empty the ordinal position in the
    // argument list will be used.
    //
    // Name must omit any symbol prefix.
    Name string

    // Value of the parameter. It may be assigned the same value types as
    // the query arguments.
    Value interface{}
    // contains filtered or unexported fields
}

Can we fix the formatting to look nicer? I expect it to be like:

type NamedArg struct {
    // Name of the parameter placeholder. If empty the ordinal position in the
    // argument list will be used.
    //
    // Name must omit any symbol prefix.
    Name string

    // Value of the parameter. It may be assigned the same value types as
    // the query arguments.
    Value interface{}

    // Contains filtered or unexported fields.
}

This applies to interfaces as well.

[dsnet]

We could avoid the extra newline at the front if we move the _Named_Fields_Required struct{} to the bottom of the field list, but then we would run into #12884

[magical]

Godoc ultimately relies on the go/printer package for printing definitions, and it seems go/printer likes to preserve blank lines around comments. For example, the following code is unchanged by gofmt

package foo

type _ struct {

	// comment
	_ int
}

If you remove the comment, the blank line goes away as well

package foo

type _ struct {
	_ int
}

Without really knowing much about the internals of go/printer, it seems like a possible fix might be to teach go/printer not to preserve whitespace between an opening brace and a comment.

[dsnet]

@magical, I agree. I looked into this issue as well from the perspective of cmd/doc and came to the same conclusion that the issue in go/printer.

\cc @griesemer

[griesemer]

@magical The problem here is that the printer (must) follows the line information that's in the nodes. The reason there's a blank line here is that there's an unexported field in the source ( https://tip.golang.org/src/database/sql/sql.go?s=1976:2351#L71 ) which is removed from the doc. The remaining fields have their line positions unchanged, and thus for the printer it looks like that there's (at least) one empty line (it doesn't print more than one empty line).

This is non-trivial to fix with the current printer (how does it know that this is not the actual source?). The go/doc lib could try to adjust line numbers but that's really tricky for other reasons.

The real solution (and the solution for several pending printer issues) is a (overdue) rewrite of go/printer, based on a new internal format representation (currently in used by the compiler: cmd/compile/internal/syntax). But it's a big task and it's not high priority.

[griesemer]

Actually, there's perhaps a simple work-around which is a filter that post-processed the output generated by go/printer. Such a filter could simply look for struct { and an empty line (same for interfaces) and remove that empty line. Cheap and dirty but might to the trick. Feel free to submit a CL...

Leaving unplanned for now.

[magical]

@griesemer Correct me if i'm wrong—you're saying that because godoc deletes the _Named_Fields_Required field, that code gets seen by go/printer as

type NamedArg struct {


	// Name is the name of the parameter placeholder.
	//
	// If empty, the ordinal position in the argument list will be
	// used.
	//
	// Name must omit any symbol prefix.
	Name string

	// Value is the value of the parameter.
	// It may be assigned the same value types as the query
	// arguments.
	Value interface{}
}

Right?

I understand that. I'm proposing that go/printer be modified to always omit blank lines between an opening brace of a struct declaration and a comment, like it's already capable of doing when the opening brace is followed by a field. It doesn't have to know anything about the original source.

If that's too difficult or distruptive, i'd be happy to submit a kludge for godoc.

[dsnet]

The downside to a godoc-only kludge is that it doesn't benefit other doc-like tools like cmd/doc. It seems the solution is dirty in either case. So it's do a kludge in go/printer once or do the same kludge for every doc-like tool out there.