Go Docs

1 minute read

I’ve been working on a simple package github.com/hoani/getset lately, and I wanted to make sure I had some nice documentation alongside the package.

Installing godoc

Install the latest godoc:

go install golang.org/x/tools/cmd/godoc@latest

You can run godoc with:

godoc -http :8080

If you navigate through the index, you should be able to find you package, mine was here:

See godoctricks for many other tips and tricks.

Comment above the package name to add overview documentation:

// A lightweight set implementation.
//
// Requires go 1.18 or higher.
package getset

Comment above public functions and types to add documentation for them. For example:

// Has checks if an item is included in the set.
func (s Set[T]) Has(item T) bool {

I place examples in a file called examples_test.go under a <packagename>_test package.

The following examples will show up in the overview:

func Example() { // the first example
  //...
}

func Example_extra() { // will be called `Example (extra)`
  //...
}

If you have a function called New, add an example to the New section as follows:

func ExampleNew() {
  //...
}

If you have a type called MyType, add an example for MyType as follows:

func ExampleMyType() {
  //...
}

If MyType has a method DoSomething, add an example for DoSomething as follows:

func ExampleMyType_DoSomething(){
  //...
}

git tag v0.1.0
git push origin v0.1.0
GOPROXY=proxy.golang.org go list -m <repo>@v0.1.0

If your repo is public, it should appear on https://pkg.go.dev/<repo>