Package comments and godoc

Good documentation is an integral part of high-quality Go code. The Go toolchain encourages keeping documentation close to source code so it stays accurate and easy to update. This page summarizes conventions, commands, and examples for writing Go package and identifier documentation that integrates well with godoc and go doc. Primary documentation tools

godoc — historically provided an HTML view of package documentation and could run a local documentation server.
go doc — the modern, included command-line tool that prints package and identifier documentation in the terminal.

You can run these commands locally:

godoc
go doc PACKAGE_NAME
go doc PACKAGE_NAME.IDENTIFIER_NAME

A dark presentation slide about "godoc" showing two bullet points: that Godoc parses Go source code (including comments) and produces documentation as HTML or plain text. It also states the result is documentation tightly coupled with the code it documents.

Why Go documentation matters

Documentation lives next to code, so it is more likely to be updated when implementation changes.
Well-structured comments improve discoverability of package features via go doc and generated HTML pages.
Following canonical conventions produces clearer, more consistent output in generated docs.

Quick reference: tools and their common uses

Tool	Primary use	Typical command
`go doc`	Inspect package and identifier docs in the terminal	`go doc fmt`
`godoc`	Serve HTML documentation locally (legacy but still used)	`godoc -http=:6060`

Convention and best practices

Place a comment directly before the declaration of a package, type, variable, constant, or function. Do not insert a blank line between the comment and the declaration.
Use a blank comment line to separate paragraphs inside long comments.
Package-level documentation is commonly placed in a file named doc.go inside the package.
Comments for exported identifiers (those that start with an uppercase letter) should begin with the identifier name. For example, a comment for Nimbus should start with “Nimbus …”. This canonical convention yields nicer generated documentation.

Example: a well-documented package and function

// Package decrypt provides simple decryption algorithms.
//
// The Nimbus implementation demonstrates a basic rune-shifting decryption.
package decrypt

import "strings"

// Nimbus shifts each rune's Unicode code point back by 3 and returns the result.
func Nimbus(s string) string {
	var b strings.Builder
	b.Grow(len(s))
	for _, r := range s {
		b.WriteRune(r - 3)
	}
	return b.String()
}

How go doc presents information

go doc decrypt prints package-level documentation and a list of exported identifiers in the package.
go doc decrypt Nimbus prints the documentation for the Nimbus identifier (its comment and signature).

Example usage and expected output (conceptual)

# Show package documentation and exported identifiers
go doc decrypt

Output (example):

package decrypt

Package decrypt provides simple decryption algorithms.

FUNCTIONS:
    func Nimbus(s string) string

# Show documentation for a single identifier
go doc decrypt Nimbus

Output (example):

func Nimbus(s string) string
    Nimbus shifts each rune's Unicode code point back by 3 and returns the result.

Exported identifiers should have comments that start with the identifier name (for example, “Nimbus …”). This convention improves clarity and produces better generated documentation.

Do not insert a blank line between a declaration and its preceding comment. A blank line detaches the comment from the declaration and prevents tools like go doc from associating the comment with the symbol.

A few final tips

At minimum, document all exported identifiers — this significantly helps users of your package.
Keep comments concise and accurate; update them as the code evolves.
Use go doc for quick local inspection; use godoc or static site generators when you need an HTML view or a local documentation server.
Consider adding a doc.go with package overview, examples, and package-level details to improve discoverability.

Links and references

That’s it for this lesson.

Introduction

Introduction: Modules, Packages, and Imports

Core packages

API Development Project

CI/CD pipeline

Concurrency

Package comments and godoc

Watch Video