[golang-dev] code review 7229071: cmd/go: run examples in source order, not name order (issue 7229071)

Reviewers: golang-dev_googlegroups.com,

Message:
Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go/


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

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

Fixes issue 4662.

Please review this at https://codereview.appspot.com/7229071/

Affected files:
M src/cmd/go/test.bash
M src/cmd/go/test.go
M src/pkg/go/doc/example.go


Index: src/cmd/go/test.bash
===================================================================
--- a/src/cmd/go/test.bash
+++ b/src/cmd/go/test.bash
@@ -279,6 +279,9 @@
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
Index: src/cmd/go/test.go
===================================================================
--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -809,7 +809,9 @@
*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 @@
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

Index: src/pkg/go/doc/example.go
===================================================================
--- a/src/pkg/go/doc/example.go
+++ b/src/pkg/go/doc/example.go
@@ -18,6 +18,7 @@
"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 @@
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 @@
Comments: file.Comments,
Output: output,
EmptyOutput: output == "" && hasOutput,
+ Order: len(flist),
})
}
if !hasTests && numDecl > 1 && len(flist) == 1 {