When you're working on a small project by yourself, you can keep the entire API in your head. But the second you share your code with a teammate or open-source it, you're going to get a barrage of questions. That's where godoc comes in. In Go, documentation isn't a separate chore you do in a Word doc or a Wiki; it's baked directly into your source code.

How do I write comments that actually show up in the docs?

It's simpler than you'd think, but there is one strict rule: the comment must be placed immediately preceding the declaration, with no empty lines in between. If you put a blank line between your comment and your function, Go treats it as just a regular comment and ignores it for documentation purposes.

Also, the convention is to start the comment with the name of the thing you're documenting. It feels repetitive at first, but it makes the generated documentation read like a professional manual.

package inventory

// Item represents a product in the warehouse.
type Item struct {
	SKU      string
	Quantity int
}

// AddStock increases the quantity of the item by the given amount.
// It returns an error if the amount is negative.
func (i *Item) AddStock(amount int) error {
	if amount < 0 {
		return fmt.Errorf("cannot add negative stock")
	}
	i.Quantity += amount
	return nil
}

I've seen a lot of devs try to write "This function adds stock..."—don't do that. Start with "AddStock increases...". It's the Go way.

Where do I actually view these documents while I'm coding?

You have two main options. If you want a quick answer without leaving your terminal, use the go doc command. For example, go doc inventory.Item will dump the documentation for that struct right into your shell. It's fast, efficient, and exactly what I use 90% of the time.

But if you want the full "web browser" experience—the one that looks like the official Go packages site—you'll want to use pkgsite (which is the modern successor to the original godoc tool). You can install it and run it locally to see your own project rendered as a website. It's a great way to check if your formatting looks right before you push your code to a repository.

What's the deal with "Example" functions?

The best documentation isn't a description; it's a runnable example. Go has a brilliant feature where you can write "Example" functions in your _test.go files, and godoc will automatically pull them into the documentation page for that function.

The trick is the naming convention: the function must start with Example, followed by the name of the function it's demonstrating. Then, you add a special comment at the end starting with // Output:. This turns the example into a test that the Go toolchain actually verifies.

// In inventory_test.go
package inventory

import "fmt"

func ExampleItem_AddStock() {
	item := Item{SKU: "GOPHER-PLUSH", Quantity: 10}
	item.AddStock(5)
	fmt.Println(item.Quantity)
	// Output: 15
}

When you view your docs, this code block appears right under the AddStock method. It's a win-win: you're providing a tutorial for your users, and you're writing a regression test for your code at the same time.

📋 Practical Task

Documenting the Warehouse Shipping Package

You've been handed a "Shipping" package that is functionally complete but totally undocumented. Your task is to make it professional and "Go-idiomatic".

• Create a package named shipping.
• Implement a Shipment struct with fields for TrackingID and Weight.
• Implement a method CalculateCost(rate float64) float64 that returns the weight multiplied by the rate.
• Add proper doc comments to the struct and the method (remember the naming convention!).
• Create a shipping_test.go file and implement an ExampleShipment_CalculateCost function that demonstrates a shipment weighing 10kg at a rate of 2.5, printing the result. Include the // Output: comment so it's valid.

To verify your work, run go doc -all in your terminal to ensure your comments are being picked up correctly.