go/doc, godoc: regard lone examples as "whole file" examples

Fixes #2930.

R=r, gri, rsc
CC=golang-dev
https://golang.org/cl/5657048

src/cmd/go/test.go

@@ -187,6 +187,10 @@ Here is an example of an example:
 		Println("The output of this example function.")
 	}
 
+The entire test file is presented as the example when it contains a single
+example function, at least one other function, type, variable, or constant
+declaration, and no test or benchmark functions.
+
 See the documentation of the testing package for more information.
 		`,
 }

src/cmd/godoc/godoc.go

@@ -516,10 +516,13 @@ func example_htmlFunc(funcName string, examples []*doc.Example, fset *token.File
 			continue
 		}
 
-		// print code, unindent and remove surrounding braces
+		// print code
 		code := node_htmlFunc(eg.Body, fset)
+		if len(code) > 0 && code[0] == '{' {
+			// unindent and remove surrounding braces
 			code = strings.Replace(code, "\n    ", "\n", -1)
 			code = code[2 : len(code)-2]
+		}
 
 		err := exampleHTML.Execute(&buf, struct {
 			Name, Code, Output string

src/pkg/go/doc/example.go

@@ -9,6 +9,7 @@ package doc
 import (
 	"go/ast"
 	"go/printer"
+	"go/token"
 	"strings"
 	"unicode"
 	"unicode/utf8"
@@ -21,28 +22,47 @@ type Example struct {
 }
 
 func Examples(pkg *ast.Package) []*Example {
-	var examples []*Example
-	for _, src := range pkg.Files {
-		for _, decl := range src.Decls {
+	var list []*Example
+	for _, file := range pkg.Files {
+		hasTests := false // file contains tests or benchmarks
+		numDecl := 0      // number of non-import declarations in the file
+		var flist []*Example
+		for _, decl := range file.Decls {
+			if g, ok := decl.(*ast.GenDecl); ok && g.Tok != token.IMPORT {
+				numDecl++
+				continue
+			}
 			f, ok := decl.(*ast.FuncDecl)
 			if !ok {
 				continue
 			}
+			numDecl++
 			name := f.Name.Name
+			if isTest(name, "Test") || isTest(name, "Benchmark") {
+				hasTests = true
+				continue
+			}
 			if !isTest(name, "Example") {
 				continue
 			}
-			examples = append(examples, &Example{
+			flist = append(flist, &Example{
 				Name: name[len("Example"):],
 				Body: &printer.CommentedNode{
 					Node:     f.Body,
-					Comments: src.Comments,
+					Comments: file.Comments,
 				},
 				Output: f.Doc.Text(),
 			})
 		}
+		if !hasTests && numDecl > 1 && len(flist) == 1 {
+			// If this file only has one example function, some
+			// other top-level declarations, and no tests or
+			// benchmarks, use the whole file as the example.
+			flist[0].Body.Node = file
 		}
-	return examples
+		list = append(list, flist...)
+	}
+	return list
 }
 
 // isTest tells whether name looks like a test, example, or benchmark.

src/pkg/testing/testing.go

@@ -64,6 +64,9 @@
 //     func ExampleT_suffix() { ... }
 //     func ExampleT_M_suffix() { ... }
 //
+// The entire test file is presented as the example when it contains a single
+// example function, at least one other function, type, variable, or constant
+// declaration, and no test or benchmark functions.
 package testing
 
 import (