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

このコミットは、Go言語の標準ライブラリである encoding/json パッケージ内の encode.go ファイルに対するドキュメンテーションの修正です。具体的には、json.Marshal 関数がサポートされていない型をエンコードしようとした際に返すエラーの型に関する記述を修正しています。

コミット

commit 83771afe1022da584767cbac988446497d683bae
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Wed May 23 17:18:05 2012 -0700

    encoding/json: documentation fix
    
    Fixes #3650
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/6238046

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

https://github.com/golang/go/commit/83771afe1022da584767cbac988446497d683bae

元コミット内容

encoding/json: documentation fix

このコミットは、encoding/json パッケージのドキュメンテーションの修正を目的としています。

変更の背景

この変更は、GitHubのIssue #3650 に対応するものです。元のドキュメンテーションでは、json.Marshal 関数がJSONエンコードできない値（チャネル、複素数、関数など）を扱った場合に InvalidTypeError を返すと記述されていました。しかし、実際には UnsupportedTypeError を返すのが正しい挙動でした。このコミットは、ドキュメンテーションの記述を実際の挙動に合わせて InvalidTypeError から UnsupportedTypeError へと修正し、さらに UnsupportedTypeError の定義をドキュメンテーションに追加することで、より正確で分かりやすい情報を提供することを目的としています。

前提知識の解説

• encoding/json パッケージ: Go言語の標準ライブラリの一つで、Goのデータ構造とJSONデータの間で変換（エンコード/デコード）を行う機能を提供します。
• json.Marshal 関数: Goの値をJSON形式にエンコードする関数です。この関数は、Goの構造体、マップ、スライス、プリミティブ型などをJSONのオブジェクト、配列、値に変換します。
• JSONエンコードの制約: JSONは、すべてのGoの型を表現できるわけではありません。特に、チャネル、複素数、関数といった型はJSONには直接対応する表現がありません。
• InvalidTypeError と UnsupportedTypeError:
  • InvalidTypeError は、Goの reflect パッケージなどで、無効な型操作が行われた場合に返されることがある一般的なエラー型です。
  • UnsupportedTypeError は、encoding/json パッケージにおいて、JSONエンコードがサポートされていない特定のGoの型が json.Marshal に渡された場合に返されるエラー型です。このエラー型は、encoding/json パッケージ内で定義されており、Type reflect.Type フィールドを持つことで、どの型がサポートされていないかを具体的に示すことができます。

技術的詳細

json.Marshal 関数は、Goの値をJSONバイト列に変換する際に、Goの reflect パッケージを使用して値の型情報を検査します。JSONの仕様上、チャネル、複素数、関数といった特定のGoの型はJSONで表現できません。これらの型が Marshal 関数に渡された場合、Marshal はエラーを返して処理を中断する必要があります。

このコミット以前のドキュメンテーションでは、この際に InvalidTypeError が返されると誤って記述されていました。しかし、encoding/json パッケージは、より具体的なエラー情報を提供するために UnsupportedTypeError という独自のエラー型を定義しています。この UnsupportedTypeError は、reflect.Type フィールドを持つことで、どの具体的な型がエンコードできなかったのかを呼び出し元に伝えることができます。これは、単に「無効な型」とだけ伝える InvalidTypeError よりも、エラーの原因を特定しやすく、デバッグを容易にする点で優れています。

このコミットは、ドキュメンテーションの記述を実際のコードの挙動（UnsupportedTypeError を返す）に合わせることで、開発者が encoding/json パッケージをより正確に理解し、適切にエラーハンドリングを行えるようにするための重要な修正です。また、UnsupportedTypeError の定義をコメントとして追加することで、このエラー型の存在と目的を明確にしています。

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

src/pkg/encoding/json/encode.go ファイルの以下の部分が変更されました。

--- a/src/pkg/encoding/json/encode.go
+++ b/src/pkg/encoding/json/encode.go
@@ -96,7 +96,7 @@ import (
 //
 // Channel, complex, and function values cannot be encoded in JSON.
 // Attempting to encode such a value causes Marshal to return
-// an InvalidTypeError.
+// an UnsupportedTypeError.
 //
 // JSON cannot represent cyclic data structures and Marshal does not
 // handle them.  Passing cyclic structures to Marshal will result in
@@ -157,6 +157,8 @@ type Marshaler interface {
 	MarshalJSON() ([]byte, error)
 }
 
+// An UnsupportedTypeError is returned by Marshal when attempting
+// to encode an unsupported value type.
 type UnsupportedTypeError struct {
 	Type reflect.Type
 }

コアとなるコードの解説

1. ドキュメンテーションの修正: // Attempting to encode such a value causes Marshal to return の行の次の行が、 - an InvalidTypeError. から + an UnsupportedTypeError. に変更されました。 これは、json.Marshal 関数がサポートされていない型をエンコードしようとした際に返すエラーの型が InvalidTypeError ではなく UnsupportedTypeError であることを明確にするための修正です。

2. UnsupportedTypeError のコメント追加: type UnsupportedTypeError struct { の直前に、以下のコメントが追加されました。 // An UnsupportedTypeError is returned by Marshal when attempting // to encode an unsupported value type. このコメントは、UnsupportedTypeError の目的と、それがどのような場合に返されるのかを説明しています。これにより、このエラー型が encoding/json パッケージの公開APIの一部としてどのように機能するかが明確になります。

これらの変更は、コードの動作自体を変更するものではなく、encoding/json パッケージのドキュメンテーションの正確性を向上させ、開発者がより正確な情報を得られるようにするためのものです。

関連リンク

• Go CL (Code Review) へのリンク: https://golang.org/cl/6238046
• 関連するGitHub Issue: https://github.com/golang/go/issues/3650

参考にした情報源リンク

• https://github.com/golang/go/issues/3650 (GitHub Issue: encoding/json: documentation for InvalidTypeError is incorrect)