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

このコミットは、Go言語の標準ライブラリ sync パッケージ内の WaitGroup 型のドキュメントから、古くて冗長なコード例を削除するものです。これにより、ドキュメントの可読性と整合性が向上します。

コミット

commit 986df83e0de4b762b66f9cd6f4af3d8ad5f25bf5
Author: Dmitriy Vyukov <dvyukov@google.com>
Date:   Thu Mar 1 21:26:08 2012 +0400

    sync: remove old WaitGroup example
    The docs look awkward - there is a paragraph
    "For example:" with a plain text example,
    and straight below it a real Example.
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5717048

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

https://github.com/golang/go/commit/986df83e0de4b762b66f9cd6f4af3d8ad5f25bf5

元コミット内容

sync: remove old WaitGroup example

このコミットは、sync パッケージの WaitGroup のドキュメントから古いコード例を削除します。ドキュメントには「For example:」という段落があり、その直下にプレーンテキストの例があり、さらにそのすぐ下に実際の Example 関数による例があるため、見た目が不格好であるという問題が指摘されています。

変更の背景

Go言語のドキュメンテーションツール godoc は、ソースコード内の特定のコメント形式（特に Example 関数）を解析し、自動的に実行可能なコード例としてドキュメントに表示する機能を持っています。これにより、ドキュメントのコード例が常に最新かつ正確であることが保証されます。

このコミットが行われる以前の sync.WaitGroup のドキュメントには、以下のような問題がありました。

冗長性: WaitGroup の説明の後に、「For example:」という見出しとともに、通常のコメントブロックとして書かれたコード例が存在していました。
非推奨の形式: そのプレーンテキストの例のすぐ下に、godoc が認識する正式な Example 関数（ExampleWaitGroup など）によるコード例も存在していました。

このように、同じ内容のコード例が異なる形式で二重に存在することで、ドキュメントが「不格好 (awkward)」に見え、読者にとって混乱を招く可能性がありました。このコミットは、冗長で非推奨のプレーンテキストの例を削除し、正式な Example 関数による例のみを残すことで、ドキュメントの品質と整合性を向上させることを目的としています。

前提知識の解説

`sync.WaitGroup`

sync.WaitGroup は、Go言語の標準ライブラリ sync パッケージで提供される同期プリミティブの一つです。複数のゴルーチン（軽量スレッド）の完了を待機するために使用されます。主に以下の3つのメソッドで構成されます。

Add(delta int): WaitGroup のカウンタに delta を加算します。通常、新しいゴルーチンを起動する前に Add(1) を呼び出し、待機するゴルーチンの数を増やします。カウンタが負の値になるとパニックします。
Done(): WaitGroup のカウンタを1減らします。これは、ゴルーチンがそのタスクを完了したときに呼び出されるべきです。通常、defer wg.Done() の形式でゴルーチンの開始時に設定されます。
Wait(): WaitGroup のカウンタが0になるまでブロックします。すべてのゴルーチンが Done() を呼び出してカウンタが0になった後、Wait() を呼び出しているゴルーチンはブロック解除されます。

WaitGroup は、例えば、メインゴルーチンが複数のバックグラウンドゴルーチンを起動し、それらすべての処理が完了するのを待ってから次の処理に進む、といったシナリオで非常に有用です。

Go言語のドキュメンテーションと `Example` 関数

Go言語では、ソースコード内のコメントがそのままドキュメントとして利用されるという特徴があります。特に、godoc ツールは、パッケージ、関数、型、変数などの宣言の直前にあるコメントを抽出し、HTML形式のドキュメントを生成します。

さらに、godoc には特別な機能として「Example 関数」があります。これは、Example というプレフィックスを持つ関数（例: ExampleWaitGroup や Example_MyFunction）として記述され、その関数内のコードがドキュメントに表示されるだけでなく、go test コマンドによって実際に実行され、その出力がドキュメントに埋め込まれます。これにより、ドキュメントのコード例が常にコンパイル可能で、期待通りの動作をすることが保証されます。

この仕組みは、ドキュメントの品質を高く保つ上で非常に重要であり、Goコミュニティでは Example 関数を用いたドキュメンテーションが推奨されています。

技術的詳細

このコミットは、src/pkg/sync/waitgroup.go ファイル内の WaitGroup 型の定義に付随するドキュメンテーションコメントを修正しています。具体的には、WaitGroup の説明の後に続く、以下のような形式のプレーンテキストのコード例が削除されました。

// For example:
//
//   for i := 0; i < n; i++ {
//       if !condition(i) {
//           continue
//       }
//       wg.Add(1)
//       go func() {
//           // Do something.
//           wg.Done()
//       }()
//   }
//   wg.Wait()
//

この例は、godoc が自動的に実行・検証する Example 関数とは異なり、単なるコメントとして記述されていました。そのため、この例が古くなったり、コンパイルエラーを含むようになったりしても、自動的に検出されることはありませんでした。

このプレーンテキストの例の直下には、すでに godoc が認識する正式な ExampleWaitGroup 関数が存在しており、そちらが推奨される形式でした。したがって、このコミットは、冗長でメンテナンスが困難な古い形式の例を削除し、ドキュメントをより簡潔で、かつ godoc のベストプラクティスに沿った形に整理するものです。

変更自体は非常に小さく、コードの動作には一切影響を与えません。純粋にドキュメンテーションの改善を目的としたコミットです。

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

--- a/src/pkg/sync/waitgroup.go
+++ b/src/pkg/sync/waitgroup.go
@@ -11,21 +11,6 @@ import "sync/atomic"
 // goroutines to wait for.  Then each of the goroutines
 // runs and calls Done when finished.  At the same time,\n // Wait can be used to block until all goroutines have finished.
-//
-// For example:
-//
-//   for i := 0; i < n; i++ {
-//       if !condition(i) {
-//           continue
-//       }
-//       wg.Add(1)
-//       go func() {
-//           // Do something.
-//           wg.Done()\n //       }()
-//   }\n //   wg.Wait()\n // 
 type WaitGroup struct {
 	m       Mutex
 	counter int32

コアとなるコードの解説

上記の差分が示すように、src/pkg/sync/waitgroup.go ファイルから、WaitGroup 型の定義の直前にあった15行のコメントブロックが削除されています。このコメントブロックは、WaitGroup の使用例をプレーンテキスト形式で示していました。

削除されたコードは、WaitGroup の基本的な Add、Done、Wait メソッドの典型的な使用パターンを示していましたが、これはすでに godoc の Example 関数として提供されている内容と重複していました。

この変更により、WaitGroup のドキュメントはより簡潔になり、読者は godoc が提供する実行可能な Example 関数に集中できるようになります。これは、Go言語のドキュメンテーションの哲学である「簡潔さ」と「実行可能な例による検証」に合致する改善です。

参考にした情報源リンク

Go言語の公式ドキュメント (sync パッケージ): https://pkg.go.dev/sync
Go言語のドキュメンテーションに関する公式ブログ記事やガイドライン (一般的な知識に基づくため特定のURLはなし)
godoc ツールの動作に関する一般的な情報 (一般的な知識に基づくため特定のURLはなし)

comemo