go/doc: tune association of a function with a type

Previously, we used to associate a function with its first returned type
assuming that it is a factory function for that type.

However, a function may return multiple types in which case it is usually
doing something else. Check for multiple return types, and treat it as
a normal function in that case. Maintain same behavior if the function
returns just one type.

Fixes #12839

Change-Id: Ic4ac11d322996f216f593b71f4e61ad4270d5213
Reviewed-on: https://go-review.googlesource.com/105575
Reviewed-by: Robert Griesemer <gri@golang.org>
Run-TryBot: Robert Griesemer <gri@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/src/go/doc/reader.go b/src/go/doc/reader.go
index 140f5872336dd7eea8df178209bd5d2a55401578..5d6f6e8fb00cc396e6e5c269316ad40561f62ed8 100644 (file)
--- a/src/go/doc/reader.go
+++ b/src/go/doc/reader.go
@@ -389,10 +389,12 @@ func (r *reader) readFunc(fun *ast.FuncDecl) {
                return
        }
 
-       // associate factory functions with the first visible result type, if any
+       // Associate factory functions with the first visible result type, if that
+       // is the only type returned.
        if fun.Type.Results.NumFields() >= 1 {
-               res := fun.Type.Results.List[0]
-               if len(res.Names) <= 1 {
+               var typ *namedType // type to associate the function with
+               numResultTypes := 0
+               for _, res := range fun.Type.Results.List {
                        // exactly one (named or anonymous) result associated
                        // with the first type in result signature (there may
                        // be more than one result)
@@ -403,13 +405,17 @@ func (r *reader) readFunc(fun *ast.FuncDecl) {
                                factoryType = t.Elt
                        }
                        if n, imp := baseTypeName(factoryType); !imp && r.isVisible(n) {
-                               if typ := r.lookupType(n); typ != nil {
-                                       // associate function with typ
-                                       typ.funcs.set(fun)
-                                       return
+                               if t := r.lookupType(n); t != nil {
+                                       typ = t
+                                       numResultTypes++
                                }
                        }
                }
+               // If there is exactly one result type, associate the function with that type.
+               if numResultTypes == 1 {
+                       typ.funcs.set(fun)
+                       return
+               }
        }
 
        // just an ordinary function

diff --git a/src/go/doc/testdata/issue12839.0.golden b/src/go/doc/testdata/issue12839.0.golden
new file mode 100644 (file)
index 0000000..76c2855
--- /dev/null
+++ b/src/go/doc/testdata/issue12839.0.golden
@@ -0,0 +1,33 @@
+// Package issue12839 is a go/doc test to test association of a ...
+PACKAGE issue12839
+
+IMPORTPATH
+       testdata/issue12839
+
+IMPORTS
+       p
+
+FILENAMES
+       testdata/issue12839.go
+
+FUNCTIONS
+       // F1 should not be associated with T1 
+       func F1() (*T1, *T2)
+
+       // F4 should not be associated with a type (same as F1) 
+       func F4() (a T1, b T2)
+
+
+TYPES
+       // 
+       type T1 struct{}
+
+       // F2 should be associated with T1 
+       func F2() (a, b, c T1)
+
+       // F3 should be associated with T1 because b.T3 is from a ...
+       func F3() (a T1, b p.T3)
+
+       // 
+       type T2 struct{}
+

diff --git a/src/go/doc/testdata/issue12839.1.golden b/src/go/doc/testdata/issue12839.1.golden
new file mode 100644 (file)
index 0000000..b0a327f
--- /dev/null
+++ b/src/go/doc/testdata/issue12839.1.golden
@@ -0,0 +1,36 @@
+// Package issue12839 is a go/doc test to test association of a ...
+PACKAGE issue12839
+
+IMPORTPATH
+       testdata/issue12839
+
+IMPORTS
+       p
+
+FILENAMES
+       testdata/issue12839.go
+
+FUNCTIONS
+       // F1 should not be associated with T1 
+       func F1() (*T1, *T2)
+
+       // F4 should not be associated with a type (same as F1) 
+       func F4() (a T1, b T2)
+
+
+TYPES
+       // 
+       type T1 struct{}
+
+       // F2 should be associated with T1 
+       func F2() (a, b, c T1)
+
+       // F3 should be associated with T1 because b.T3 is from a ...
+       func F3() (a T1, b p.T3)
+
+       // 
+       func (t T1) hello() string
+
+       // 
+       type T2 struct{}
+

diff --git a/src/go/doc/testdata/issue12839.2.golden b/src/go/doc/testdata/issue12839.2.golden
new file mode 100644 (file)
index 0000000..76c2855
--- /dev/null
+++ b/src/go/doc/testdata/issue12839.2.golden
@@ -0,0 +1,33 @@
+// Package issue12839 is a go/doc test to test association of a ...
+PACKAGE issue12839
+
+IMPORTPATH
+       testdata/issue12839
+
+IMPORTS
+       p
+
+FILENAMES
+       testdata/issue12839.go
+
+FUNCTIONS
+       // F1 should not be associated with T1 
+       func F1() (*T1, *T2)
+
+       // F4 should not be associated with a type (same as F1) 
+       func F4() (a T1, b T2)
+
+
+TYPES
+       // 
+       type T1 struct{}
+
+       // F2 should be associated with T1 
+       func F2() (a, b, c T1)
+
+       // F3 should be associated with T1 because b.T3 is from a ...
+       func F3() (a T1, b p.T3)
+
+       // 
+       type T2 struct{}
+

diff --git a/src/go/doc/testdata/issue12839.go b/src/go/doc/testdata/issue12839.go
new file mode 100644 (file)
index 0000000..500d495
--- /dev/null
+++ b/src/go/doc/testdata/issue12839.go
@@ -0,0 +1,38 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package issue12839 is a go/doc test to test association of a function
+// that returns multiple types.
+// See golang.org/issue/12839.
+package issue12839
+
+import "p"
+
+type T1 struct{}
+
+type T2 struct{}
+
+func (t T1) hello() string {
+       return "hello"
+}
+
+// F1 should not be associated with T1
+func F1() (*T1, *T2) {
+       return &T1{}, &T2{}
+}
+
+// F2 should be associated with T1
+func F2() (a, b, c T1) {
+       return T1{}, T1{}, T1{}
+}
+
+// F3 should be associated with T1 because b.T3 is from a different package
+func F3() (a T1, b p.T3) {
+       return T1{}, p.T3{}
+}
+
+// F4 should not be associated with a type (same as F1)
+func F4() (a T1, b T2) {
+       return T1{}, T2{}
+}