Goのパッケージドキュメントが便利

pkg.go.devへの移行

これまでGoでは標準パッケージのドキュメントはgolang.org/pkgから閲覧できました。また、サードパーティ製のパッケージは、godoc.orgで閲覧できました。Goはソースコードにすべての依存関係をインポートパスとして記述します。そのため、インポートパスさえあれば簡単にパッケージドキュメントが生成でき、https://godoc.org/github.com/tenntenn/greetingのようなURLをブラウザで開くだけで閲覧が可能でした。

godoc.orgの存在によってREADMEにパッケージドキュメントへのリンクを貼るだけで済むようになりました。簡単にドキュメントが生成できるため、ソースコードにドキュメントコメント書く文化の浸透にも寄与したのかなと思います。

Go Modulesが登場し、パッケージを束ね、バージョン管理をする単位としてモジュールという概念が生まれました。モジュールごとにバージョン管理ができるため、ビルドの再現性がとれるようになりました。パッケージドキュメントにおいてもpkg.go.devが登場し、バージョンごとにサードパーティ製のドキュメントを閲覧できるようになりました。

一方、標準パッケージはgolang.org上で最新のGoのドキュメントが読めるという状況でした。古いバージョンのドキュメントが読みたい場合はgodocコマンドを用いて手元でドキュメントを読むしかありませんでした。

しかし、先日、golang.org/pkgがpkg.go.dev/stdがリダイレクトされるようになりました。その結果、パッチバージョンごとにドキュメントを確認でき、さらにパッケージドキュメントの利便性が向上しました。

pkg.go.devの便利な機能

pkg.go.devには、godoc.orgにはなかった便利な機能があります。例えば、fキーを押すと次のような検索画面が表示されます。型や関数などをサクッと検索できます。

ImportsタブやImported byタブも便利です。インポートしているパッケージやインポートされているパッケージの一覧を表示されます。実際に使ってる例を見つけることができます。

型名や関数名をクリックするとGoogle Open Sourceが開きます。ソースコードが読みやすくとても便利です。

pkg.go.devには検索バーがあり、パッケージの検索もできます。パッケージが思い出せなくてもなんとなくのワードで絞り込めます。また、依存しているパッケージを覚えている場合はそのパッケージのImported byタブから見つけるのもアリです。

リポジトリのREADMEにpkg.go.devへのリンクを貼る場合はバッジを作成するツールを利用すると良いでしょう。パッケージドキュメントへのURLを入力するだけで簡単に生成できます。

この他にもパッケージを選ぶためのさまざまな情報が掲載されています。ライセンスの有無や安定したバージョンかどうか、Go Modulesに対応しているかなども確認できます。

まとめ

本記事では、Goにおけるパッケージドキュメントがpkg.go.devに移行したことをお伝えしました。pkg.go.devはgolang.org/pkgやgodoc.orgにはないさまざまな機能が増えていますので、ぜひ試してみてください。

また、何か問題などを見つけた場合には、フィードバックをすると更に改善するでしょう！