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
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 とします）を作成してみます。
// 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 にて作成したパッケージのドキュメントが作られていることを確認しました
参考
Discussion