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

Fixes #2930.

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

diff --git a/src/cmd/go/test.go b/src/cmd/go/test.go
index 1633244556059d4c39895ec1fc0976d2aeae068a..e2bf44ed9d4175e671d99b45053696e0109cc7e0 100644 (file)
--- a/src/cmd/go/test.go
+++ b/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.
                `,
 }

diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go
index 3945039299fb1677eb57a9dca1902a8821e27ca2..e7c2f2135d5c23c026c16f8bfd31e4a6cfa87f7a 100644 (file)
--- a/src/cmd/godoc/godoc.go
+++ b/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)
-               code = strings.Replace(code, "\n    ", "\n", -1)
-               code = code[2 : len(code)-2]
+               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

diff --git a/src/pkg/go/doc/example.go b/src/pkg/go/doc/example.go
index d5b58d266436ed8247fd8c3abe44d637888eaa2b..1c23b0d95c3928edc3d7b5ba8de4a911cdf57d13 100644 (file)
--- a/src/pkg/go/doc/example.go
+++ b/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
+               }
+               list = append(list, flist...)
        }
-       return examples
+       return list
 }
 
 // isTest tells whether name looks like a test, example, or benchmark.

diff --git a/src/pkg/testing/testing.go b/src/pkg/testing/testing.go
index bbacf8ba502fb848bf1c844d2438930fec9e43e2..d5d60eae4cd20cb72929842cd4c284fccd762a5f 100644 (file)
--- a/src/pkg/testing/testing.go
+++ b/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 (