pkg.go.devのドキュメントのVariablesに載せる大域変数は初期化していないといけない？

概要

パッケージの変数を公開しているのに、pkg.go.dev の Variables セクションに説明がないのに気づいた。
変数は実際公開されているし、コメントも書いてある。なぜだろう・・・となったので、調べた感じをメモ。
詳細は分からないが、何かで初期化してないと Variables には掲載されないっぽい。

Variables セクションに記載がない

国民の祝日の一覧を管理する ikawaha/holiday というパッケージを作っていて、パッケージの大域変数を用意しておいて、init()で初期化。これをパッケージ外からも利用できるようにしていました。

var (
	// Catalog is the list of national holidays.
	Catalog Holidays

	//go:embed holidays.json
	holidaysJSON []byte
)

func init() {
	Catalog = func() Holidays {
		ret := map[string]string{}
		if err := json.Unmarshal(holidaysJSON, &ret); err != nil {
			panic(err)
		}
		return ret
	}()
}

この Catalog というのは国民の祝日全てを管理する map になっています。holidays.json というファイルが embed されていて、ここに全ての祝日データがあり、init() が呼ばれたタイミングでこのデータが Catalog にロードされます。

で、「これを利用してね」というのが分かるようにコメントも書いておきました。こうしておけば pkg.go.dev で作成されるドキュメントに記載されるはず・・・。ところが

🤔

記載がないですね。このままだと、この変数が公開されていることが伝わりません。

解決

変数を初期化すればいいようです。

var (
	// Catalog is the list of national holidays. In the init(), holidays.json
	// will be loaded for initialization.
	Catalog = Holidays{}

こうすると

ちゃんと記載されますね！でも、ここでは空の map でしか初期化できないので記載が微妙ではあります。

というか、パッケージの大域変数はエラーとかそう云うものだけにしておいて、init() で初期化が必要になるようなものは公開しない方がいいのでしょうか？もしかしたらそうなのかも知れません。コメントもらえるとうれしいです。

Happy hacking!