Godoc in GoCenter Tells A Go Module’s Story

 

UPDATE: As of May 1, 2021 – GoCenter central repository has been sunset and all features will be deprecated. For more information on the sunsetting of the centers read the deprecation blog post

 

 

Using an open-source Go module from the community of other developers can be like going on a blind date. That “getting to know you” phase that can be awkward and risky. The more you know in advance, the better off you’ll be, right?

When using software, having accurate and precise documentation is one of the most important aspects. Good software documentation tells the story of what a particular piece of code does and how to use it. Its primary function is to make software accessible and maintainable 

The Golang project takes documentation quite seriously and provides developers a way to document their software quickly and easily with Godoc.To help both authors and consumers of Go modules, we’ve included Godoc generation into JFrog GoCenter.

What is Godoc?

Godoc is a Golang project tool that has been available to developers for nearly a decade. It parses Golang source code including comments and produces documentation as HTML or plain text.  Godoc relies on some Go commenting conventions that are commonly followed by disciplined developers. For example:

• A type, variable, constant, function and package are documented by writing a regular comment directly preceding its declaration with no intervening blank line.
• Godoc will present that comment as text alongside the item it documents

The example below depicts a simple Date function. We can see that the description of the functions are formatted within the code:

When the source code is processed by the Godoc tool, it produces documentation for the function in a highly readable format:

GoDoc in GoCenter

JFrog GoCenter is a community GOPROXY for publicly available Go modules. Through this free repository of immutable module versions, Go developers can be certain of what’s in the Go modules they use in their apps.

But an equally important part of GoCenter is the information available through its rich UI about every Go module. When viewing a Go module entry, tabs of additional data include:

• The list of the module’s dependencies
• Which other Go modules it’s used by
• Vital usage metrics such as the number of forks, contributors, and pull requests
• Known security vulnerabilities as detected by JFrog Xray

Now we’ve added a new tab to GoCenter that displays the Godoc HTML output of each module version:

GoCenter produces this tab’s information by automatically running Godoc on every module version source files. The Godoc information is also available for pseudo-versions, since many Go modules use pseudo-versions as dependencies.

When a module has subdirectories, those are listed in a table at the end of the Godoc.

Clicking on the subdirectory name will display the Godoc for the package in that subdirectory:

Preparing Go Modules for Godoc

As you can see, Godoc in GoCenter provides consumers of Go modules with even more information that will help them use available packages.

Go module authors benefit as well, when other developers are encouraged to use modules that are richly documented. That means that Golang developers should cultivate the skills and discipline that will produce useful documentation through Godocs. 

By installing the Godoc tool and running the godoc-http:6060 webserver, you’ll be able to test and check the documentation of every package installed locally. By default, Godoc uses $GOROOT and‘$GOPATH (if set) to look at the packages it finds. The godoc command will automatically run in module mode if the package has a go.mod file.

For full information on using Godoc, see the Godoc documentation.

Godoc Tips

When using Godoc, it’s useful to remember the following things as they will make creating documentation in Go much simpler:

• Comments made on package declarations should typically provide general package documentation
  • These are usually 1 or 2 sentences in length
  • For larger, more detailed descriptions, the documentation should contain its own doc.go file
• Comments that are not adjacent to a top-level declaration are omitted from documentation
• Using the word BUG(who) at the beginning of Top-level comments will have the comment recognized and categorized as a known bug and will be included in the Bugs section of the package documentation

Godoc also provides executable documentation in the form of examples. Here are characteristic of Example functions :

• They take the no argument
• They reside in the package’s _test.go file and start with word Example
• They may include a concluding line comment that begins with Output: and is compared with the standard output of the function when the tests are run.
• They are compiled and executed as part of the package test suite.  
  • If there is no Output: defined the example will get compiled but not executed

The following are the naming conventions for example functions:

• func Example() — Example of Package as a whole
• func ExampleFunction() – Example of a Function of package
• func ExampleType() – Example of a Type of Package
• func ExampleType_Method()  – Example of a Method on a Type of Package

Here is an example of the Date function of package Time which lives in examples_test.go at the package level.

Making a Date

Godoc can help you to understand how to use a new piece of Golang code by providing readable summaries of functions and their usage. Since Godoc is such an established part of the Golang project, many Go module authors format their comments accordingly. 

If you’re a Go module author, structuring your comments for Godocs is a great way to help and encourage other developers to use what you’ve created.

Making Godoc information more easily available is the latest feature of JFrog GoCenter that helps you know as much as you can about a Go module before you use it. 

Before any pairup, you want to know your potential Go module partner’s story (documentation), their family (dependencies), their friends (used by), and any red flags (security vulnerabilities). Give GoCenter a look, and you’ll see how it can help you make the best match.