[インデックス 12211] ファイルの概要

このコミットは、src/cmd/go/test.go ファイルに対して行われた変更です。具体的には、go test コマンドのヘルプテキスト、特にGo言語の Example 関数に関する説明が修正されています。

コミット

• コミットハッシュ: 5c7799f108c2ea6686aea0f4d5086f11ced7fd00
• 作者: Robert Griesemer gri@golang.org
• コミット日時: 2012年2月24日（金）15:42:25 -0800
• コミットメッセージ:

  go: fix help text documenting example functions
  
  R=adg, r
  CC=golang-dev
  https://golang.org/cl/5695062
  

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/5c7799f108c2ea6686aea0f4d5086f11ced7fd00

元コミット内容

go: fix help text documenting example functions

このコミットは、go コマンドのヘルプテキストにおいて、Example 関数のドキュメントに関する記述を修正することを目的としています。

変更の背景

Go言語の testing パッケージには、コードの動作例を示すための Example 関数という機能があります。これらの関数は、go test コマンドによって実行され、その出力が期待される出力と一致するかどうかが検証されます。また、godoc ツールによって生成されるドキュメントにも表示され、コードの利用方法を視覚的に示す役割も果たします。

このコミットが行われる以前の go test のヘルプテキストでは、Example 関数の出力が「関数のドキュメントコメント」と比較されると記述されていました。しかし、実際のGoの testing パッケージの動作では、Example 関数の出力は、関数本体内の特定の形式のコメント（// Output: で始まるコメント）と比較されます。このヘルプテキストの記述と実際の動作との間に齟齬があったため、ユーザーが Example 関数を正しく理解し、利用する上で混乱を招く可能性がありました。

このコミットは、この誤解を招く記述を修正し、Example 関数の出力検証メカニズムを正確に反映させることを目的としています。これにより、開発者が Example 関数をより効果的に使用できるよう、ドキュメントの正確性を向上させています。

前提知識の解説

Go言語の testing パッケージ

Go言語には、ユニットテスト、ベンチマークテスト、そして例（Example）を記述するための標準パッケージ testing が用意されています。

• テスト関数 (TestXXX): func TestXXX(t *testing.T) の形式で定義され、コードの特定の機能が正しく動作するかを検証します。t *testing.T を通じてテストの失敗を報告したり、ログを出力したりできます。
• ベンチマーク関数 (BenchmarkXXX): func BenchmarkXXX(b *testing.B) の形式で定義され、コードのパフォーマンスを測定します。b *testing.B を通じてベンチマークの実行回数を制御したり、タイマーをリセットしたりできます。
• Example 関数 (ExampleXXX): func ExampleXXX() の形式で定義され、コードの利用例を示します。これらの関数は、go test コマンドによって実行され、その標準出力（os.Stdout）が、関数内の特定のコメント（// Output:）に続く期待される出力と比較されます。一致しない場合、テストは失敗します。また、godoc コマンドで生成されるドキュメントにも表示され、コードの使い方のスニペットとして機能します。

go test コマンド

go test コマンドは、Goパッケージ内のテスト、ベンチマーク、およびExample関数を実行するための主要なツールです。このコマンドは、指定されたパッケージ内の _test.go で終わるファイルを探し、その中のテスト関数、ベンチマーク関数、Example関数を実行します。

Example 関数の出力検証メカニズム

Example 関数の特徴的な点は、その出力が自動的に検証されることです。これは、関数本体の最後のコメントとして // Output: というプレフィックスを持つ行を記述し、その後に期待される出力を記述することで実現されます。go test は、Example 関数が標準出力に出力した内容と、この // Output: コメントに続く内容を比較します。

例えば、以下のような Example 関数があったとします。

package main

import "fmt"

func ExampleHello() {
	fmt.Println("Hello, world!")
	// Output: Hello, world!
}

go test は ExampleHello を実行し、fmt.Println("Hello, world!") の出力が Hello, world! であることを確認します。もし出力が異なれば、テストは失敗します。

また、複数行の出力もサポートされており、その場合は // Output: の後に続く行もすべて期待される出力として扱われます。

package main

import "fmt"

func ExampleMultiLine() {
	fmt.Println("First line")
	fmt.Println("Second line")
	// Output: First line
	// Second line
}

このメカニズムは、コードの動作例が常に最新かつ正確であることを保証するのに役立ちます。

技術的詳細

このコミットの技術的な詳細は、go test コマンドのヘルプテキストにおける Example 関数の説明の正確性を向上させることにあります。

以前のヘルプテキストでは、Example 関数の出力が「関数のドキュメントコメント」と比較されると誤って記述されていました。Goの慣習では、関数のドキュメントコメントは関数宣言の直前に記述されるものであり、通常は // または /* ... */ で記述されます。しかし、Example 関数の出力検証は、関数本体の内部に記述される // Output: コメントに依存しています。

このコミットは、この誤解を解消するために、以下の点を明確にしています。

1. 出力比較の対象: 出力は「関数のドキュメントコメント」ではなく、「関数の \"Output:\" コメント」と比較されることを明記。
2. Output: コメントの位置: この \"Output:\" コメントは「関数本体の最後のコメントでなければならない」という制約を追記。これは、go test が Output: コメントを解析する際のルールを正確に反映しています。
3. Output: コメントがない場合の挙動: Output: コメントがない場合、または Output: の後にテキストがない場合は、Example 関数がコンパイルされるものの「実行されない」ことを明確化。これは、出力検証の対象がないため、実行しても意味がないという設計思想に基づいています。
4. 複数行出力の例: 実際の Example 関数の例を更新し、複数行の出力とその // Output: コメントでの記述方法を示しています。これにより、ユーザーは複数行の出力を伴う Example 関数をどのように記述すればよいかを具体的に理解できます。

これらの変更により、go test のヘルプドキュメントは、Example 関数の動作と利用方法について、より正確で詳細な情報を提供するようになりました。これは、Go言語のドキュメンテーションの品質向上に貢献し、開発者が Example 関数をより効果的に活用するための助けとなります。

コアとなるコードの変更箇所

変更は src/cmd/go/test.go ファイルの helpTestfunc コマンドのヘルプテキスト部分に集中しています。

--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -167,8 +167,10 @@ A benchmark function is one named BenchmarkXXX and should have the signature,

 An example function is similar to a test function but, instead of using *testing.T
 to report success or failure, prints output to os.Stdout and os.Stderr.
-That output is compared against the function\'s doc comment.
-An example without a doc comment is compiled but not executed.
+That output is compared against the function\'s \"Output:\" comment, which
+must be the last comment in the function body (see example below). An
+example with no such comment, or with no text after \"Output:\" is compiled
+but not executed.

 Godoc displays the body of ExampleXXX to demonstrate the use
 of the function, constant, or variable XXX.  An example of a method M with
@@ -179,8 +181,9 @@ where xxx is a suffix not beginning with an upper case letter.\n Here is an example of an example:\n \n \tfunc ExamplePrintln() {\n-\t\tPrintln(\"The output of this example function.\")\n-\t\t// Output: The output of this example function.\n+\t\tPrintln(\"The output of\\nthis example.\")\n+\t\t// Output: The output of\n+\t\t// this example.\n \t}\n \n  The entire test file is presented as the example when it contains a single

コアとなるコードの解説

上記の差分は、go help testfunc で表示されるヘルプメッセージの一部を修正しています。

1. 変更前:

   That output is compared against the function's doc comment.
   An example without a doc comment is compiled but not executed.
   

   ここでは、Example 関数の出力が「関数のドキュメントコメント」と比較されると記述されていました。また、ドキュメントコメントがない場合は実行されないとされていました。

2. 変更後:

   That output is compared against the function's "Output:" comment, which
   must be the last comment in the function body (see example below). An
   example with no such comment, or with no text after "Output:" is compiled
   but not executed.
   

   この修正により、出力が比較されるのは「関数の \"Output:\" コメント」であり、それが「関数本体の最後のコメントでなければならない」という重要な制約が追加されました。さらに、「そのようなコメントがない場合、または \"Output:\" の後にテキストがない場合」はコンパイルされるが実行されない、とより正確な条件が記述されています。

3. Example コードの変更:

   -\t\tPrintln("The output of this example function.")
   -\t\t// Output: The output of this example function.
   +\t\tPrintln("The output of\\nthis example.")
   +\t\t// Output: The output of
   +\t\t// this example.
   

   これは、ヘルプテキストに含まれる Example 関数の具体的なコード例の修正です。以前は単一行の出力例でしたが、変更後は \n を含む複数行の出力例に変更され、それに合わせて // Output: コメントも複数行で記述されるようになりました。これにより、複数行の出力を伴う Example 関数の記述方法がより明確に示されています。

これらの変更は、go test のヘルプドキュメントが Example 関数の実際の動作と期待される記述形式を正確に反映するようにするためのものです。

関連リンク

• Gerrit Change-ID: https://golang.org/cl/5695062 (このコミットに対応するGoプロジェクトのGerritレビューページ)

参考にした情報源リンク

• Go言語の testing パッケージに関する公式ドキュメント: https://pkg.go.dev/testing
• Go言語の Example 関数に関する一般的な情報 (Goの公式ブログやチュートリアルなど)
• go test コマンドのヘルプ (go help test または go help testfunc を実行して得られる情報)
• Go言語のドキュメンテーション慣習に関する情報 (godoc の動作など)