Writing Effective GoDoc: Using godoc, pkgsite and GoDoc Syntax with Examples

Go follows the "comments as documentation" principle, where public symbols are documented directly in the source code. The generated documentation is called GoDoc and is displayed on pkg.go.dev. This article explains how to write GoDoc correctly, using the go.jsonvalue library as a concrete example.

What is GoDoc? It can refer to the content previously hosted at https://godoc.org, the current pkg.go.dev site, the godoc command, the pkgsite tool, or the documentation format itself. Both godoc and pkgsite render the same GoDoc format.

Installing and using the godoc command

Since Go 1.12 the godoc tool is no longer bundled; install it with: go get -v golang.org/x/tools/cmd/godoc Run a local server for a module (replace XXXX with the directory containing go.mod): cd XXXX; godoc -http=:6060 Open

http://localhost:6060/pkg/github.com/Andrew-M-C/go.jsonvalue/

to view the generated GoDoc for the jsonvalue package.

Installing and using the pkgsite command pkgsite requires Go 1.18 or newer. Install it with: go install golang.org/x/pkgsite/cmd/pkgsite@latest Run it similarly: cd XXXX; pkgsite -http=:6060 The URL is the same as for godoc but without the pkg/ prefix.

GoDoc syntax overview

All exported types, functions, variables, and constants are displayed on the package page, even if they lack comments. Every exported item should have a comment.

Comments can use // or /* ... */, but the single‑line form is preferred. The first word of a comment should be the name of the item it documents (e.g., // SomeTypeA does ...).

Binding a comment to a type

// This line will be treated as SomeTypeA's GoDoc because it is directly above the definition.
// It describes SomeTypeA.
type SomeTypeA struct{}

// This line is separated by a blank line, so it is NOT SomeTypeB's GoDoc.

type SomeTypeB struct{}

/*
Multi‑line comment that is also attached to SomeTypeC.
*/
type SomeTypeC struct{}

When rendered, only the first comment block is associated with the type.

Paragraph breaks

A blank comment line ( //) creates a new paragraph in the rendered documentation.

// First line of the comment.
//
// Second paragraph starts here.
func SomeNewLine() error {
    return nil
}

Embedding code snippets in comments

// IntsElem reads an element from an int slice without panicking.
// It returns the value and the actual index in the slice.
// The index parameter can be:
//   0 – return the first element.
//   >0 – count from the start, wrapping around at the end.
//   <0 – count backwards, wrapping around at the beginning.
func IntsElem(ints []int, index int) (value, actualIndex int) {
    // ... implementation ...
}

Package overview comment

The package comment should appear before the package clause, typically starting with // Package jsonvalue .... Only one file in the package should contain this comment to avoid duplication.

Deprecation

Mark deprecated items with a comment that begins with Deprecated::

// Deprecated: ElemAt is deprecated; use IntsElem instead.
func ElemAt(ints []int, index int) int {
    // ...
}

Pkgsite highlights deprecated symbols in the directory listing and hides their full documentation until expanded.

Example code for documentation

Example functions must be placed in a separate *_test.go file with a package name ending in _test. The function name follows the pattern Example<Package>_<Func>_X where X orders multiple examples.

func ExampleSet_At_1() {
    // ... example code ...
    // Output:
    // expected output line 1
    // expected output line 2
}

Each example should end with an // Output: comment that contains the expected standard output.

Publishing GoDoc

After pushing the code to a repository (e.g., GitHub), the documentation becomes available at https://pkg.go.dev/github.com/Andrew-M-C/go.jsonvalue. The first visit triggers a fetch and rendering of the latest tags.

To add a badge to the README, use the badge generator at https://pkg.go.dev/badge/ and copy the provided HTML or Markdown snippet.

References

In‑depth article on the design and implementation of pkg.go.dev Source code of

pkg.go.dev