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

このコミットは、Go言語の標準ライブラリ go/doc パッケージ内の example.go ファイルに対する変更です。具体的には、Goのドキュメンテーションツールが「プレイアブル（実行可能）」なExampleをどのように認識し、表示するかについての条件をドキュメントコメントとして追加しています。

コミット

commit 13d85668ac42525564f04e85f9529d993812f345
Author: Andrew Gerrand <adg@golang.org>
Date:   Tue Feb 18 15:53:22 2014 +1100

    go/doc: document the conditions where examples are "playable"
    
    LGTM=r
    R=r
    CC=golang-codereviews
    https://golang.org/cl/64910043

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

https://github.com/golang/go/commit/13d85668ac42525564f04e85f9529d993812f345

元コミット内容

go/doc: document the conditions where examples are "playable"

このコミットは、GoのドキュメンテーションツールがExampleを「プレイアブル」と判断する条件をドキュメントに追加するものです。

変更の背景

Go言語では、コードのExample（使用例）をテストコードとして記述し、それを自動的にドキュメンテーションに含める機能があります。これらのExampleは、go test コマンドで実行できるだけでなく、go doc コマンドや pkg.go.dev のようなオンラインドキュメンテーションサイトで表示され、さらに一部のExampleは「Go Playground」と呼ばれるインタラクティブな環境で直接実行できるようになっています。

この「プレイアブル」なExampleは、ユーザーが実際にコードを試すことができるため、ドキュメンテーションの質を大きく向上させます。しかし、どのようなExampleがプレイアブルとして扱われるかという明確な基準が、コードベースのドキュメントに不足していました。このコミットは、その基準を go/doc パッケージの Example 型のコメントとして明記することで、開発者がプレイアブルなExampleを記述する際の指針を提供し、ツールの挙動をより透過的にすることを目的としています。

前提知識の解説

GoのExampleとテスト

Go言語では、Exampleは通常のテスト関数 (TestXxx) やベンチマーク関数 (BenchmarkXxx) と同様に、_test.go ファイル内に記述されます。Example関数は ExampleXxx という命名規則に従い、通常は fmt.Println などで出力を生成し、その出力が期待される出力と一致するかどうかでテストされます。

package mypackage_test

import (
	"fmt"
)

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

上記のExampleは、go test で実行され、go doc でドキュメンテーションに表示されます。

go/doc パッケージ

go/doc パッケージは、Goのソースコードからドキュメンテーションを生成するためのツールです。このパッケージは、GoのAST（抽象構文木）を解析し、パッケージ、関数、型、変数、定数、そしてExampleなどの情報を抽出して構造化されたデータとして提供します。go doc コマンドや pkg.go.dev は、この go/doc パッケージを利用してドキュメンテーションを生成しています。

Go Playground

Go Playgroundは、Goのコードをブラウザ上で記述・実行できるインタラクティブな環境です。Goのドキュメンテーションサイトに表示されるプレイアブルなExampleは、このGo Playgroundの機能を利用して、ユーザーが直接コードを実行し、その結果を確認できるようにしています。

プレイアブルなExampleの重要性

プレイアブルなExampleは、Goのドキュメンテーションの非常に強力な機能です。

1. 理解の促進: ユーザーはコードの動作を即座に確認できるため、APIの理解が深まります。
2. 学習体験の向上: 新しいGoユーザーが言語やライブラリの機能を試すための手軽な方法を提供します。
3. デモンストレーション: 特定の機能やユースケースを効果的にデモンストレーションできます。

しかし、Go Playgroundはサンドボックス環境であり、外部ネットワークアクセスやファイルシステムアクセスなど、一部の機能が制限されています。そのため、すべてのExampleがプレイアブルにできるわけではなく、特定の条件を満たす必要があります。このコミットは、その条件を明確にすることで、開発者がプレイアブルなExampleを意図的に作成できるように支援します。

技術的詳細

このコミットは、go/doc パッケージの Example 構造体のコメントに、Exampleが「プレイアブル」であるための条件を追記しています。

追加されたコメントによると、Exampleが「プレイアブル」である（Play フィールドが非nilである）ためには、以下のいずれかの条件を満たす必要があります。

1. 自己完結型 (Self-contained) のExample関数:

   • Example関数が、他のパッケージの識別子（または int のような事前宣言された識別子）のみを参照していること。
   • テストファイルがドットインポート（import . "some/package"）を含んでいないこと。 この条件は、Exampleが外部の複雑な依存関係を持たず、Go Playgroundのような隔離された環境で容易に実行できることを保証します。ドットインポートは、パッケージ内の識別子を修飾なしで直接参照できるようにするため、Exampleの依存関係を不明瞭にし、Go Playgroundでの実行を困難にする可能性があります。

2. ファイル全体がExampleである場合:

   • ファイルにExample関数がちょうど1つだけ含まれていること。
   • テスト関数やベンチマーク関数がゼロであること。
   • Example関数以外のトップレベルの関数、型、変数、または定数宣言が少なくとも1つ含まれていること。 この条件は、Exampleが単一の目的を持ち、そのファイルがExampleのデモンストレーションに特化している場合に適用されます。Example関数以外のトップレベル宣言があることで、Exampleがそのパッケージの特定の機能や構造をどのように使用するかを示す、より完全な例として機能することを意図しています。

これらの条件は、Go Playgroundの制約と、Exampleがドキュメンテーションとして提供される際の明確性を考慮して設計されています。

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

変更は src/pkg/go/doc/example.go ファイルに対して行われています。

--- a/src/pkg/go/doc/example.go
+++ b/src/pkg/go/doc/example.go
@@ -32,6 +32,17 @@ type Example struct {
  
  // Examples returns the examples found in the files, sorted by Name field.
  // The Order fields record the order in which the examples were encountered.
+//
+// Playable Examples must be in a package whose name ends in "_test".
+// An Example is "playable" (the Play field is non-nil) in either of these
+// circumstances:
+//   - The example function is self-contained: the function references only
+//     identifiers from other packages (or predeclared identifiers, such as
+//     "int") and the test file does not include a dot import.
+//   - The entire test file is the example: the file contains exactly one
+//     example function, zero test or benchmark functions, and at least one
+//     top-level function, type, variable, or constant declaration other
+//     than the example function.
  func Examples(files ...*ast.File) []*Example {
  	var list []*Example
  	for _, file := range files {

コアとなるコードの解説

変更は、Example 構造体の定義の直後にある Examples 関数のドキュメントコメントに追加されています。

• Playable Examples must be in a package whose name ends in "_test". これは、Exampleがプレイアブルであるためには、_test サフィックスを持つパッケージ（例: mypackage_test）に属している必要があることを明確にしています。これはGoのテストファイルの命名規則と一致しており、Exampleがテストの一部として扱われることを示唆しています。

• An Example is "playable" (the Play field is non-nil) in either of these circumstances: ここから、具体的なプレイアブルの条件が列挙されています。

  • The example function is self-contained: the function references only identifiers from other packages (or predeclared identifiers, such as "int") and the test file does not include a dot import. 前述の「自己完結型」の条件です。Example関数が、そのExampleが属するパッケージ内の他の識別子を参照せず、外部パッケージの識別子や組み込み型のみを参照する場合にプレイアブルとなります。また、ドットインポートがないことも条件です。

  • The entire test file is the example: the file contains exactly one example function, zero test or benchmark functions, and at least one top-level function, type, variable, or constant declaration other than the example function. 前述の「ファイル全体がExample」の条件です。ファイル内にExample関数が1つだけで、テストやベンチマーク関数がなく、Example関数以外のトップレベル宣言がある場合にプレイアブルとなります。

これらのコメントは、go/doc パッケージがExampleを解析し、Example 構造体の Play フィールドを設定する際の内部ロジックを外部に公開するものです。これにより、Goのドキュメンテーションシステムがどのように機能するかを開発者が理解し、それに応じてExampleを記述できるようになります。

関連リンク

• Go言語のExampleに関する公式ドキュメント: https://go.dev/blog/examples
• go/doc パッケージのドキュメント: https://pkg.go.dev/go/doc
• Go Playground: https://go.dev/play/

参考にした情報源リンク

• Go言語の公式ドキュメント
• Go Playgroundの動作原理に関する一般的な知識
• GoのテストとExampleの慣習に関する一般的な知識