go/ast: improved documentation for comments associated with an AST

Fixes #18593.

Change-Id: Ibe33ad9b536fee909120b3654b9d831e469eb285
Reviewed-on: https://go-review.googlesource.com/46370
Reviewed-by: Matthew Dempsky <mdempsky@google.com>

1 files changed, 13 insertions, 0 deletions

diff --git a/src/go/ast/ast.go b/src/go/ast/ast.go
index 2ecc48b741..7336a5d2d0 100644
--- a/src/go/ast/ast.go
+++ b/src/go/ast/ast.go
@@ -967,6 +967,19 @@ func (*FuncDecl) declNode() {}
 // appearance, including the comments that are pointed to from other nodes
 // via Doc and Comment fields.
 //
+// For correct printing of source code containing comments (using packages
+// go/format and go/printer), special care must be taken to update comments
+// when a File's syntax tree is modified: For printing, comments are inter-
+// spersed between tokens based on their position. If syntax tree nodes are
+// removed or moved, relevant comments in their vicinity must also be removed
+// (from the File.Comments list) or moved accordingly (by updating their
+// positions). A CommentMap may be used to facilitate some of these operations.
+//
+// Whether and how a comment is associated with a node depends on the inter-
+// pretation of the syntax tree by the manipulating program: Except for Doc
+// and Comment comments directly associated with nodes, the remaining comments
+// are "free-floating" (see also issues #18593, #20744).
+//
 type File struct {
 	Doc        *CommentGroup   // associated documentation; or nil
 	Package    token.Pos       // position of "package" keyword