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

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

このコミットは、Go言語の公式ドキュメントツールであるgodocが生成するパッケージドキュメントのHTMLテンプレートファイルlib/godoc/package.htmlに対する変更です。このファイルは、Goパッケージのドキュメントページがどのように表示されるかを定義しており、パッケージの概要、インデックス、例（Examples）、サブディレクトリなどのセクションのレイアウトとコンテンツを制御しています。

コミット

このコミットは、godocが生成するパッケージドキュメントにおいて、Example（例）のリストがIndex（インデックス）セクションの前に表示されていた問題を修正します。コミットの目的は、ExampleリストをIndexセクション内に移動させることで、パッケージの内容がまだ不明な段階で例が表示されるという論理的な誤りを解消することです。

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

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

元コミット内容

commit dffdece81928103398e74d1b462bba03eb24552c
Author: Russ Cox <rsc@golang.org>
Date:   Mon Dec 10 20:20:00 2012 -0500

    godoc: move example list into index section
    
    Putting it before the Index (where it is now) is wrong:
    we don't even know what's in the package yet.
    
    Fixes #4484.
    
    R=adg, dsymonds
    CC=golang-dev
    https://golang.org/cl/6868071

変更の背景

この変更の背景には、godocが生成するドキュメントの論理的な表示順序の問題がありました。元の実装では、パッケージの「Index」（インデックス、つまりパッケージ内の関数、型、変数などの一覧）が表示される前に、「Examples」（例）のセクションが表示されていました。コミットメッセージにあるように、「Indexの前に置くのは間違っている。まだパッケージに何が含まれているかさえ分からないのだから」という理由で、この順序が不適切であると判断されました。

この問題は、GoのIssueトラッカーでIssue 4484: godoc: example list should be part of indexとして報告されていました。このIssueでは、ユーザーがパッケージのドキュメントを見たときに、まずパッケージの全体像（インデックス）を把握し、その後に具体的な使用例（Examples）を参照するのが自然な流れであると指摘されていました。このコミットは、このユーザーエクスペリエンスの改善を目的としています。

前提知識の解説

  • godoc: Go言語の公式ドキュメントツールです。Goのソースコードからコメントやシグネチャを解析し、HTML形式のドキュメントを生成します。開発者がコードを理解し、利用する上で非常に重要なツールです。
  • Goテンプレート (text/template, html/template): Go言語には、テキストやHTMLを生成するためのテンプレートエンジンが標準ライブラリとして提供されています。godocはこれらのテンプレートを使用して、Goのソースコードから抽出した情報（パッケージ名、関数、型、例など）を整形して表示します。
    • {{if .Examples}}: これはGoテンプレートの条件分岐構文です。.Examplesというデータが存在する場合（つまり、パッケージに例がある場合）に、その中のコンテンツがレンダリングされます。
    • {{range .Examples}}: これはGoテンプレートのループ構文です。.Examplesというコレクションの各要素に対して、ループ内のコンテンツが繰り返されます。
    • {{.Name}}, {{example_name .Name}}: これらはテンプレート内でデータにアクセスしたり、ヘルパー関数を呼び出したりする構文です。
  • HTML構造とナビゲーション: package.htmlはHTMLドキュメントの構造を定義しています。dl (description list), dd (description details), a (anchor link), h2 (heading) などのHTMLタグが使用され、ドキュメント内の異なるセクションへのリンク（例: #pkg-overview, #pkg-index, #pkg-examples）が作成されています。これらのリンクは、ページ内ジャンプを可能にし、ユーザーが特定のセクションに素早く移動できるようにします。
  • toggleVisible クラス: godocのドキュメントでは、一部のセクション（例: Index）がデフォルトで折りたたまれており、ユーザーがクリックすることで展開されるようになっています。これはJavaScriptとCSSによって実現されており、toggleVisible, collapsed, expanded, toggleButtonといったクラスがその挙動を制御しています。

技術的詳細

このコミットの技術的な詳細は、godocのHTMLテンプレートであるlib/godoc/package.htmlの構造変更に集約されます。具体的には、ExampleセクションのHTMLブロックが、ドキュメントのナビゲーションリンクと実際のコンテンツの両方で移動されています。

元の構造では、ナビゲーションバーにおいて「Overview」の次に「Examples」が来て、その後に「Index」が来ていました。また、実際のコンテンツブロックでも同様に、「Overview」のコンテンツの直後に「Examples」のコンテンツブロックがあり、その後に「Index」のコンテンツブロックが続いていました。

このコミットでは、以下の2つの主要な変更が行われています。

  1. ナビゲーションリンクの順序変更:

    • Overview (#pkg-overview)
    • Index (#pkg-index)
    • Examples (#pkg-examples) (条件付きで表示) この順序に変更されました。これにより、ユーザーはまずパッケージの概要とインデックスを確認し、その後に例を参照するという自然な流れになります。

  2. コンテンツブロックの移動:

    • 以前は、example_htmlの呼び出しと、id="pkg-examples"を持つdivブロックが、id="pkg-index"を持つdivブロックの前にありました。
    • 変更後、id="pkg-examples"を持つdivブロック全体が、id="pkg-index"を持つdivブロックの内部、具体的にはid="manual-nav"のdivの直後に移動されました。これにより、ExamplesセクションはIndexセクションの一部として論理的に配置されます。

この変更は、単にHTML要素の表示順序を入れ替えるだけでなく、godocが生成するドキュメントの論理的な構造とユーザーエクスペリエンスを改善することを目的としています。パッケージの全体像を把握するためのインデックスが先に提示され、その後に具体的な使用例が続くことで、ドキュメントの可読性と理解度が向上します。

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

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -17,10 +17,10 @@
 			</dl>
 			<dl>
 			<dd><a href="#pkg-overview" class="overviewLink">Overview</a></dd>
+\t\t\t<dd><a href="#pkg-index" class="indexLink">Index</a></dd>
 			{{if $.Examples}}\n \t\t\t\t<dd><a href="#pkg-examples" class="examplesLink">Examples</a></dd>\n \t\t\t{{end}}\n-\t\t\t<dd><a href="#pkg-index" class="indexLink">Index</a></dd>\n \t\t\t{{if $.Dirs}}\n \t\t\t\t<dd><a href="#pkg-subdirectories">Subdirectories</a></dd>\n \t\t\t{{end}}\
@@ -38,22 +38,6 @@
 \t\t</div>\n \t\t{{example_html "" $.Examples $.FSet}}\n \n-\t\t{{if $.Examples}}\n-\t\t<div id=\"pkg-examples\" class=\"toggleVisible\">\n-\t\t\t<div class=\"collapsed\">\n-\t\t\t\t<h2 class=\"toggleButton\" title=\"Click to show Examples section\">Examples ▹</h2>\n-\t\t\t</div>\n-\t\t\t<div class=\"expanded\">\n-\t\t\t\t<h2 class=\"toggleButton\" title=\"Click to hide Examples section\">Examples ▾</h2>\n-\t\t\t\t<dl>\n-\t\t\t\t{{range $.Examples}}\n-\t\t\t\t<dd><a class=\"exampleLink\" href=\"#example_{{.Name}}\">{{example_name .Name}}</a></dd>\n-\t\t\t\t{{end}}\n-\t\t\t\t</dl>\n-\t\t\t</div>\n-\t\t</div>\n-\t\t{{end}}\n-\t
 \t\t<div id=\"pkg-index\" class=\"toggleVisible\">\n \t\t<div class=\"collapsed\">\n \t\t\t<h2 class=\"toggleButton\" title=\"Click to show Index section\">Index ▹</h2>\
@@ -92,6 +76,17 @@
 \t\t\t</dl>\n \t\t\t</div><!-- #manual-nav -->\n \n+\t\t{{if $.Examples}}\n+\t\t<div id=\"pkg-examples\">\n+\t\t\t<h4>Examples</h4>\n+\t\t\t<dl>\n+\t\t\t{{range $.Examples}}\n+\t\t\t<dd><a class=\"exampleLink\" href=\"#example_{{.Name}}\">{{example_name .Name}}</a></dd>\n+\t\t\t{{end}}\n+\t\t\t</dl>\n+\t\t</div>\n+\t\t{{end}}\
+\t
 \t\t{{with .Filenames}}\n \t\t\t<h4>Package files</h4>\n \t\t\t<p>\

コアとなるコードの解説

このdiffは、lib/godoc/package.htmlテンプレートファイルにおけるExampleセクションの移動を示しています。

変更点1: ナビゲーションリンクの順序変更

@@ -17,10 +17,10 @@
 			</dl>
 			<dl>
 			<dd><a href="#pkg-overview" class="overviewLink">Overview</a></dd>
+\t\t\t<dd><a href="#pkg-index" class="indexLink">Index</a></dd>
 			{{if $.Examples}}\n \t\t\t\t<dd><a href="#pkg-examples" class="examplesLink">Examples</a></dd>\n \t\t\t{{end}}\
-\t\t\t<dd><a href="#pkg-index" class="indexLink">Index</a></dd>\
 \t\t\t{{if $.Dirs}}\n \t\t\t\t<dd><a href="#pkg-subdirectories">Subdirectories</a></dd>\
 \t\t\t{{end}}\
  • - <dd><a href="#pkg-index" class="indexLink">Index</a></dd>: 元々Examplesリンクの後にあったIndexリンクが削除されています。
  • + <dd><a href="#pkg-index" class="indexLink">Index</a></dd>: Overviewリンクの直後にIndexリンクが追加されています。

これにより、左側のナビゲーションバーにおけるリンクの表示順序が「Overview」→「Index」→「Examples」（存在する場合）に変更され、より論理的な順序になりました。

変更点2: Examplesコンテンツブロックの移動

@@ -38,22 +38,6 @@
 \t\t</div>\n \t\t{{example_html "" $.Examples $.FSet}}\n \n-\t\t{{if $.Examples}}\n-\t\t<div id=\"pkg-examples\" class=\"toggleVisible\">\n-\t\t\t<div class=\"collapsed\">\n-\t\t\t\t<h2 class=\"toggleButton\" title=\"Click to show Examples section\">Examples ▹</h2>\n-\t\t\t</div>\n-\t\t\t<div class=\"expanded\">\n-\t\t\t\t<h2 class=\"toggleButton\" title=\"Click to hide Examples section\">Examples ▾</h2>\n-\t\t\t\t<dl>\n-\t\t\t\t{{range $.Examples}}\n-\t\t\t\t<dd><a class=\"exampleLink\" href=\"#example_{{.Name}}\">{{example_name .Name}}</a></dd>\n-\t\t\t\t{{end}}\n-\t\t\t\t</dl>\n-\t\t\t</div>\n-\t\t</div>\n-\t\t{{end}}\
-\t
 \t\t<div id=\"pkg-index\" class=\"toggleVisible\">\n \t\t<div class=\"collapsed\">\n \t\t\t<h2 class=\"toggleButton\" title=\"Click to show Index section\">Index ▹</h2>\
@@ -92,6 +76,17 @@
 \t\t\t</dl>\n \t\t\t</div><!-- #manual-nav -->\n \n+\t\t{{if $.Examples}}\n+\t\t<div id=\"pkg-examples\">\n+\t\t\t<h4>Examples</h4>\n+\t\t\t<dl>\n+\t\t\t{{range $.Examples}}\n+\t\t\t<dd><a class=\"exampleLink\" href=\"#example_{{.Name}}\">{{example_name .Name}}</a></dd>\n+\t\t\t{{end}}\n+\t\t\t</dl>\n+\t\t</div>\n+\t\t{{end}}\
+\t
 \t\t{{with .Filenames}}\n \t\t\t<h4>Package files</h4>\n \t\t\t<p>\
  • -で始まる行群は、元のid="pkg-examples"を持つdivブロック（Examplesセクション全体）が削除されたことを示しています。このブロックには、折りたたみ/展開機能（toggleVisibleクラス）と、各例へのリンクが含まれていました。
  • +で始まる行群は、新しいid="pkg-examples"を持つdivブロックが追加されたことを示しています。この新しいブロックは、id="pkg-index"を持つdivブロックの内部、具体的には<!-- #manual-nav -->コメントの直後に配置されています。
  • 注目すべきは、新しいExamplesセクションではtoggleVisibleクラスが削除され、デフォルトで展開された状態になっている点です。これは、Indexセクション内に配置されたことで、ExamplesがIndexの一部として常に表示されるようになったため、個別の折りたたみ機能が不要になったことを示唆しています。

これらの変更により、godocが生成するパッケージドキュメントは、ユーザーが情報をより効率的かつ直感的に見つけられるように改善されました。

関連リンク

参考にした情報源リンク