GoでAPIドキュメントに例を追加するにはどうすればよいですか？

Question

Go標準ライブラリにはexecutable examplesがあります。そのような例を自分のAPIドキュメントに追加するにはどうすればよいですか？

Answer 1

$ go help testfuncの出力：

「行くテスト」コマンドは、テストを見つけることを期待、ベンチマーク、および例は、テスト対象のパッケージに対応する「* _test.go」ファイルに を機能します。

テスト機能（XXXが小文字で始まらない任意の英数字文字列 ある）TestXXX名前一つであり、署名を持っている必要があり、

func TestXXX(t *testing.T) { ... } 

ベンチマーク関数が名前付きものですBenchmarkXXXと署名を持っている必要があり、

func BenchmarkXXX(b *testing.B) { ... } 

関数の例はテスト関数に似ていますが、* testing.T を使用して成功または失敗を報告する代わりに、出力をos.Stdoutおよびos.Stderrに出力します。 その出力は関数の "Output："コメントと比較されます。 は関数本体の最後のコメントでなければなりません（下記の例を参照）。そのようなコメントがない例、または「Output：」の後にテキストがない例は ですが、実行されません。

GodocはExampleXXXの本文を表示し、関数、定数、または変数XXXの使用 を示しています。 受信機タイプTまたは* TのメソッドMの例は、ExampleT_Mという名前です。与えられた関数、定数、または変数に対して、 という複数の例がある可能性があります。末尾の_xxxによって区別されます。 ここで、xxxは大文字で始まらない接尾辞です。ここ

例の一例である：

func ExamplePrintln() { 
     Println("The output of\nthis example.") 
     // Output: The output of 
     // this example. 
} 

それは単一 例えば、機能、少なくとも一つの他の機能、種類、変数が含まれている場合、全体のテストファイルは一例として提示されています、または定数 宣言であり、テストまたはベンチマーク機能はありません。

詳細については、テストパッケージのドキュメントを参照してください。