Skip to content

Commit

Permalink
Update integers.md (#832)
Browse files Browse the repository at this point in the history
Adds explanation to why an Example without an Output comment is useful for docs.
  • Loading branch information
kalyncoose authored Jan 1, 2025
1 parent 314fbad commit 2a97c2b
Showing 1 changed file with 2 additions and 0 deletions.
2 changes: 2 additions & 0 deletions integers.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,8 @@ $ go test -v

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.

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.

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)`.

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.
Expand Down

0 comments on commit 2a97c2b

Please sign in to comment.