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

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

このコミットは、Go言語の公式ドキュメンテーションツールであるgodocのHTMLテンプレートファイルlib/godoc/package.htmlに対する変更です。具体的には、型名（Type.Name）の扱いを簡素化し、テンプレート内で直接アクセスできるように修正しています。また、不要になったテンプレート変数の宣言を削除しています。

コミット

commit d191ad11aeb75959621777a9da17dcd8efdb6304
Author: Robert Griesemer <gri@golang.org>
Date:   Mon Jan 23 16:08:05 2012 -0800

    lib/godoc: use Type.Name directly

    Also: remove an unused template variable declaration.

    R=adg
    CC=golang-dev
    https://golang.org/cl/5572043

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

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

元コミット内容

diff --git a/lib/godoc/package.html b/lib/godoc/package.html
index 5a7f3ef976..d84c1c1e7f 100644
--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -20,8 +20,7 @@
 		<dd><a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
 	{{end}}
 	{{range .Types}}
-		{{$tname := printf "%s" .Type.Name}}
-		{{$tname_html := node_html .Type.Name $.FSet}}
+		{{$tname_html := html .Name}}
 		<dd><a href="#{{$tname_html}}">type {{$tname_html}}</a></dd>
 		{{range .Funcs}}
 			{{$name_html := html .Name}}
@@ -86,8 +85,8 @@
 		{{example_html .Name $.Examples $.FSet}}
 	{{end}}
 	{{range .Types}}
-		{{$tname := printf "%s" .Type.Name}}
-		{{$tname_html := node_html .Type.Name $.FSet}}
+		{{$tname := .Name}}
+		{{$tname_html := html .Name}}
 		<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
 		{{comment_html .Doc}}
 		<pre>{{node_html .Decl $.FSet}}</pre>

変更の背景

この変更は、Go言語のドキュメンテーションツールgodocの内部的な改善の一環として行われました。godocはGoのソースコードから自動的にドキュメントを生成する重要なツールであり、その出力形式はHTMLテンプレートによって定義されています。

以前のバージョンでは、テンプレート内で型名にアクセスする際に、.Type.Nameという形式でアクセスし、さらにprintf "%s"で文字列に変換したり、node_htmlというカスタム関数を使ってHTMLエスケープを行っていました。これは、テンプレートに渡されるデータ構造が、型情報を含むオブジェクトのさらにTypeフィールドの中に実際の型名が格納されている、という構造になっていたためと考えられます。

このコミットの背景には、godocが扱うデータモデルの洗練、またはテンプレートエンジンへのデータ提供方法の最適化があったと推測されます。より直接的に型名にアクセスできるようにすることで、テンプレートコードの可読性と保守性を向上させることが目的です。また、不要な中間変数（$tname）の削除は、コードの冗長性を排除し、よりクリーンな状態を保つための一般的なプラクティスです。

Go言語は当時まだ比較的新しい言語であり、ツールの改善やAPIの洗練が活発に行われていた時期です。このような変更は、言語とそのエコシステムが成熟していく過程で、より効率的で直感的な設計へと進化していることを示しています。

前提知識の解説

このコミットを理解するためには、以下の前提知識が必要です。

  1. Go言語のgodocツール:

    • godocは、Go言語のソースコードからドキュメンテーションを生成するための標準ツールです。コメントや宣言から情報を抽出し、HTML形式などで表示します。開発者がコードを理解しやすくするために非常に重要な役割を果たします。
    • godocは、Goの標準ライブラリの一部として提供されており、go docコマンドを通じて利用できます。

  2. Go言語のtext/templateまたはhtml/templateパッケージ:

    • Go言語には、テキストやHTMLを生成するためのテンプレートエンジンが標準で提供されています。godocのHTML出力もこれらのテンプレートエンジンを利用して生成されます。
    • テンプレートは、プレースホルダー（{{...}}）と制御構造（{{if ...}}, {{range ...}}など）を含むテキストファイルです。
    • データコンテキスト (.): テンプレート内で{{.}}は現在のデータコンテキスト（テンプレートに渡されたデータ構造の現在の要素）を参照します。{{.FieldName}}のように記述することで、現在のデータコンテキストのフィールドにアクセスできます。
    • 変数宣言 ($var := ...): テンプレート内で一時的な変数を宣言するために使用されます。
    • パイプライン (|): 複数の関数呼び出しを連結するために使用されます。例えば、{{.Name | html}}は、.Nameの値をhtml関数に渡し、その結果を出力します。
    • 組み込み関数: html（HTMLエスケープ）、printf（書式設定された文字列の生成）など、多くの組み込み関数が提供されています。

  3. HTMLエスケープ:

    • Webページに動的なコンテンツを表示する際、ユーザー入力やプログラムによって生成された文字列にHTML特殊文字（<, >, &, "など）が含まれていると、意図しないHTMLタグとして解釈されたり、クロスサイトスクリプティング（XSS）などのセキュリティ脆弱性を引き起こす可能性があります。
    • HTMLエスケープは、これらの特殊文字を対応するHTMLエンティティ（例: <を&lt;に）に変換することで、ブラウザがそれらを単なるテキストとして表示するようにします。htmlテンプレート関数はこの目的で使用されます。

技術的詳細

このコミットの技術的な核心は、godocのHTMLテンプレートにおけるデータアクセスパスの最適化と、それに伴う冗長な処理の削除です。

変更前は、{{range .Types}}ブロック内で、各型情報が.として利用可能になった際に、型名にアクセスするためにType.Nameというパスを辿っていました。これは、テンプレートに渡されるデータ構造が、例えば以下のようなネストされた構造を持っていたことを示唆しています。

// 変更前のテンプレートコンテキストのイメージ
type TemplateTypeInfo struct {
    Type struct {
        Name string
        // ... その他の型情報
    }
    // ...
}

この構造では、型名を取得するために{{.Type.Name}}と記述する必要がありました。さらに、この型名を文字列として確実に扱うためにprintf "%s"を使用し、HTMLエスケープのためにnode_htmlというカスタム関数（おそらくgodoc固有のヘルパー関数）を使用していたと考えられます。

変更後は、{{range .Types}}ブロック内で利用可能なデータコンテキスト（.）が、直接型名を含むNameフィールドを持つようになったことを意味します。

// 変更後のテンプレートコンテキストのイメージ
type TemplateTypeInfo struct {
    Name string // 型名が直接ここに移動
    // ... その他の型情報
}

この変更により、以下の点が改善されました。

  1. 直接的なアクセス: 型名に.Nameとして直接アクセスできるようになり、Typeという中間フィールドを介する必要がなくなりました。これにより、テンプレートコードがより直感的で読みやすくなります。
  2. 冗長な変換の削除: printf "%s"は、既に文字列であるType.Nameを再度文字列に変換する冗長な処理でした。.Nameが直接文字列として提供されるようになったことで、この変換が不要になりました。
  3. 標準的なHTMLエスケープの使用: node_htmlというカスタム関数から、Goの標準テンプレートパッケージが提供するhtml関数への移行は、より標準的で広く理解されているメカニズムを使用することを示しています。これは、godocのテンプレートがGoの標準テンプレート機能に沿って洗練されたことを意味する可能性があります。また、node_htmlが提供していた追加の機能（もしあれば）が不要になったか、別の方法で処理されるようになったことを示唆しています。
  4. 未使用変数の削除: $tname変数は、printf "%s" .Type.Nameの結果を保持していましたが、この値が後続の処理で直接使用されなくなったため、宣言自体が不要となり削除されました。これはコードのクリーンアップと最適化の一環です。

全体として、この変更はgodocの内部データ表現とテンプレートの連携がより効率的かつGoのテンプレートエンジンの慣習に沿った形に進化したことを示しています。

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

変更はlib/godoc/package.htmlファイルに集中しています。

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -20,8 +20,7 @@
 		<dd><a href="#{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
 	{{end}}
 	{{range .Types}}
-		{{$tname := printf "%s" .Type.Name}}
-		{{$tname_html := node_html .Type.Name $.FSet}}
+		{{$tname_html := html .Name}}
 		<dd><a href="#{{$tname_html}}">type {{$tname_html}}</a></dd>
 		{{range .Funcs}}
 			{{$name_html := html .Name}}
@@ -86,8 +85,8 @@
 		{{example_html .Name $.Examples $.FSet}}\n \t{{end}}\n \t{{range .Types}}
-		{{$tname := printf "%s" .Type.Name}}
-		{{$tname_html := node_html .Type.Name $.FSet}}
+		{{$tname := .Name}}
+		{{$tname_html := html .Name}}
 		<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
 		{{comment_html .Doc}}
 		<pre>{{node_html .Decl $.FSet}}</pre>

具体的には、{{range .Types}}ブロック内の2箇所で変更が行われています。

  1. 最初の{{range .Types}}ブロック内:

    • 削除: {{$tname := printf "%s" .Type.Name}}
    • 削除: {{$tname_html := node_html .Type.Name $.FSet}}
    • 追加: {{$tname_html := html .Name}}

  2. 2番目の{{range .Types}}ブロック内:

    • 削除: {{$tname := printf "%s" .Type.Name}}
    • 削除: {{$tname_html := node_html .Type.Name $.FSet}}
    • 追加: {{$tname := .Name}}
    • 追加: {{$tname_html := html .Name}}

コアとなるコードの解説

このコミットの核心は、Goのテンプレートにおけるデータバインディングと関数呼び出しの簡素化にあります。

変更前は、godocのテンプレートは、型情報を表すオブジェクトのTypeフィールドのNameフィールドにアクセスしていました（例: .Type.Name）。これは、テンプレートに渡されるデータ構造が、型名が直接ルートにない、より複雑なネスト構造を持っていたことを示唆しています。さらに、printf "%s"という関数を使って、このNameフィールドの値を明示的に文字列に変換していました。これは、Nameフィールドが文字列型ではないか、あるいはテンプレートエンジンがその型を直接文字列として扱えない場合の安全策として行われていた可能性があります。そして、node_htmlというカスタム関数がHTMLエスケープと、おそらくはgodoc特有のノード（ASTノードなど）のHTML表現への変換を行っていました。

変更後は、{{range .Types}}ループのコンテキスト（.）が、直接Nameというフィールドを持つようになりました。これにより、Typeという中間フィールドを介する必要がなくなり、{{.Name}}というより直接的なアクセスが可能になりました。

また、HTMLエスケープには、Goの標準テンプレートパッケージが提供するhtml関数が使用されるようになりました。これは、node_htmlが提供していた機能が、標準のhtml関数で十分になったか、あるいはnode_htmlが担当していた他の役割が別の場所に移管されたことを意味します。

特に2番目の変更箇所では、{{$tname := .Name}}が追加されています。これは、$tname変数が、HTMLエスケープされていない生の型名を保持するために使用されるようになったことを示しています。その直後に{{$tname_html := html .Name}}でHTMLエスケープされたバージョンが$tname_htmlに格納され、HTMLのid属性や表示テキストに使用されています。これは、生の型名とHTMLエスケープされた型名の両方がテンプレート内で必要とされるシナリオに対応するための変更です。

この変更は、godocの内部データモデルがよりフラットになり、テンプレートがより効率的かつGoのテンプレートエンジンの慣習に沿った形でデータにアクセスできるようになったことを示しています。これにより、テンプレートコードの記述が簡潔になり、保守性が向上します。

関連リンク

参考にした情報源リンク

  • Go言語の公式ドキュメンテーション
  • Go言語のtext/templateおよびhtml/templateパッケージのドキュメンテーション
  • Gitのdiff形式に関する一般的な知識
  • HTMLエスケープに関する一般的なWeb開発の知識