@@ -36,43 +36,44 @@ As with typical tests, examples are functions that reside in a package's
36
36
Unlike normal test functions, though, example functions take no arguments
37
37
and begin with the word ` Example ` instead of ` Test ` .
38
38
39
- The [ ` stringutil ` package] ( https://pkg.go.dev/golang.org/x/example/stringutil / )
39
+ The [ ` reverse ` package] ( https://pkg.go.dev/golang.org/x/example/hello/reverse / )
40
40
is part of the [ Go example repository] ( https://cs.opensource.google/go/x/example ) .
41
- Here's an example that demonstrates its ` Reverse ` function:
41
+ Here's an example that demonstrates its ` String ` function:
42
42
43
- package stringutil_test
43
+ package reverse_test
44
44
45
45
import (
46
46
"fmt"
47
47
48
- "golang.org/x/example/stringutil "
48
+ "golang.org/x/example/hello/reverse "
49
49
)
50
50
51
- func ExampleReverse () {
52
- fmt.Println(stringutil.Reverse ("hello"))
51
+ func ExampleString () {
52
+ fmt.Println(reverse.String ("hello"))
53
53
// Output: olleh
54
54
}
55
55
56
- This code might live in ` example_test.go ` in the ` stringutil ` directory.
56
+ This code might live in ` example_test.go ` in the ` reverse ` directory.
57
57
58
- Godoc will present this example alongside the ` Reverse ` function's documentation:
58
+ The Go package documentation server _ pkg.go.dev_ presents this
59
+ example alongside the [ ` String ` function's documentation] ( https://pkg.go.dev/golang.org/x/example/hello/reverse/#String ) :
59
60
60
- {{image "examples/reverse .png"}}
61
+ {{image "examples/pkgdoc .png" 517 }}
61
62
62
63
Running the package's test suite, we can see the example function is executed
63
64
with no further arrangement from us:
64
65
65
66
$ go test -v
66
- === RUN TestReverse
67
- --- PASS: TestReverse (0.00s)
68
- === RUN: ExampleReverse
69
- --- PASS: ExampleReverse (0.00s)
67
+ === RUN TestString
68
+ --- PASS: TestString (0.00s)
69
+ === RUN ExampleString
70
+ --- PASS: ExampleString (0.00s)
70
71
PASS
71
- ok golang.org/x/example/stringutil 0.009s
72
+ ok golang.org/x/example/hello/reverse 0.209s
72
73
73
74
## Output comments
74
75
75
- What does it mean that the ` ExampleReverse ` function "passes"?
76
+ What does it mean that the ` ExampleString ` function "passes"?
76
77
77
78
As it executes the example,
78
79
the testing framework captures data written to standard output
@@ -82,15 +83,15 @@ The test passes if the test's output matches its output comment.
82
83
To see a failing example we can change the output comment text to something
83
84
obviously incorrect
84
85
85
- func ExampleReverse () {
86
- fmt.Println(stringutil.Reverse ("hello"))
86
+ func ExampleString () {
87
+ fmt.Println(reverse.String ("hello"))
87
88
// Output: golly
88
89
}
89
90
90
91
and run the tests again:
91
92
92
93
$ go test
93
- --- FAIL: ExampleReverse (0.00s)
94
+ --- FAIL: ExampleString (0.00s)
94
95
got:
95
96
olleh
96
97
want:
@@ -99,17 +100,17 @@ and run the tests again:
99
100
100
101
If we remove the output comment entirely
101
102
102
- func ExampleReverse () {
103
- fmt.Println(stringutil.Reverse ("hello"))
103
+ func ExampleString () {
104
+ fmt.Println(reverse.String ("hello"))
104
105
}
105
106
106
107
then the example function is compiled but not executed:
107
108
108
109
$ go test -v
109
- === RUN TestReverse
110
- --- PASS: TestReverse (0.00s)
110
+ === RUN TestString
111
+ --- PASS: TestString (0.00s)
111
112
PASS
112
- ok golang.org/x/example/stringutil 0.009s
113
+ ok golang.org/x/example/hello/reverse 0.110s
113
114
114
115
Examples without output comments are useful for demonstrating code that cannot
115
116
run as unit tests, such as that which accesses the network,
@@ -124,16 +125,16 @@ package-level identifier.
124
125
func ExampleBar_Qux() // documents the Qux method of type Bar
125
126
func Example() // documents the package as a whole
126
127
127
- Following this convention, godoc displays the ` ExampleReverse ` example
128
- alongside the documentation for the ` Reverse ` function.
128
+ Following this convention, godoc displays the ` ExampleString ` example
129
+ alongside the documentation for the ` String ` function.
129
130
130
131
Multiple examples can be provided for a given identifier by using a suffix
131
132
beginning with an underscore followed by a lowercase letter.
132
- Each of these examples documents the ` Reverse ` function:
133
+ Each of these examples documents the ` String ` function:
133
134
134
- func ExampleReverse ()
135
- func ExampleReverse_second ()
136
- func ExampleReverse_third ()
135
+ func ExampleString ()
136
+ func ExampleString_second ()
137
+ func ExampleString_third ()
137
138
138
139
## Larger examples
139
140
0 commit comments