概要

go docコマンドに新しいコマンドラインオプション-exが追加され、指定したパッケージまたはシンボルに紐づく実行可能なexample(ExampleXxx関数)の一覧を表示できるようになった。また、go doc bytes.ExampleBufferのようにexample関数名そのものをコマンドライン引数として渡した場合は、-exの有無にかかわらず、そのexampleのソースコードと付随するコメントが表示されるようになった。

導入経緯

このIssueは、godocにはすでに存在していた-exフラグ(exampleを表示する機能)をgo docコマンドにも導入してほしい、という要望から始まった。

議論のハイライト

• 議論の中心は「-exを指定しない通常のgo doc実行時に、exampleが存在すること自体をどう(あるいは表示するか否かを)伝えるか」だった。各シンボルの一覧に// example availableのような注釈を都度付ける案や、exampleの存在を示す文言を末尾に追加する案などが検討されたが、いずれも出力が冗長になったり煩雑になったりする欠点が指摘された。
• 最終的にrsc(proposal review group)から、(1) -exはパッケージ・シンボルの一覧表示にexampleの1行サマリ(func ExampleXxx())を追加するだけの機能とし、(2) go doc bytes.ExampleBufferのようにexample関数名を直接指定した場合は-exの有無に関係なく常にそのソースとコメントを表示する、という案が提示され、これが合意された。
• この方針により、go docは-exなしでは従来どおりの出力を維持しつつ、exampleを探したいユーザーは-exで一覧からexample名を見つけ、go doc pkg.ExampleNameで内容を確認する、という二段階の使い方ができるようになった。
• 議論はproposalとして仕切り直され、likely acceptを経てaccepted(提案採用)となった。

実装解説

実装はcmd/go/internal/docパッケージに追加されている。

• -exフラグ自体はdoc.goでshowExという真偽値のパッケージ変数として定義され、ヘルプテキストにも追記されている。
• パッケージ・シンボルの一覧表示部分では、funcSummaryなどが関数やタイプの1行サマリを出力した直後にexampleSummaryを呼び出す。exampleSummaryはshowExがfalseの場合は即座に戻るだけで何も出力しない。つまり-exはあくまで一覧表示にfunc ExampleXxx()という行を追加するかどうかだけを切り替えるフラグである。
• 一方、コマンドラインでシンボル名としてExampleから始まる名前が渡された場合は、symbolDocがfindExamplesでパッケージ内の全example(パッケージ・型・関数・メソッドに紐づくもの全て)から名前が一致するものを探し出し、emitExampleがgo/format.Nodeでソースを整形して出力する。この経路はshowExの値を参照しておらず、-exを指定しなくても動作する。
• この2つの経路が分離していることが、議論で合意された「一覧表示への影響は-exで制御するが、名前を直接指定した場合は常に表示する」という設計をそのまま反映している。