slices.SortFunc(list, func(a, b *CommentGroup) int {
		return cmp.Compare(a.Pos(), b.Pos())
	})
}

// A CommentMap maps an AST node to a list of comment groups
// associated with it. See [NewCommentMap] for a description of
// the association.
type CommentMap map[Node][]*CommentGroup

func (cmap CommentMap) addComment(n Node, c *CommentGroup) {
	list := cmap[n]
	if len(list) == 0 {
		list = []*CommentGroup{c}
	} else {

/* ERROR "5:24" */                 // position of ; on previous line
	package /* ERROR "7:2" */  // indented with tab
        import  /* ERROR "8:9" */  // indented with blanks
`
	m := CommentMap(strings.NewReader(src), regexp.MustCompile("^ ERROR "))
	found := 0 // number of errors found
	for line, errlist := range m {
		for _, err := range errlist {
			if err.Pos.Line() != line {

	"go/scanner"
	"go/token"
	"regexp"
	"strings"
	"testing"
)

type comment struct {
	line, col int    // comment position
	text      string // comment text, excluding "//", "/*", or "*/"
}

// commentMap collects all comments in the given src with comment text
// that matches the supplied regular expression rx and returns them as
// []comment lists in a map indexed by line number. The comment text is

func CommentsDo(src io.Reader, handler func(line, col uint, text string)) {
	var s scanner
	s.init(src, handler, comments)
	for s.tok != _EOF {
		s.next()
	}
}

// CommentMap collects all comments in the given src with comment text
// that matches the supplied regular expression rx and returns them as
// []Error lists in a map indexed by line number. The comment text is

	// x
	// y
	// int
	// print
	// x
	// y
}

// This example illustrates how to remove a variable declaration
// in a Go program while maintaining correct comment association
// using an ast.CommentMap.
func ExampleCommentMap() {
	// src is the input for which we create the AST that we
	// are going to manipulate.
	src := `
// This is the package comment.
package main

}

// pvacfgbody generates a simplified CFG for a slice of statements,
// containing only calls to putattr and the if statements affecting them.
func pvacfgbody(t *testing.T, fset *token.FileSet, cm ast.CommentMap, body []ast.Stmt) (start, end *pvacfgnode) {
	add := func(n *pvacfgnode) {
		if start == nil || end == nil {
			start = n
			end = n
		} else {
			end.then = n
			end = n
		}
	}

	conf.Check(pkgName, fset, files, &info)
	if listErrors {
		return
	}

	// collect expected errors
	errmap := make(map[string]map[int][]comment)
	for i, filename := range filenames {
		if m := commentMap(srcs[i], regexp.MustCompile("^ ERRORx? ")); len(m) > 0 {
			errmap[filename] = m
		}
	}

	// match against found errors
	var indices []int // list indices of matching errors, reused for each error

	conf.Check(pkgName, files, &info)
	if listErrors {
		return
	}

	// collect expected errors
	errmap := make(map[string]map[uint][]syntax.Error)
	for i, filename := range filenames {
		if m := syntax.CommentMap(bytes.NewReader(srcs[i]), regexp.MustCompile("^ ERRORx? ")); len(m) > 0 {
			errmap[filename] = m
		}
	}

	// match against found errors
	var indices []int // list indices of matching errors, reused for each error

// 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
// interpretation of the syntax tree by the manipulating program: except for Doc

		{"(*UnaryExpr).End", Method, 0},
		{"(*UnaryExpr).Pos", Method, 0},
		{"(*ValueSpec).End", Method, 0},
		{"(*ValueSpec).Pos", Method, 0},
		{"(CommentMap).Comments", Method, 1},
		{"(CommentMap).Filter", Method, 1},
		{"(CommentMap).String", Method, 1},
		{"(CommentMap).Update", Method, 1},
		{"(ObjKind).String", Method, 0},
		{"ArrayType", Type, 0},
		{"ArrayType.Elt", Field, 0},
		{"ArrayType.Lbrack", Field, 0},