When you think about programming, it's natural to focus on topics like languages, algorithms, and debugging. But technical documentation can be just as important to get right.

Without good documentation, code reusability can suffer. Users new to a codebase can easily get lost or frustrated if documentation is not up to scratch. It's not only important to understand what a program does, but how—or even why—it does it.

Packages like Pydoc for Python and Javadoc for Java help by automating part of the process. The Godoc tool does just the same for Go.

What Is Godoc?

Godoc is a Go package that lets you create, manage, and use Go documentation in “the Go way”. The Go way is a set of principles that, as a Go programmer, you should follow to improve code quality.

Using Godoc, you can easily read other developers’ documentation and code. You can also automate the creation of your own documentation and publish it using Godoc.

Godoc is similar to Javadoc, the code documentor for Java. They both use comments and code in modules to generate documentation. And both tools structure that documentation in HTML so you can view it in a browser.

Getting Started With Godoc

Using Godoc is easy. To begin, install the Godoc package from the golang website using this command: 

        go get golang.org/x/tools/cmd/godoc

Running this command will install Godoc in your specified workspace. Once it completes, you should be able to run the godoc command in a terminal. If there are any errors with your installation, try updating Go to a recent version.

How to Comment Your Code

Godoc looks for single and multiple line comments to include in the documentation it generates.

Make sure to format code the Go way, as explained in the Effective Go publication by the Go team for the best results.

Here’s an example using C++-style single-line comments: 

        // User is a struct model containing
type User struct {
 
}

You can also use C-style block comments: 

        /* 
User is a custom data structure
 
You can include any text here and the Godoc server will format it when you run it.
*/
type User struct {
 
}

In the comments above, “User” begins the sentences because the comment describes what the User struct does. This is one of the many topics that the Go way discusses. Starting documentation sentences with a useful name is crucial since the first sentence appears in the package list.

Running a Godoc Server

Once you have commented your code, you can run the godoc command in your terminal, from your project’s code directory.

Conventionally, Go developers use port 6060 to host documentation. This is the command for running a Godoc server on that port: 

        godoc -http=:6060

The command above hosts your code documentation on localhost, or 127.0.0.1. The port doesn’t have to 6060; godoc will run on any unoccupied port. However, it’s always best to follow the Go documentation conventions.

Once you have run the command, you can view your documentation in a browser by visiting localhost:6060. The time that Godoc takes to generate your documentation will depend on its size and complexity.

An Example Program With Godoc Comments

The code below adheres to the Go way, in this case using single-line comments. 

        // name of the package
package user
 
// fmt is responsible for formatting
import (
    "fmt"
)
 
// User is a struct of human data
type User struct {
    Age  int
    Name string
}
 
func main() {
    // human is an initialization of the User struct
    human := User {
        Age:  0,
        Name: "person",
    }
 
    fmt.Println(human.Talk())
}
 
// Talk is a method of the User struct
func (receiver User) Talk() string {
    return "Every User Gets to Say Something!"
}

If you run Godoc on the code module above, you should see output looking something like this:

Godoc documentation example

Notice that it’s in a familiar format, similar to what you’ll find on the Go official documentation website.

Godoc uses the comment preceding the package declaration as the Overview. Make sure this comment describes what your program does.

The Index contains links to the type declarations and methods so you can navigate to them quickly.

Godoc also provides functionality for viewing the source code that makes up the package in the Package files section.

Improving Your Documentation Using Godoc

You can include more than just plain text in your Godoc documentation. You can add URLs that Godoc will generate links for and structure your comments into paragraphs.

If you want to link to a resource, write the URL in your comment, and Godoc will recognize it and add a link. For paragraphs, leave an empty comment line. 

        // Package main
package main
 
// Document represents a regular document.
//
// Link to https://google.com
type Document struct {
    pages      int
    references string
    signed     bool
}
 
// Write writes a new Document to the storage
//
// You can learn about writing from Wikipedia.com
func Write() {
 
}
Godoc documentation code example

Note that Godoc requires you to write out URLs in full for it to link them. In this example, the Google URL includes the https:// prefix, so Godoc adds a link to it. Since the Wikipedia domain is not a full URL on its own, Godoc will leave it alone.

Here are some best principles to apply when documenting your Go code:

  • Keep your documentation simple and concise.
  • Start the sentence of functions, types, and variable declarations by their names.
  • Start a line with an indent to pre-format it as code.
  • Comments that begin "BUG(name)" like "BUG(joe): This doesn't work" are special. Godoc will recognize them as bugs and report them in their own section of the documentation.

Godoc Can Ease Your Documentation Woes

Using Godoc, you can be more productive and worry less about the effort of documenting your programs by hand.

You should keep your documentation precise, detailed, and to the point to make it easier for your target audience to read and understand. It’s also vital that you keep code comments up-to-date as you modify your program.

Check out the Godoc package documentation to learn more about using Godoc.