Skip to content

Commit 2a97c2b

Browse files
authored
Update integers.md (#832)
Adds explanation to why an Example without an Output comment is useful for docs.
1 parent 314fbad commit 2a97c2b

File tree

1 file changed

+2
-0
lines changed

1 file changed

+2
-0
lines changed

integers.md

+2
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,8 @@ $ go test -v
148148

149149
Notice the special format of the comment, `// Output: 6`. While the example will always be compiled, adding this comment means the example will also be executed. Go ahead and temporarily remove the comment `// Output: 6`, then run `go test`, and you will see `ExampleAdd` is no longer executed.
150150

151+
Examples without output comments are useful for demonstrating code that cannot run as unit tests, such as that which accesses the network, while guaranteeing the example at least compiles.
152+
151153
To view example documentation, let's take a quick look at `pkgsite`. Navigate to your project's directory, then run `pkgsite -open .`, which should open a web browser for you, pointing to `http://localhost:8080`. Inside here you'll see a list of all of Go's Standard Library packages, plus Third Party packages you have installed, under which you should see your example documentation for `github.com/quii/learn-go-with-tests`. Follow that link, and then look under `Integers`, then under `func Add`, then expand `Example` and you should see the example you added for `sum := Add(1, 5)`.
152154

153155
If you publish your code with examples to a public URL, you can share the documentation of your code at [pkg.go.dev](https://pkg.go.dev/). For example, [here](https://pkg.go.dev/github.com/quii/learn-go-with-tests/integers/v2) is the finalised API for this chapter. This web interface allows you to search for documentation of standard library packages and third-party packages.

0 commit comments

Comments
 (0)