Go has been gaining a lot of popularity recently. With a lot of the success stories centered on the performance gains switching from other languages. For me a lot of the smaller features, that shows an attention to detail, which makes it enjoyable to code in. These details are also what will help the Golang community grow as well. One of these details is the built in documentation into the language.
There is a built in
go doc command with the language where you can view your
package documentation locally by running an http server to serve your docs.
GoDoc is the main hosting for open source packages that will
build docs for your package by doing a
go get and generating docs. Locally
you can run
go doc from your package to display the docs in your terminal.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
Or you can view all the packages in your
$GOSRC directory as well as the standard
library code in your browser by running
godoc -http=:6060. Then visit
localhost:6060 in your browser. This looks the same as golang.org you may notice.
Packages and find the package you are looking for. This all comes built
into the language itself.
If you have spent any time using go, browsed the standard library docs, used
an open source go project you may have notice a
Examples in docs. These examples
are one of the details I mentioned that add to the language and help grow a
community. Here is an example of the
time package examples. The novel thing about this is it is just the
built in examples from the Go source that get generated by
go doc from the
language itself. There is no extra documentation package or custom manages site.
So you have an open source project, or some internal go project, that you want
to make life easier for others to pick up and understand. Lets write an example
for them to understand how to use your package. Lets say you have a fibonacci
number generator package. And you want to show someone how to use it with an
example. Lets add a
$GOPATH/src/fib directory with a
fib.go main package
with the following:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
Since we’ll be expecting others to use our package we’ll want to test it works
as well as document how to use it. With examples we can do both in one shot.
In our same
$GOPATH/src/fib directory create a
fib_test.go file. Lets add
our example test.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Now from your
fib/ directory run
go test and you should see some similar output:
1 2 3
This allowed us to both test our fibonacci package and show someone else an example how to use it. If the output changed or we broke our package our tests should fail as well.
1 2 3 4 5 6 7 8 9 10 11
Simple enough. What if you have a struct where you are calling a function off of
and want to show how one would use the function. The principal is the same except
we change our
Example() function name in our test. If we change our
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
Then we can add an example on how to use our new
Calculate() method in
1 2 3 4 5 6 7 8 9 10 11