cmd/doc: fix merging comments in -src mode

These changes fix go doc -src mode that vomits comments from random files if
filesystem does not sort files by name. The issue was with parse.ParseDir
using the Readdir order of files, which varies between platforms and filesystem
implementations. Another option is to merge comments using token.FileSet.Iterate
order in cmd/doc, but since ParseDir is mostly used in go doc, I’ve opted for
smaller change because it’s unlikely to break other uses or cause any perfomance
issues.

Example (macOS APFS): `go doc -src net.ListenPacket`

Change-Id: I7f9f368c7d9ccd9a2cbc48665f2cb9798c7b3a3f
GitHub-Last-Rev: 654fb45042
GitHub-Pull-Request: golang/go#36104
Reviewed-on: https://go-review.googlesource.com/c/go/+/210999
Run-TryBot: Rob Pike <r@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

src/cmd/doc/doc_test.go

@@ -724,6 +724,40 @@ var tests = []test{
 		},
 	},
 
+	// Merging comments with -src.
+	{
+		"merge comments with -src A",
+		[]string{"-src", p + "/merge", `A`},
+		[]string{
+			`A doc`,
+			`func A`,
+			`A comment`,
+		},
+		[]string{
+			`Package A doc`,
+			`Package B doc`,
+			`B doc`,
+			`B comment`,
+			`B doc`,
+		},
+	},
+	{
+		"merge comments with -src B",
+		[]string{"-src", p + "/merge", `B`},
+		[]string{
+			`B doc`,
+			`func B`,
+			`B comment`,
+		},
+		[]string{
+			`Package A doc`,
+			`Package B doc`,
+			`A doc`,
+			`A comment`,
+			`A doc`,
+		},
+	},
+
 	// No dups with -u. Issue 21797.
 	{
 		"case matching on, no dups",