From: Robert Griesemer Date: Wed, 21 Jun 2017 18:51:34 +0000 (-0700) Subject: go/ast: improved documentation for comments associated with an AST X-Git-Tag: go1.9beta2~34 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=7a2fb4048e4f16c5cad5e90f87a62afd199d3367;p=gostls13.git 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 --- 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