cmd/doc: make -src mode deterministic

These changes make cmd/doc -src deterministic, or, more precisely,
go/ast.MergePackageFiles, which is used by cmd/doc. So far the order of
comments depended on the package file map iteration order.

cmd/doc with -src flag has been inserting and omitting random comments
ever since the addition of -src flag. After investigating the code path
with the debugger, I’ve noticed that ast.File.Comments slice order changes
between invocations of the command. The bug was introduced in 3e24f2d6,
which ironically claimed to “fix formatting of -src output”. The commit
implemented the collection of comments by iterating over the map and
c7cdce13 “godoc: make ?m=src mode deterministic” did’t actually make
go/ast.MergePackageFiles deterministic.

I’ve found this issue after running “go doc -src sync.WaitGroup.Wait”.
There are likely other packages and functions affected, but the bug
should be somewhat reproducible across all Go versions.

Change-Id: Iae223e99550c0a3b54005c5cde36f909e655b66b
GitHub-Last-Rev: c49532f79fcd7529d7ad1a369c467abc59d4df0a
GitHub-Pull-Request: golang/go#33553
Reviewed-on: https://go-review.googlesource.com/c/go/+/189477
Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Robert Griesemer <gri@golang.org>

src/go/ast/filter.go

@@ -474,7 +474,9 @@ func MergePackageFiles(pkg *Package, mode MergeMode) *File {
 			}
 		}
 	} else {
-		for _, f := range pkg.Files {
+		// Iterate over filenames for deterministic order.
+		for _, filename := range filenames {
+			f := pkg.Files[filename]
 			imports = append(imports, f.Imports...)
 		}
 	}
@@ -484,7 +486,8 @@ func MergePackageFiles(pkg *Package, mode MergeMode) *File {
 	if mode&FilterUnassociatedComments == 0 {
 		comments = make([]*CommentGroup, ncomments)
 		i := 0
-		for _, f := range pkg.Files {
+		for _, filename := range filenames {
+			f := pkg.Files[filename]
 			i += copy(comments[i:], f.Comments)
 		}
 	}