go/types, types2: expand documentation for Info.Types map

Function types for function (and method) declarations do not
appear in Info.Types maps, only Info.Defs maps, because the
function type is implicit in the declaration and not a proper
(function) type expression. This is true even though the AST
represents these types via an (artificial) FuncType node.

Document this explicitly in the API.

No functional code changes.

Fixes #70908.

Change-Id: I2aa897daed04e7ad0fa8b625d9adc7b423c57387
Reviewed-on: https://go-review.googlesource.com/c/go/+/640776
Reviewed-by: Alan Donovan <[email protected]>
Auto-Submit: Robert Griesemer <[email protected]>
Reviewed-by: Robert Griesemer <[email protected]>
Reviewed-by: Robert Findley <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

src/cmd/compile/internal/types2/api.go

@@ -208,11 +208,19 @@ type Info struct {
 	//
 	// The Types map does not record the type of every identifier,
 	// only those that appear where an arbitrary expression is
-	// permitted. For instance, the identifier f in a selector
-	// expression x.f is found only in the Selections map, the
-	// identifier z in a variable declaration 'var z int' is found
-	// only in the Defs map, and identifiers denoting packages in
-	// qualified identifiers are collected in the Uses map.
+	// permitted. For instance:
+	// - an identifier f in a selector expression x.f is found
+	//   only in the Selections map;
+	// - an identifier z in a variable declaration 'var z int'
+	//   is found only in the Defs map;
+	// - an identifier p denoting a package in a qualified
+	//   identifier p.X is found only in the Uses map.
+	//
+	// Similarly, no type is recorded for the (synthetic) FuncType
+	// node in a FuncDecl.Type field, since there is no corresponding
+	// syntactic function type expression in the source in this case
+	// Instead, the function type is found in the Defs.map entry for
+	// the corresponding function declaration.
 	Types map[syntax.Expr]TypeAndValue
 
 	// If StoreTypesInSyntax is set, type information identical to

src/go/types/api.go

@@ -217,11 +217,19 @@ type Info struct {
 	//
 	// The Types map does not record the type of every identifier,
 	// only those that appear where an arbitrary expression is
-	// permitted. For instance, the identifier f in a selector
-	// expression x.f is found only in the Selections map, the
-	// identifier z in a variable declaration 'var z int' is found
-	// only in the Defs map, and identifiers denoting packages in
-	// qualified identifiers are collected in the Uses map.
+	// permitted. For instance:
+	// - an identifier f in a selector expression x.f is found
+	//   only in the Selections map;
+	// - an identifier z in a variable declaration 'var z int'
+	//   is found only in the Defs map;
+	// - an identifier p denoting a package in a qualified
+	//   identifier p.X is found only in the Uses map.
+	//
+	// Similarly, no type is recorded for the (synthetic) FuncType
+	// node in a FuncDecl.Type field, since there is no corresponding
+	// syntactic function type expression in the source in this case
+	// Instead, the function type is found in the Defs.map entry for
+	// the corresponding function declaration.
 	Types map[ast.Expr]TypeAndValue
 
 	// Instances maps identifiers denoting generic types or functions to their