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

このコミットは、src/pkg/html/doc.go ファイルに影響を与えています。具体的には、2行の追加と2行の削除が行われ、合計4行が変更されています。

コミット

commit f6279b46f8220a90fb5bcadcfc8cdbe3eedd7cf2
Author: Gustavo Niemeyer <gustavo@niemeyer.net>
Date:   Fri Nov 18 01:06:59 2011 -0200

    html: fix doc after Err method name change
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5411045

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

https://github.com/golang/go/commit/f6279b46f8220a90fb5bcadcfc8cdbe3eedd7cf2

元コミット内容

html: fix doc after Err method name change

このコミットは、html パッケージ内の Err メソッド名の変更に伴い、ドキュメントを修正するものです。

変更の背景

このコミットの背景には、Go言語の標準ライブラリである html パッケージにおけるAPIの変更があります。具体的には、HTMLパーサーのトークナイザーがエラー情報を返すメソッドの名前が Error() から Err() へと変更されたことが原因です。

Go言語では、APIの設計において簡潔さと一貫性が重視されます。メソッド名が Error() の場合、Goの慣習として error インターフェースを実装している型が Error() メソッドを持つことが一般的です。しかし、このケースでは、トークナイザーのエラーメソッドが error インターフェースを直接実装しているわけではなく、単にエラーオブジェクトを返すためのメソッドであった可能性があります。

このような状況で、よりGoらしい、あるいはより明確な命名規則に合わせるために、メソッド名が Error() から Err() に変更されたと考えられます。この変更は、APIの利用者が混乱することなく、より直感的にメソッドの役割を理解できるようにするための改善の一環です。

このコミットは、そのAPI変更に伴い、html パッケージのドキュメント（doc.go）内のサンプルコードや説明が古いメソッド名 z.Error() を参照していたため、新しいメソッド名 z.Err() に更新する必要が生じたために行われました。ドキュメントはコードの正確な利用方法を伝える上で非常に重要であるため、APIの変更に追随してドキュメントも更新することは不可欠です。

前提知識の解説

Go言語の html パッケージ

Go言語の標準ライブラリには、HTMLのパース（解析）を行うための html パッケージが含まれています。このパッケージは、HTMLドキュメントをトークン（要素の開始タグ、終了タグ、テキスト、コメントなど）のストリームとして処理するための機能を提供します。

• トークナイザー (Tokenizer): html パッケージの中心的なコンポーネルの1つがトークナイザーです。これは、入力されたHTMLバイトストリームを読み込み、意味のあるトークンに分割する役割を担います。例えば、<p> は開始タグトークン、Hello はテキストトークン、</p> は終了タグトークンとして認識されます。
• z.Next(): トークナイザー (z は html.Tokenizer のインスタンスを指すことが多い) の Next() メソッドは、次のHTMLトークンを読み込み、そのトークンの種類（html.StartTagToken, html.TextToken, html.ErrorToken など）を返します。
• html.ErrorToken: Next() メソッドが html.ErrorToken を返した場合、それはパース中にエラーが発生したか、入力ストリームの終端に達したことを示します。
• エラーハンドリング: Go言語では、関数がエラーを返す場合、通常は戻り値の最後の要素として error 型の値を返します。nil であればエラーなし、nil でなければエラーが発生したことを意味します。このコミットで変更された z.Error() や z.Err() は、トークナイザーが遭遇した具体的なエラーオブジェクトを取得するためのメソッドです。

Go言語におけるエラーメソッドの命名慣習

Go言語では、error インターフェースを実装する型は、Error() string というシグネチャを持つメソッドを定義することが慣習となっています。このメソッドは、エラーの文字列表現を返します。

しかし、このコミットで言及されている z.Error() や z.Err() は、error インターフェースを実装しているわけではなく、単にエラーオブジェクト（error 型の値）を返すメソッドです。このような場合、Error() という命名は、error インターフェースの Error() メソッドと混同される可能性があり、Goの慣習からするとやや不自然に映ることがあります。

Err() という命名は、特定のオブジェクトが保持しているエラー状態を取得するためのメソッドとして、より一般的で簡潔なGoの慣習に沿っています。例えば、io.Reader や bufio.Scanner など、多くのGoの標準ライブラリの型が、内部のエラー状態を返すために Err() メソッドを提供しています。この変更は、html パッケージのAPIをGoの他の標準ライブラリとより一貫性のあるものにするための改善と見なせます。

技術的詳細

このコミットの技術的な詳細は、Go言語の html パッケージにおけるトークナイザーのエラー報告メカニズムの変更と、それに伴うドキュメントの同期にあります。

html.Tokenizer のエラー報告

html.Tokenizer は、HTMLドキュメントをトークン化する際に、パースエラーや入力の終端に達したことを html.ErrorToken を返すことで示します。この html.ErrorToken が返された後、トークナイザーの内部状態から具体的なエラーオブジェクトを取得するために、以前は Error() メソッドが提供されていました。

例えば、以下のようなコードスニペットが想定されます。

for {
    tt := z.Next()
    if tt == html.ErrorToken {
        // エラーまたはEOFの場合
        err := z.Error() // 以前のメソッド呼び出し
        if err == io.EOF {
            // 正常終了
            return nil
        }
        // エラー処理
        return err
    }
    // その他のトークン処理
}

メソッド名の変更とその影響

このコミットの前に、html.Tokenizer のエラー取得メソッドが Error() から Err() に変更されました。この変更は、GoのAPI設計における一貫性と簡潔性を追求した結果と考えられます。

• Error() から Err() への変更:
  • Error() というメソッド名は、Goの error インターフェースの Error() string メソッドと混同される可能性がありました。error インターフェースの Error() メソッドはエラーの文字列表現を返しますが、html.Tokenizer の Error() メソッドは error 型のオブジェクト自体を返します。
  • Err() という命名は、io.Reader や bufio.Scanner など、Goの他の標準ライブラリで、オブジェクトが保持する内部のエラー状態を返すための慣習的なメソッド名です。これにより、html パッケージのAPIがGoのエコシステム全体でより自然に感じられるようになります。

このメソッド名の変更自体は、このコミットの直接の変更ではありませんが、このコミットのトリガーとなりました。メソッド名が変更されたことで、既存のドキュメントやサンプルコードが古くなり、新しいAPIに適合させる必要が生じました。

doc.go の役割

src/pkg/html/doc.go は、Goのパッケージドキュメンテーションの一部です。Goでは、doc.go ファイルにパッケージ全体の概要や使用例、重要な概念などを記述することが一般的です。このファイルに書かれたコメントは、go doc コマンドや pkg.go.dev などのドキュメンテーションツールによって自動的に抽出され、公開されます。

したがって、doc.go 内のサンプルコードが古いAPIを参照していると、ユーザーが誤った方法でパッケージを使用する可能性があり、混乱を招きます。このコミットは、このドキュメントの不整合を解消し、ユーザーが常に最新かつ正確なAPI情報にアクセスできるようにすることを目的としています。

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

変更は src/pkg/html/doc.go ファイルの2箇所で行われています。

--- a/src/pkg/html/doc.go
+++ b/src/pkg/html/doc.go
@@ -37,7 +37,7 @@ lower-cased, and attributes are collected into a []Attribute. For example:
 	for {
 		if z.Next() == html.ErrorToken {
 			// Returning io.EOF indicates success.
-			return z.Error()
+			return z.Err()
 		}
 		emitToken(z.Token())
 	}
@@ -51,7 +51,7 @@ call to Next. For example, to extract an HTML page\'s anchor text:\n 		tt := z.Next()\n 		switch tt {\n 		case ErrorToken:\n-			return z.Error()
+			return z.Err()
 		case TextToken:\n 			if depth > 0 {\n 				// emitBytes should copy the []byte it receives,\n```

具体的には、以下の2行が変更されています。

1.  `return z.Error()` が `return z.Err()` に変更。
2.  `return z.Error()` が `return z.Err()` に変更。

## コアとなるコードの解説

このコミットにおけるコアとなるコードの変更は非常にシンプルで、`html.Tokenizer` のエラー取得メソッドの呼び出しを、古い `Error()` から新しい `Err()` に置き換えることです。

### 変更前: `return z.Error()`

変更前のコードでは、`html.Tokenizer` のインスタンス `z` に対して `Error()` メソッドを呼び出していました。これは、トークナイザーが `html.ErrorToken` を返した場合に、そのエラーの詳細を取得するためのものです。

```go
// 以前のコード
if z.Next() == html.ErrorToken {
    // Returning io.EOF indicates success.
    return z.Error() // ここで古いメソッドが呼ばれていた
}

変更後: return z.Err()

変更後のコードでは、Error() メソッドの代わりに Err() メソッドが呼び出されています。これは、html.Tokenizer のAPIが変更され、エラー取得メソッドの名前が Err() に統一されたためです。

// 変更後のコード
if z.Next() == html.ErrorToken {
    // Returning io.EOF indicates success.
    return z.Err() // 新しいメソッドが呼ばれる
}

この変更は、html パッケージの内部で html.Tokenizer のエラー取得メソッドの名前が Error() から Err() に変更されたことに伴う、ドキュメントの修正です。この修正により、html パッケージのドキュメントに記載されているサンプルコードが、最新のAPIと一致するようになり、ユーザーが正確な情報を参照できるようになりました。

Go言語の標準ライブラリでは、APIの安定性と一貫性が非常に重視されます。このようなメソッド名の変更は、通常、より良いAPI設計やGoの慣習への準拠を目指して行われます。そして、それに伴い、ドキュメントも迅速に更新されることが重要です。このコミットは、そのプロセスの一環として、ドキュメントの正確性を保つためのメンテナンス作業と言えます。

関連リンク

• Go言語の html パッケージのドキュメント: https://pkg.go.dev/golang.org/x/net/html (Go 1.0以降、html パッケージは golang.org/x/net/html に移動しています。このコミットが行われた2011年当時は、まだ標準ライブラリの一部として src/pkg/html に存在していた可能性があります。)
• Go言語の io.EOF について: https://pkg.go.dev/io#pkg-variables
• Go言語のエラーハンドリングに関する公式ブログ記事: https://go.dev/blog/error-handling-and-go

参考にした情報源リンク

• Go言語の公式ドキュメンテーション
• Go言語のエラーハンドリングに関する一般的な慣習
• Go言語のAPI設計原則に関する情報
• GitHubのコミット履歴と差分表示
• Go言語の html パッケージの歴史的経緯に関する情報 (必要に応じてWeb検索)

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

このコミットは、src/pkg/html/doc.go ファイルに影響を与えています。具体的には、2行の追加と2行の削除が行われ、合計4行が変更されています。

コミット

commit f6279b46f8220a90fb5bcadcfc8cdbe3eedd7cf2
Author: Gustavo Niemeyer <gustavo@niemeyer.net>
Date:   Fri Nov 18 01:06:59 2011 -0200

    html: fix doc after Err method name change
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5411045

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

https://github.com/golang/go/commit/f6279b46f8220a90fb5bcadcfc8cdbe3eedd7cf2

元コミット内容

html: fix doc after Err method name change

このコミットは、html パッケージ内の Err メソッド名の変更に伴い、ドキュメントを修正するものです。

変更の背景

このコミットの背景には、Go言語の標準ライブラリである html パッケージにおけるAPIの変更があります。具体的には、HTMLパーサーのトークナイザーがエラー情報を返すメソッドの名前が Error() から Err() へと変更されたことが原因です。

Go言語では、APIの設計において簡潔さと一貫性が重視されます。メソッド名が Error() の場合、Goの慣習として error インターフェースを実装している型が Error() メソッドを持つことが一般的です。しかし、このケースでは、トークナイザーのエラーメソッドが error インターフェースを直接実装しているわけではなく、単にエラーオブジェクトを返すためのメソッドであった可能性があります。

このような状況で、よりGoらしい、あるいはより明確な命名規則に合わせるために、メソッド名が Error() から Err() に変更されたと考えられます。この変更は、APIの利用者が混乱することなく、より直感的にメソッドの役割を理解できるようにするための改善の一環です。

このコミットは、そのAPI変更に伴い、html パッケージのドキュメント（doc.go）内のサンプルコードや説明が古いメソッド名 z.Error() を参照していたため、新しいメソッド名 z.Err() に更新する必要が生じたために行われました。ドキュメントはコードの正確な利用方法を伝える上で非常に重要であるため、APIの変更に追随してドキュメントも更新することは不可欠です。

前提知識の解説

Go言語の html パッケージ

Go言語の標準ライブラリには、HTMLのパース（解析）を行うための html パッケージが含まれています。このパッケージは、HTMLドキュメントをトークン（要素の開始タグ、終了タグ、テキスト、コメントなど）のストリームとして処理するための機能を提供します。

• トークナイザー (Tokenizer): html パッケージの中心的なコンポーネルの1つがトークナイザーです。これは、入力されたHTMLバイトストリームを読み込み、意味のあるトークンに分割する役割を担います。例えば、<p> は開始タグトークン、Hello はテキストトークン、</p> は終了タグトークンとして認識されます。
• z.Next(): トークナイザー (z は html.Tokenizer のインスタンスを指すことが多い) の Next() メソッドは、次のHTMLトークンを読み込み、そのトークンの種類（html.StartTagToken, html.TextToken, html.ErrorToken など）を返します。
• html.ErrorToken: Next() メソッドが html.ErrorToken を返した場合、それはパース中にエラーが発生したか、入力ストリームの終端に達したことを示します。
• エラーハンドリング: Go言語では、関数がエラーを返す場合、通常は戻り値の最後の要素として error 型の値を返します。nil であればエラーなし、nil でなければエラーが発生したことを意味します。このコミットで変更された z.Error() や z.Err() は、トークナイザーが遭遇した具体的なエラーオブジェクトを取得するためのメソッドです。

Go言語におけるエラーメソッドの命名慣習

Go言語では、error インターフェースを実装する型は、Error() string というシグネチャを持つメソッドを定義することが慣習となっています。このメソッドは、エラーの文字列表現を返します。

しかし、このコミットで言及されている z.Error() や z.Err() は、error インターフェースを実装しているわけではなく、単にエラーオブジェクト（error 型の値）を返すメソッドです。このような場合、Error() という命名は、error インターフェースの Error() メソッドと混同される可能性があり、Goの慣習からするとやや不自然に映ることがあります。

Err() という命名は、特定のオブジェクトが保持しているエラー状態を取得するためのメソッドとして、より一般的で簡潔なGoの慣習に沿っています。例えば、io.Reader や bufio.Scanner など、多くのGoの標準ライブラリの型が、内部のエラー状態を返すために Err() メソッドを提供しています。この変更は、html パッケージのAPIをGoの他の標準ライブラリとより一貫性のあるものにするための改善と見なせます。

技術的詳細

このコミットの技術的な詳細は、Go言語の html パッケージにおけるトークナイザーのエラー報告メカニズムの変更と、それに伴うドキュメントの同期にあります。

html.Tokenizer のエラー報告

html.Tokenizer は、HTMLドキュメントをトークン化する際に、パースエラーや入力の終端に達したことを html.ErrorToken を返すことで示します。この html.ErrorToken が返された後、トークナイザーの内部状態から具体的なエラーオブジェクトを取得するために、以前は Error() メソッドが提供されていました。

例えば、以下のようなコードスニペットが想定されます。

for {
    tt := z.Next()
    if tt == html.ErrorToken {
        // エラーまたはEOFの場合
        err := z.Error() // 以前のメソッド呼び出し
        if err == io.EOF {
            // 正常終了
            return nil
        }
        // エラー処理
        return err
    }
    // その他のトークン処理
}

メソッド名の変更とその影響

このコミットの前に、html.Tokenizer のエラー取得メソッドが Error() から Err() に変更されました。この変更は、GoのAPI設計における一貫性と簡潔性を追求した結果と考えられます。

• Error() から Err() への変更:
  • Error() というメソッド名は、Goの error インターフェースの Error() string メソッドと混同される可能性がありました。error インターフェースの Error() メソッドはエラーの文字列表現を返しますが、html.Tokenizer の Error() メソッドは error 型のオブジェクト自体を返します。
  • Err() という命名は、io.Reader や bufio.Scanner など、Goの他の標準ライブラリで、オブジェクトが保持する内部のエラー状態を返すための慣習的なメソッド名です。これにより、html パッケージのAPIがGoのエコシステム全体でより自然に感じられるようになります。

このメソッド名の変更自体は、このコミットの直接の変更ではありませんが、このコミットのトリガーとなりました。メソッド名が変更されたことで、既存のドキュメントやサンプルコードが古くなり、新しいAPIに適合させる必要が生じました。

doc.go の役割

src/pkg/html/doc.go は、Goのパッケージドキュメンテーションの一部です。Goでは、doc.go ファイルにパッケージ全体の概要や使用例、重要な概念などを記述することが一般的です。このファイルに書かれたコメントは、go doc コマンドや pkg.go.dev などのドキュメンテーションツールによって自動的に抽出され、公開されます。

したがって、doc.go 内のサンプルコードが古いAPIを参照していると、ユーザーが誤った方法でパッケージを使用する可能性があり、混乱を招きます。このコミットは、このドキュメントの不整合を解消し、ユーザーが常に最新かつ正確なAPI情報にアクセスできるようにすることを目的としています。

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

変更は src/pkg/html/doc.go ファイルの2箇所で行われています。

--- a/src/pkg/html/doc.go
+++ b/src/pkg/html/doc.go
@@ -37,7 +37,7 @@ lower-cased, and attributes are collected into a []Attribute. For example:
 	for {
 		if z.Next() == html.ErrorToken {
 			// Returning io.EOF indicates success.
-			return z.Error()
+			return z.Err()
 		}
 		emitToken(z.Token())
 	}
@@ -51,7 +51,7 @@ call to Next. For example, to extract an HTML page\'s anchor text:\n 		tt := z.Next()\n 		switch tt {\n 		case ErrorToken:\n-			return z.Error()
+			return z.Err()
 		case TextToken:\n 			if depth > 0 {\n 				// emitBytes should copy the []byte it receives,\n```

具体的には、以下の2行が変更されています。

1.  `return z.Error()` が `return z.Err()` に変更。
2.  `return z.Error()` が `return z.Err()` に変更。

## コアとなるコードの解説

このコミットにおけるコアとなるコードの変更は非常にシンプルで、`html.Tokenizer` のエラー取得メソッドの呼び出しを、古い `Error()` から新しい `Err()` に置き換えることです。

### 変更前: `return z.Error()`

変更前のコードでは、`html.Tokenizer` のインスタンス `z` に対して `Error()` メソッドを呼び出していました。これは、トークナイザーが `html.ErrorToken` を返した場合に、そのエラーの詳細を取得するためのものです。

```go
// 以前のコード
if z.Next() == html.ErrorToken {
    // Returning io.EOF indicates success.
    return z.Error() // ここで古いメソッドが呼ばれていた
}

変更後: return z.Err()

変更後のコードでは、Error() メソッドの代わりに Err() メソッドが呼び出されています。これは、html.Tokenizer のAPIが変更され、エラー取得メソッドの名前が Err() に統一されたためです。

// 変更後のコード
if z.Next() == html.ErrorToken {
    // Returning io.EOF indicates success.
    return z.Err() // 新しいメソッドが呼ばれる
}

この変更は、html パッケージの内部で html.Tokenizer のエラー取得メソッドの名前が Error() から Err() に変更されたことに伴う、ドキュメントの修正です。この修正により、html パッケージのドキュメントに記載されているサンプルコードが、最新のAPIと一致するようになり、ユーザーが正確な情報を参照できるようになりました。

Go言語の標準ライブラリでは、APIの安定性と一貫性が非常に重視されます。このようなメソッド名の変更は、通常、より良いAPI設計やGoの慣習への準拠を目指して行われます。そして、それに伴い、ドキュメントも迅速に更新されることが重要です。このコミットは、そのプロセスの一環として、ドキュメントの正確性を保つためのメンテナンス作業と言えます。

関連リンク

• Go言語の html パッケージのドキュメント: https://pkg.go.dev/golang.org/x/net/html (Go 1.0以降、html パッケージは golang.org/x/net/html に移動しています。このコミットが行われた2011年当時は、まだ標準ライブラリの一部として src/pkg/html に存在していた可能性があります。)
• Go言語の io.EOF について: https://pkg.go.dev/io#pkg-variables
• Go言語のエラーハンドリングに関する公式ブログ記事: https://go.dev/blog/error-handling-and-go

参考にした情報源リンク

• Go言語の公式ドキュメンテーション
• Go言語のエラーハンドリングに関する一般的な慣習
• Go言語のAPI設計原則に関する情報
• GitHubのコミット履歴と差分表示
• Go言語の html パッケージの歴史的経緯に関する情報 (必要に応じてWeb検索)