godoc: support multiple examples

gotest: document examples
go/doc: tidy comment

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5235055

diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go
index 8238dbb30465c54bff919d2ec2f3f5acb30bd70d..cf2c0c43098414628b34c05f189c002fa2b1f66e 100644 (file)
--- a/src/cmd/godoc/godoc.go
+++ b/src/cmd/godoc/godoc.go
@@ -458,10 +458,15 @@ func comment_htmlFunc(comment string) string {
        return buf.String()
 }
 
-func example_htmlFunc(name string, examples []*doc.Example, fset *token.FileSet) string {
+func example_htmlFunc(funcName string, examples []*doc.Example, fset *token.FileSet) string {
        var buf bytes.Buffer
        for _, eg := range examples {
-               if eg.Name != name {
+               // accept Foo or Foo_.* for funcName == Foo
+               name := eg.Name
+               if i := strings.Index(name, "_"); i >= 0 {
+                       name = name[:i]
+               }
+               if name != funcName {
                        continue
                }
 

diff --git a/src/cmd/gotest/doc.go b/src/cmd/gotest/doc.go
index 3ec425b403a5a1072948f4f4556f27ad1b569605..d60996103a41975bfab3736af51d391355307601 100644 (file)
--- a/src/cmd/gotest/doc.go
+++ b/src/cmd/gotest/doc.go
@@ -26,6 +26,18 @@ signature,
 
        func BenchmarkXXX(b *testing.B) { ... }
 
+Example functions may also be written. They are similar to test functions but,
+instead of using *testing.T to report success or failure, their output to
+os.Stdout and os.Stderr is compared against their doc comment.
+
+       // The output of this example function.
+       func ExampleXXX() {
+               fmt.Println("The output of this example function.")
+       }
+
+Multiple example functions may be provided for a given name XXX if they are
+discriminated by a distinct suffix starting with "_", such as ExampleXXX_2.
+
 See the documentation of the testing package for more information.
 
 By default, gotest needs no arguments.  It compiles all the .go files

diff --git a/src/pkg/go/doc/example.go b/src/pkg/go/doc/example.go
index 008f2b86b9597bb4df094f24d7bdc9a872851f90..7fdf0bcff6637eede8a87ff7a3b05b2d6eb12fdb 100644 (file)
--- a/src/pkg/go/doc/example.go
+++ b/src/pkg/go/doc/example.go
@@ -41,9 +41,9 @@ func Examples(pkg *ast.Package) []*Example {
        return examples
 }
 
-// isTest tells whether name looks like a test (or benchmark, according to prefix).
-// It is a Test (say) if there is a character after Test that is not a lower-case letter.
-// We don't want Testiness.
+// isTest tells whether name looks like a test, example, or benchmark.
+// It is a Test (say) if there is a character after Test that is not a
+// lower-case letter. (We don't want Testiness.)
 func isTest(name, prefix string) bool {
        if !strings.HasPrefix(name, prefix) {
                return false