cmd/go: run examples in source order, not name order

Add Order field to doc.Example and write doc comments there.

Fixes #4662.

R=golang-dev, iant
CC=golang-dev
https://golang.org/cl/7229071

src/cmd/go/test.bash

@@ -279,6 +279,9 @@ fi
 unset GOPATH
 rm -rf $d
 
+# Only succeeds if source order is preserved.
+./testgo test testdata/example[12]_test.go
+
 # clean up
 rm -rf testdata/bin testdata/bin1
 rm -f testgo

src/cmd/go/test.go

@@ -809,7 +809,9 @@ func (t *testFuncs) load(filename, pkg string, seen *bool) error {
 			*seen = true
 		}
 	}
-	for _, e := range doc.Examples(f) {
+	ex := doc.Examples(f)
+	sort.Sort(byOrder(ex))
+	for _, e := range ex {
 		if e.Output == "" && !e.EmptyOutput {
 			// Don't run examples with no output.
 			continue
@@ -820,6 +822,12 @@ func (t *testFuncs) load(filename, pkg string, seen *bool) error {
 	return nil
 }
 
+type byOrder []*doc.Example
+
+func (x byOrder) Len() int           { return len(x) }
+func (x byOrder) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
+func (x byOrder) Less(i, j int) bool { return x[i].Order < x[j].Order }
+
 var testmainTmpl = template.Must(template.New("main").Parse(`
 package main
 

src/cmd/go/testdata/example1_test.go

@@ -0,0 +1,23 @@
+// Copyright 2013 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Make sure that go test runs Example_Z before Example_A, preserving source order.
+
+package p
+
+import "fmt"
+
+var n int
+
+func Example_Z() {
+	n++
+	fmt.Println(n)
+	// Output: 1
+}
+
+func Example_A() {
+	n++
+	fmt.Println(n)
+	// Output: 2
+}

src/cmd/go/testdata/example2_test.go

@@ -0,0 +1,21 @@
+// Copyright 2013 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Make sure that go test runs Example_Y before Example_B, preserving source order.
+
+package p
+
+import "fmt"
+
+func Example_Y() {
+	n++
+	fmt.Println(n)
+	// Output: 3
+}
+
+func Example_B() {
+	n++
+	fmt.Println(n)
+	// Output: 4
+}

src/pkg/go/doc/example.go

@@ -18,6 +18,7 @@ import (
 	"unicode/utf8"
 )
 
+// An Example represents an example function found in a source files.
 type Example struct {
 	Name        string // name of the item being exemplified
 	Doc         string // example function doc string
@@ -26,8 +27,11 @@ type Example struct {
 	Comments    []*ast.CommentGroup
 	Output      string // expected output
 	EmptyOutput bool   // expect empty output
+	Order       int    // original source code order
 }
 
+// Examples returns the examples found in the files, sorted by Name field.
+// The Order fields record the order in which the examples were encountered.
 func Examples(files ...*ast.File) []*Example {
 	var list []*Example
 	for _, file := range files {
@@ -65,6 +69,7 @@ func Examples(files ...*ast.File) []*Example {
 				Comments:    file.Comments,
 				Output:      output,
 				EmptyOutput: output == "" && hasOutput,
+				Order:       len(flist),
 			})
 		}
 		if !hasTests && numDecl > 1 && len(flist) == 1 {