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/105575Reviewed-by: Robert Griesemer <gri@golang.org>
Run-TryBot: Robert Griesemer <gri@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

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

src/go/doc/testdata/issue12839.0.golden

+// 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{}
+

src/go/doc/testdata/issue12839.1.golden

+// 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{}
+

src/go/doc/testdata/issue12839.2.golden

+// 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{}
+

src/go/doc/testdata/issue12839.go

+// 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{}
+}