[release-branch.go1.14] 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`

Fixes #38993

Change-Id: I7f9f368c7d9ccd9a2cbc48665f2cb9798c7b3a3f
GitHub-Last-Rev: 654fb450421266a0bb64518016944db22bd681e3
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>
(cherry picked from commit 585e31df63f6879c03b285711de6f9dcba1f2cb0)
Reviewed-on: https://go-review.googlesource.com/c/go/+/235579
Run-TryBot: Andrew Bonventre <andybons@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>

diff --git a/src/cmd/doc/doc_test.go b/src/cmd/doc/doc_test.go
index c0959acca130693d86fd3cae2f46fd57f00da337..fd2ae3082705e0bf9ba88f58bd8c138f46ea42a5 100644 (file)
--- a/src/cmd/doc/doc_test.go
+++ b/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",

diff --git a/src/cmd/doc/testdata/merge/aa.go b/src/cmd/doc/testdata/merge/aa.go
new file mode 100644 (file)
index 0000000..f8ab92d
--- /dev/null
+++ b/src/cmd/doc/testdata/merge/aa.go
@@ -0,0 +1,7 @@
+// Package comment A.
+package merge
+
+// A doc.
+func A() {
+       // A comment.
+}

diff --git a/src/cmd/doc/testdata/merge/bb.go b/src/cmd/doc/testdata/merge/bb.go
new file mode 100644 (file)
index 0000000..fd8cf3c
--- /dev/null
+++ b/src/cmd/doc/testdata/merge/bb.go
@@ -0,0 +1,7 @@
+// Package comment B.
+package merge
+
+// B doc.
+func B() {
+       // B comment.
+}

diff --git a/src/go/parser/interface.go b/src/go/parser/interface.go
index 500c98d49669ca97c590726ba2fb885a4b0e4400..54f9d7b80ac9a6a1c364514c498866694398db0c 100644 (file)
--- a/src/go/parser/interface.go
+++ b/src/go/parser/interface.go
@@ -133,13 +133,7 @@ func ParseFile(fset *token.FileSet, filename string, src interface{}, mode Mode)
 // first error encountered are returned.
 //
 func ParseDir(fset *token.FileSet, path string, filter func(os.FileInfo) bool, mode Mode) (pkgs map[string]*ast.Package, first error) {
-       fd, err := os.Open(path)
-       if err != nil {
-               return nil, err
-       }
-       defer fd.Close()
-
-       list, err := fd.Readdir(-1)
+       list, err := ioutil.ReadDir(path)
        if err != nil {
                return nil, err
        }