go/printer: CommentedNode behavior is partially undocumented

[dmitshur]

What did you do?

I read the documentation of package go/printer in order to understand how to use printer.CommentedNode.

CommentedNode is currently defined as:

// A CommentedNode bundles an AST node and corresponding comments.
// It may be provided as argument to any of the Fprint functions.
//
type CommentedNode struct {
	Node     interface{} // *ast.File, or ast.Expr, ast.Decl, ast.Spec, or ast.Stmt
	Comments []*ast.CommentGroup
}

It is also mentioned in the documentation of the Config.Fprint method:

// Fprint "pretty-prints" an AST node to output for a given configuration cfg.
// Position information is interpreted relative to the file set fset.
// The node type must be *ast.File, *CommentedNode, []ast.Decl, []ast.Stmt,
// or assignment-compatible to ast.Expr, ast.Decl, ast.Spec, or ast.Stmt.
//
func (cfg *Config) Fprint(output io.Writer, fset *token.FileSet, node interface{}) error

As well as the format.Node function, but there isn't additional information there.

What did you expect to see?

Documentation that would allow me to learn an answer to the question of "what happens to comments that are already a part of the Node being wrapped in a printer.CommentedNode?" without having to also read the source code.

What did you see instead?

Insufficient documentation to know what the intended behavior is.

/cc @griesemer @josharian

[gopherbot]

Change https://golang.org/cl/240217 mentions this issue: internal/fetch/dochtml/internal/render: preserve existing doc when trimming

[gopherbot]

Change https://golang.org/cl/276632 mentions this issue: internal/godoc/dochtml/internal/render: fix long-literal comment rendering

[jba]

Using a CommentedNode also turns off the comments added by Fprint, like "contains filtered or unexported fields". It's difficult to add those back manually, and I couldn't get rid of some extra blank lines. See https://golang.org/cl/276632. It's unclear if this is WAI or a bug.

All this is in service of modifying the doc to shorten long literals, replacing them with comments. If there were a way to do that by adding comment nodes directly to the AST, then that might be simpler.

[gopherbot]

Change https://golang.org/cl/284235 mentions this issue: internal/godoc/dochtml/internal/render: improve long-literal handling