Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

このコミットは、Go言語のドキュメンテーション生成ツールである go/doc パッケージにおける挙動の修正に関するものです。具体的には、error 型と rune 型がGoの組み込み型（predeclared types）として正しく認識されず、これらの型を返すファクトリ関数がドキュメンテーション生成時に適切に扱われない問題を解決しています。

コミット

commit f7d473dd33e90e28285fcdbf8876ffbe1caed3a7
Author: Robert Griesemer <gri@golang.org>
Date:   Tue Jan 31 15:41:25 2012 -0800

    go/doc: added error, rune to list of predeclared types

    Don't throw away factory functions returning error or rune.

    Fixes #2820.

    R=rsc
    CC=golang-dev
    https://golang.org/cl/5604046

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

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

元コミット内容

go/doc: added error, rune to list of predeclared types

このコミットは、go/doc パッケージがGo言語の組み込み型（predeclared types）のリストに error と rune を追加するものです。これにより、error または rune を返すファクトリ関数がドキュメンテーション生成プロセスで誤って破棄されることを防ぎます。この変更は、Issue #2820 を修正します。

変更の背景

Go言語の go/doc パッケージは、Goのソースコードからドキュメンテーションを生成するためのツールです。このツールは、コード内の型、関数、変数などを解析し、それらのドキュメンテーションコメントを抽出して整形します。

このコミットが修正する問題は、go/doc が特定の組み込み型（predeclared types）を特別扱いしていることに起因します。以前のバージョンでは、error と rune がこの組み込み型のリストに含まれていませんでした。その結果、これらの型を戻り値として持つ「ファクトリ関数」（特定の型のインスタンスを生成する関数）が、ドキュメンテーション生成時に適切に認識されず、ドキュメントから除外されてしまうというバグがありました。

具体的には、go/doc は、特定の条件（例えば、戻り値が組み込み型である場合）に基づいて、ドキュメントに含めるべき関数とそうでない関数を判断していました。error や rune が組み込み型として認識されていないため、これらの型を返すファクトリ関数は、ドキュメント生成の対象外と判断され、結果として生成されるドキュメントに表示されませんでした。これは、Goの標準ライブラリやユーザーコードにおいて error や rune を返す重要なファクトリ関数が多数存在することを考えると、ドキュメンテーションの欠落という重大な問題を引き起こしていました。

このコミットは、error と rune を go/doc が認識する組み込み型のリストに追加することで、この問題を解決し、これらの型を返すファクトリ関数も正しくドキュメントに含められるようにします。

前提知識の解説

Go言語の組み込み型 (Predeclared Types)

Go言語には、言語仕様によってあらかじめ定義されている基本的な型がいくつか存在します。これらは「組み込み型（predeclared types）」と呼ばれ、int, string, bool, float64 などが含まれます。これらの型は、特別なインポートなしにプログラム中で直接使用できます。

このコミットで特に重要なのは、error と rune の二つの型です。

  • error 型: Go言語におけるエラーハンドリングの基本的なインターフェースです。Goでは、関数がエラーを返す場合、通常は戻り値の最後の要素として error 型の値を返します。error 型は組み込みインターフェースであり、Error() string メソッドを持つ任意の型が error インターフェースを満たします。
  • rune 型: Go言語におけるUnicodeコードポイントを表す型です。これは int32 のエイリアスであり、文字列をイテレートする際に個々のUnicode文字を扱うために使用されます。

go/doc パッケージは、これらの組み込み型を特別に扱い、ドキュメンテーション生成のロジックに影響を与えることがあります。

go/doc パッケージ

go/doc パッケージは、Goのソースコードからドキュメンテーションを抽出・生成するための標準ライブラリです。go doc コマンドや godoc ツール（Go 1.11以降は go doc に統合）の基盤となっています。このパッケージは、GoのAST（抽象構文木）を解析し、パッケージ、型、関数、変数、定数などの情報を抽出し、それらに付随するドキュメンテーションコメントを読み取ります。

go/doc は、ドキュメントを生成する際に、どの要素をドキュメントに含めるか、どのように表示するかを決定するための内部ロジックを持っています。このロジックの一部として、特定の型（特に組み込み型）を返すファクトリ関数を識別し、それらを適切に扱う必要があります。

ファクトリ関数 (Factory Functions)

プログラミングにおけるファクトリ関数とは、特定の型の新しいインスタンス（オブジェクトや値）を生成して返す関数のことを指します。Go言語では、コンストラクタの概念は明示的にありませんが、慣習的に New プレフィックスを持つ関数などがファクトリ関数として機能します。

例:

package mypackage

import "fmt"

// MyType はカスタム型です。
type MyType struct {
    value int
}

// NewMyType は MyType の新しいインスタンスを生成するファクトリ関数です。
func NewMyType(val int) *MyType {
    return &MyType{value: val}
}

// NewError は新しいエラーを生成するファクトリ関数です。
func NewError(msg string) error {
    return fmt.Errorf("custom error: %s", msg)
}

// NewRune は新しいruneを生成するファクトリ関数です。
func NewRune(r rune) rune {
    return r
}

このコミットの文脈では、NewError や NewRune のような関数が「ファクトリ関数」として問題になっていました。

技術的詳細

go/doc パッケージの内部では、ドキュメンテーションを生成する際に、Goのソースコードを解析し、その構造を表現するAST（抽象構文木）を構築します。このASTをトラバースしながら、ドキュメントに含めるべき要素（パッケージ、型、関数など）を識別します。

src/pkg/go/doc/reader.go ファイルは、この解析プロセスの一部を担っています。特に、predeclaredTypes というマップは、Go言語の組み込み型を識別するために使用されます。このマップは map[string]bool 型で、キーが型名の文字列、値が true となっています。

var predeclaredTypes = map[string]bool{
	"bool":       true,
	"byte":       true,
	"complex64":  true,
	"complex128": true,
	"float32":    true,
	"float64":    true,
	"int":        true,
	"int8":       true,
	"int16":      true,
	"int32":      true,
	"int64":      true,
	"string":     true,
	"uint":       true,
	"uint8":      true,
	"uint16":     true,
	"uint32":     true,
	"uint64":     true,
	"uintptr":    true,
}

go/doc の内部ロジックでは、関数がファクトリ関数であるかどうか、そしてその戻り値の型が組み込み型であるかどうかを判断する際に、この predeclaredTypes マップを参照していました。もし関数が組み込み型を返すファクトリ関数であると判断された場合、特定の処理（例えば、ドキュメントに含めるかどうかの判断）が行われます。

しかし、このマップに error と rune が含まれていなかったため、error や rune を返すファクトリ関数は、go/doc の内部ロジックで「組み込み型を返すファクトリ関数」として正しく認識されませんでした。その結果、これらの関数がドキュメンテーション生成時に「破棄」されてしまい、最終的なドキュメントに表示されないという問題が発生していました。

このコミットは、単に predeclaredTypes マップに error と rune のエントリを追加することで、この問題を解決します。これにより、go/doc はこれらの型を返すファクトリ関数を正しく識別し、ドキュメントに含めるべき対象として扱うことができるようになります。

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

変更は src/pkg/go/doc/reader.go ファイルの predeclaredTypes マップに対して行われています。

--- a/src/pkg/go/doc/reader.go
+++ b/src/pkg/go/doc/reader.go
@@ -488,6 +488,7 @@ var predeclaredTypes = map[string]bool{
 	"byte":       true,
 	"complex64":  true,
 	"complex128": true,
+	"error":      true,
 	"float32":    true,
 	"float64":    true,
 	"int":        true,
@@ -495,6 +496,7 @@ var predeclaredTypes = map[string]bool{
 	"int16":      true,
 	"int32":      true,
 	"int64":      true,
+	"rune":       true,
 	"string":     true,
 	"uint":       true,
 	"uint8":      true,

コアとなるコードの解説

上記の差分が示すように、predeclaredTypes マップに以下の2つのエントリが追加されました。

  1. "error": true,
  2. "rune": true,

この変更により、go/doc パッケージがGoのソースコードを解析する際に、error と rune がGo言語の組み込み型として認識されるようになります。

go/doc の内部では、関数がファクトリ関数であるかどうかを判断するロジックがあり、その戻り値の型が predeclaredTypes マップに存在するかどうかをチェックする部分があります。このチェックが error と rune に対して true を返すようになったことで、これらの型を返すファクトリ関数も、他の組み込み型を返すファクトリ関数と同様に、ドキュメンテーション生成の対象として適切に扱われるようになります。

結果として、error や rune を返す重要なファクトリ関数が、go doc コマンドや godoc ツールで生成されるドキュメントに正しく表示されるようになり、ドキュメンテーションの完全性が向上しました。

関連リンク

  • Go Change List (CL) 5604046: https://golang.org/cl/5604046
  • Go Issue #2820: このコミットが修正した具体的なIssueの詳細は、上記のCLページからリンクされている可能性があります。

参考にした情報源リンク

  • Go言語の公式ドキュメント: go/doc パッケージに関する情報
  • Go言語の仕様: 組み込み型に関する情報
  • Go言語のソースコード: src/pkg/go/doc/reader.go の変更履歴
  • Go言語のIssueトラッカー: Issue #2820 の詳細（CL 5604046から辿れる情報）