go/doc: ignore example functions with arguments

An Example function with arguments is not a valid example to be
run with go test. Don't return those functions from Examples. This
means that some functions that were previously showing up in
Examples will no longer show up. But those functions were not being
tested properly so the fact that they were showing up is misleading.

This fixes an issue where a confusing compiler error was showing
up when running go test on a file with an invalid example. While
that issue could have been fixed by returning an error, this is
more consistent with the behavior of go/doc.Examples, and the tests
checker in vet will catch this issue.

Fixes #35284

Change-Id: I2101a7d19f38522ef9c2e50967f9cfb30d28c730
Reviewed-on: https://go-review.googlesource.com/c/go/+/211357
Run-TryBot: Michael Matloob <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Jay Conrod <[email protected]>

Author: matloob

src/cmd/go/testdata/script/test_bad_example.txt

@@ -0,0 +1,13 @@
+# Tests that invalid examples are ignored.
+# Verifies golang.org/issue/35284
+go test x_test.go
+
+-- x_test.go --
+package  x
+
+import "fmt"
+
+func ExampleThisShouldNotHaveAParameter(thisShouldntExist int) {
+	fmt.Println("X")
+	// Output:
+}

src/go/doc/example.go

@@ -62,6 +62,9 @@ func Examples(testFiles ...*ast.File) []*Example {
 			if !ok || f.Recv != nil {
 				continue
 			}
+			if params := f.Type.Params; params.List != nil {
+				continue // function has params; not a valid example
+			}
 			numDecl++
 			name := f.Name.Name
 			if isTest(name, "Test") || isTest(name, "Benchmark") {