]> Cypherpunks repositories - gostls13.git/commit
godoc: make example code more readable with new comment convention
authorAndrew Gerrand <adg@golang.org>
Thu, 16 Feb 2012 00:50:28 +0000 (11:50 +1100)
committerAndrew Gerrand <adg@golang.org>
Thu, 16 Feb 2012 00:50:28 +0000 (11:50 +1100)
commit11e113db573369e1fd5f92844269d31ae3815c25
treec043d6cc2b47330b42d8bc5384af16fe2c0e1407
parentfa0100cf26336053f9c072c3cb1081a09df41449
godoc: make example code more readable with new comment convention
go/doc: move Examples to go/ast
cmd/go: use go/doc to read examples
src/pkg: update examples to use new convention

This is to make whole file examples more readable. When presented as a
complete function, preceding an Example with its output is confusing.
The new convention is to put the expected output in the final comment
of the example, preceded by the string "output:" (case insensitive).

An idiomatic example looks like this:

// This example demonstrates Foo by doing bar and quux.
func ExampleFoo() {
        // example body that does bar and quux

        // Output:
        // example output
}

R=rsc, gri
CC=golang-dev
https://golang.org/cl/5673053
14 files changed:
src/cmd/go/test.go
src/cmd/godoc/godoc.go
src/pkg/bytes/example_test.go
src/pkg/container/heap/example_test.go
src/pkg/encoding/binary/example_test.go
src/pkg/encoding/json/example_test.go
src/pkg/go/ast/example.go [moved from src/pkg/go/doc/example.go with 56% similarity]
src/pkg/math/big/example_test.go
src/pkg/path/example_test.go
src/pkg/sort/example_test.go
src/pkg/strings/example_test.go
src/pkg/testing/testing.go
src/pkg/text/template/example_test.go
src/pkg/time/example_test.go