Go（ver1.21）で godoc を使う手順

やりたいこと

Mac に Go 1.21 をインストールしたのち godoc コマンドが使えるようにして、Godoc でドキュメントの自動生成をしたい

そもそも Godoc とは

Godoc は自作の Go パッケージに関するドキュメントを自動生成してくれるツールです。
（※ もちろん標準ライブラリやサードパーティ製のパッケージに関しても同時にドキュメントが作られ閲覧可能）

Godoc を使えば、開発者が決められたルールに沿ってソースコードにコメントで書いておくだけで、パッケージや関数、型、変数に関する説明や、
APIであればその返却値の例や必要なパラメータなどの実装例のドキュメントを自動で生成してくれます。
それをローカルで閲覧＆手元に保存することも可能ですし、
さらにそのドキュメントは全てウェブページとして公開することができます、これも自動です。
下の手順に沿って自作のパッケージの Godoc ドキュメントを作成した後に pkg.go.dev（Go の全パッケージのドキュメント検索サイト） で検索をかけると、そこに自分のパッケージがあることを確認できるかと思います。

手順

1. Go インストール

Go の公式サイト からインストールするか、brew を使用してインストールします。

$ brew install go
# 確認
$ go version
go version go1.21.2

2. Godoc のインストール

$ go install golang.org/x/tools/cmd/godoc@latest

godoc コマンドを実行して以下のようなエラーが出た場合は、適宜パスを通してください。

$ godoc
zsh: command not found: godoc

godoc の実行バイナリはインストールはされてるものの、そのファイルがインストールされている bin フォルダまでのパスが見つかっていない状態です

# まず vim などで .zshrc ファイルを開く
$ vim ./~zshrc

# .zshrc 内に以下を記入
export GOPATH=$(go env GOPATH)
export PATH=$PATH:$GOPATH/bin

# 保存
$ source ~/.zshrc

# 確認
$ cat ~/.zshrc

3. Godoc を試してみる

Go 1.13 からデフォルトでモジュールモードが有効になりました。
go env を実行すると GO111MODULE の箇所は GO111MODULE='' となっているかと思います。

モジュールモードで godoc コマンドを実行すると、godoc はコマンドが実行されたカレントディレクトリの go.mod ファイルをまず探します。
ファイルが存在していればそこに記載のあるサードパッケージと $GOROOT/src 配下にある標準パッケージに関するドキュメントが生成されます。
go.mod ファイルが存在しない場合は標準パッケージだけに関するドキュメントが生成されます。

明示的に GO111MODULE=off を設定することで、モジュールモードを完全に無効にでき、どのディレクトリからでも旧来の GOPATH モードで godoc を実行できるようになります。
このとき godoc は $GOPATH/src 配下にある全てのパッケージと $GOROOT/src 配下にある標準パッケージのドキュメントを生成するようになります。

特段理由がない限り、デフォルトとなったモジュールモードを使いましょう。

ここでは go 1.21 でモジュールモードで godoc を実行することを想定しています。

上述の説明より、ドキュメントを作成したいパッケージを他の Go プロジェクトの go.mod に記載することでそのパッケージのドキュメントが作成されます。
ドキュメントを作成したいパッケージ上でコマンドを実行しても、結局そのパッケージの go.mod に自分自身を記載していなれけば godoc によるドキュメントは作成されません。

早速ドキュメントを作成したいパッケージ（github.com/mkosakana/check_godoc とします）を作成してみます。

github.com/mkosakana/check_godoc/test.go

// Package check_godoc
package check_godoc

// Test
type Test struct{}

// test
type test struct{}

// TestVar
var TestVar int

// testVar
var testVar int

// TestFn
func TestFn() error {
	return nil
}

// testFn
func testFn() error {
	return nil
}

これを全く他の Go プロジェクトの go.mod に記載して、

module XXXXX

go 1.21

require (
	github.com/mkosakana/check-godoc v1.1.0
)

godoc コマンドを実行します

$ godoc 
or
$ godoc -http=:XXXX # ポートの指定などオプションをつけられる（ポートは何も指定しなければ6060）

using module mode; GOMOD=/Users/user_name/XXXXX/go.mod # これが出れば概ねOK

localhost:6060 にて作成したパッケージのドキュメントが作られていることを確認しました

参考

https://qiita.com/shibukawa/items/8c70fdd1972fad76a5ce#新pkggodevの場合