Document Go code automatically using Godoc

0

When thinking about programming, it’s natural to focus on topics like languages, algorithms, and debugging. But technical documentation can be just as important to getting it right.

Without good documentation, code reuse can suffer. New users of a codebase can easily get confused or frustrated if the documentation isn’t up to par. It is not only important to understand what a program does, but also how, or even why, it does it.

USE VIDEO OF THE DAY

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

What is Godoc?

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

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

Godoc is similar to Javadoc, the code documenter 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.

First steps with Godoc

Using Godoc is easy. To get started, 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 done, 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.

Godoc looks for single or multi-line comments to include in the documentation it generates.

Be sure to format the code the Go way, as explained in Go Efficient publishing by the Go team for the best results.

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


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 structure does. This is one of the many topics addressed by the Go way. Starting documentation sentences with a useful name is crucial since the first sentence appears in the list of packages.

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.

Traditionally, Go developers use the port 6060 to host the documentation. Here is the command to run a Godoc server on this port:

godoc -http=:6060 

The above command hosts your code documentation on localhost, or 127.0.0.1. The port does not need to be 6060; godoc will work on any unoccupied port. However, it’s always best to follow the conventions of the Go documentation.


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

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


package user


import (
"fmt"
)


type User struct {
Age int
Name string
}

func main() {
human := User {
Age: 0,
Name: "person",
}

fmt.Println(human.Talk())
}


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 that looks like this:

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

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

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

Godoc also provides a feature to view the source code that composes the package in the Package files section.

Improve your documentation with Godoc

You can include more than plain text in your Godoc documentation. You can add URLs for which Godoc will generate links and structure your comments in 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


type Document struct {
pages int
references string
signed bool
}


func Write() {

}

Note that Godoc asks you to write the URLs in full so that it can 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 by itself, Godoc will leave it alone.

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

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

Godoc can alleviate your documentation problems

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

You need to keep your documentation accurate, detailed and relevant 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.

See the Godoc package documentation to learn more about using Godoc.

Share.

About Author

Comments are closed.