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

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

このコミットは、Go言語の公式ドキュメント生成ツールである godoc の表示に関する改善です。具体的には、godoc が生成するパッケージドキュメントのHTMLページにおいて、「Examples（例）」セクションと「Index（インデックス）」セクションの表示順序を変更し、さらに両セクションを折りたたみ可能（collapsable）にする機能を追加しています。これにより、ユーザーはドキュメントの閲覧時に必要な情報に素早くアクセスし、不要なセクションを非表示にすることで、より整理されたビューを得られるようになります。

コミット

commit 516306f67781279e175fe0697446ba087b8ac793
Author: Andrew Gerrand <adg@golang.org>
Date:   Wed Oct 3 15:05:08 2012 +1000

    godoc: move Examples above Index and make them both collapsable
    
    R=golang-dev, dsymonds, bradfitz, r
    CC=golang-dev
    https://golang.org/cl/6591066

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

https://github.com/golang/go/commit/516306f67781279e175fe0697446ba087b8ac793

元コミット内容

このコミットの目的は、godoc が生成するHTMLドキュメントのユーザビリティを向上させることです。具体的には、以下の2つの変更が行われています。

  1. Examplesセクションの移動: これまで「Index」セクションの下に配置されていた「Examples」セクションを、「Index」セクションの上に移動させます。
  2. 折りたたみ機能の追加: 「Examples」セクションと「Index」セクションの両方に、クリックで内容の表示/非表示を切り替えられる折りたたみ機能（collapsable）を追加します。

これにより、ユーザーはより直感的にドキュメントを操作し、必要な情報に集中できるようになります。

変更の背景

godoc はGo言語のコードから自動的にドキュメントを生成する非常に強力なツールです。生成されるドキュメントは、Goのパッケージや関数の使い方を理解する上で不可欠な情報源となります。しかし、ドキュメントが長くなると、特定の情報を見つけるのが困難になることがあります。

このコミットが行われた2012年当時、Go言語はまだ比較的新しい言語であり、ドキュメンテーションツールの改善は活発に行われていました。ユーザーエクスペリエンスの向上は、言語の普及と開発者の生産性向上に直結します。

「Examples」は、コードの具体的な使用例を示すため、非常に重要なセクションです。これが「Index」の下にあると、ユーザーがExamplesを探す際にスクロールが必要になる場合があります。Examplesをより目立つ位置に移動させることで、ユーザーがパッケージの利用方法を素早く把握できるようになります。

また、ドキュメントの「Index」や「Examples」セクションは、内容が多い場合に画面を占有し、他の重要な情報（例えば、関数の詳細な説明）が視界から隠れてしまうことがあります。これらのセクションを折りたたみ可能にすることで、ユーザーは必要に応じて詳細を表示し、不要な場合は非表示にすることで、画面のスペースを有効活用し、よりクリーンなビューでドキュメントを閲覧できるようになります。これは、特に小さな画面のデバイスや、一度に多くの情報を参照したい場合に有効な改善です。

前提知識の解説

godoc

godoc はGo言語に標準で付属するドキュメンテーションツールです。Goのソースコード（.go ファイル）内のコメントや関数・型定義を解析し、自動的にHTML形式のドキュメントを生成します。このドキュメントは、Goの標準ライブラリのドキュメント（pkg.go.devなど）の基盤となっています。godoc は、コードとドキュメントを密接に連携させる「ドキュメント・ドリブン開発」の哲学を体現しています。

HTMLテンプレート

godoc は、Goの html/template パッケージを使用してドキュメントのHTMLを生成します。package.html は、個々のGoパッケージのドキュメントページをレンダリングするためのテンプレートファイルです。このファイルには、Goのテンプレート構文（{{.FieldName}}, {{range .Slice}}, {{if .Condition}} など）が埋め込まれており、godoc が解析したGoコードの構造体（Package、Func、Type など）のデータがテンプレートに渡され、最終的なHTMLが出力されます。

折りたたみ可能なUI要素 (Collapsible UI Elements)

ウェブページでコンテンツを折りたたんだり展開したりする機能は、一般的にJavaScriptとCSSを組み合わせて実装されます。

  • HTML構造: 通常、表示/非表示を切り替えるトリガー（例: <h2> タグ）と、そのトリガーによって表示/非表示が制御されるコンテンツブロック（例: <div> タグ）で構成されます。
  • CSS: コンテンツブロックの初期状態（非表示）や、表示/非表示時のアニメーションなどを定義します。display: none; や max-height: 0; overflow: hidden; などが使われます。
  • JavaScript: トリガーがクリックされたときに、コンテンツブロックのCSSクラスを変更したり、スタイルを直接操作したりして、表示/非表示を切り替えます。このコミットでは、toggleVisible、collapsed、expanded、toggleButton といったクラス名が使われており、これらがJavaScriptによって動的に操作されることで、折りたたみ機能が実現されていると推測されます。

技術的詳細

このコミットは、lib/godoc/package.html という単一のHTMLテンプレートファイルを変更しています。

Examplesセクションの移動と構造変更

変更前は、ExamplesセクションはIndexセクションの後に、シンプルな <h4> と dl リストとして存在していました。

変更後は、Examplesセクションが {{example_html "" $.Examples $.FSet}} の直後、かつ Index セクションの前に移動しています。 さらに、Examplesセクション全体が新しいHTML構造でラップされています。

{{if $.Examples}}
<div id="pkg-examples" class="toggleVisible">
    <div class="collapsed">
        <h2 class="toggleButton" title="Click to show Examples section">Examples ▹</h2>
    </div>
    <div class="expanded">
        <h2 class="toggleButton" title="Click to hide Examples section">Examples ▾</h2>
        <dl>
        {{range $.Examples}}
        <dd><a class="exampleLink" href="#example_{{.Name}}">{{example_name .Name}}</a></dd>
        {{end}}
        </dl>
    </div>
</div>
{{end}}
  • id="pkg-examples": セクションを一意に識別するためのID。
  • class="toggleVisible": このクラスが、JavaScriptによって折りたたみ機能が適用されるコンテナであることを示唆しています。
  • collapsed と expanded クラスを持つ div 要素: これらは、セクションが折りたたまれている状態と展開されている状態のコンテンツをそれぞれ含みます。
  • toggleButton クラスを持つ h2 要素: これがクリック可能なトリガーとなり、セクションの表示/非表示を切り替えます。タイトル属性 (title) は、マウスオーバー時にヒントを提供します。
  • ▹ (U+25B8, BLACK RIGHT-POINTING SMALL TRIANGLE) と ▾ (U+25BE, BLACK DOWN-POINTING SMALL TRIANGLE) の記号: これらは、セクションが折りたたまれているか展開されているかを示す視覚的なインジケータとして機能します。

Indexセクションの構造変更

Indexセクションも同様に、折りたたみ機能が追加されています。

変更前は、h2 タグの後に直接 div id="manual-nav" が続いていました。

変更後は、Indexセクション全体が toggleVisible クラスを持つ div でラップされ、その中に collapsed と expanded の状態に応じた div が配置されています。

<div id="pkg-index" class="toggleVisible">
<div class="collapsed">
    <h2 class="toggleButton" title="Click to show Index section">Index ▹</h2>
</div>
<div class="expanded">
    <h2 class="toggleButton" title="Click to hide Index section">Index ▾</h2>

    <!-- Table of contents for API; must be named manual-nav to turn off auto nav. -->
    <div id="manual-nav">
    <dl>
    {{if .Consts}}
        <dd><a href="#pkg-constants">Constants</a></dd>
    ... (中略) ...
    </dl>
    </div><!-- #manual-nav -->
</div><!-- .expanded -->
</div><!-- #pkg-index -->
  • id="pkg-index": IndexセクションのコンテナID。
  • toggleVisible, collapsed, expanded, toggleButton クラス: Examplesセクションと同様に、折りたたみ機能を実現するための構造とクラスが適用されています。

これらの変更は、HTML構造とCSSクラスの追加に限定されており、JavaScriptコード自体はこのコミットに含まれていません。これは、godoc のフロントエンドロジックが別の場所（おそらく godoc のJavaScriptファイル）でこれらのクラスを認識し、動的に動作を付与していることを示唆しています。

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

変更は lib/godoc/package.html ファイルのみです。

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -37,10 +37,32 @@
  			</div>
  		</div>
  		{{example_html "" $.Examples $.FSet}}
+
+		{{if $.Examples}}
+		<div id="pkg-examples" class="toggleVisible">
+			<div class="collapsed">
+				<h2 class="toggleButton" title="Click to show Examples section">Examples ▹</h2>
+			</div>
+			<div class="expanded">
+				<h2 class="toggleButton" title="Click to hide Examples section">Examples ▾</h2>
+				<dl>
+				{{range $.Examples}}
+				<dd><a class="exampleLink" href="#example_{{.Name}}">{{example_name .Name}}</a></dd>
+				{{end}}
+				</dl>
+			</div>
+		</div>
+		{{end}}
  	
-		<h2 id=\"pkg-index\">Index</h2>
+		<div id=\"pkg-index\" class=\"toggleVisible\">
+		<div class=\"collapsed\">
+			<h2 class=\"toggleButton\" title=\"Click to show Index section\">Index ▹</h2>
+		</div>
+		<div class=\"expanded\">
+			<h2 class=\"toggleButton\" title=\"Click to hide Index section\">Index ▾</h2>
+
  		<!-- Table of contents for API; must be named manual-nav to turn off auto nav. -->
-		<div id=\"manual-nav\">\
+			<div id=\"manual-nav\">\
  			<dl>
  			{{if .Consts}}
  				<dd><a href=\"#pkg-constants\">Constants</a></dd>
@@ -67,16 +89,8 @@
  			{{if .Bugs}}
  				<dd><a href=\"#pkg-bugs\">Bugs</a></dd>
  			{{end}}\
-		</dl>
-\
-		{{if $.Examples}}
-			<h4 id=\"pkg-examples\">Examples</h4>
-			<dl>
-			{{range $.Examples}}
-			<dd><a class=\"exampleLink\" href=\"#example_{{.Name}}\">{{example_name .Name}}</a></dd>
-			{{end}}
  			</dl>\
-		{{end}}\
+			</div><!-- #manual-nav -->\
  
  		{{with .Filenames}}
  			<h4>Package files</h4>
@@ -88,6 +102,8 @@
  			</span>
  			</p>
  		{{end}}
+		</div><!-- .expanded -->
+		</div><!-- #pkg-index -->
  	
  		{{with .Consts}}
  			<h2 id=\"pkg-constants\">Constants</h2>

コアとなるコードの解説

この変更は、package.html テンプレートのHTML構造を再編成することで、godoc が生成するドキュメントのレイアウトとインタラクティブ性を向上させています。

  1. Examplesセクションの移動:

    • 元のExamplesセクションのHTMLブロック（{{if $.Examples}}...{{end}}）が、ファイルの後半（Indexセクションの後）から削除されています。
    • 同じ内容のExamplesセクションが、{{example_html "" $.Examples $.FSet}} の直後、かつIndexセクションの前に挿入されています。これにより、ExamplesがIndexよりも視覚的に上位に表示されるようになります。

  2. 折りたたみ機能の追加:

    • Examplesセクション: 新しいExamplesセクションは、id="pkg-examples" と class="toggleVisible" を持つ div で囲まれています。この div の中に、collapsed と expanded という2つの div が含まれています。
      • collapsed div は、セクションが折りたたまれているときに表示される内容（「Examples ▹」という見出し）を含みます。
      • expanded div は、セクションが展開されているときに表示される内容（「Examples ▾」という見出しと、実際のExamplesリスト）を含みます。
      • h2 タグには class="toggleButton" が付与されており、これがクリックイベントのトリガーとして機能します。
    • Indexセクション: 同様に、既存のIndexセクションの h2 タグと div id="manual-nav" の全体が、id="pkg-index" と class="toggleVisible" を持つ div でラップされています。この div の中にも、collapsed と expanded の状態に応じた div が配置され、それぞれに toggleButton クラスを持つ h2 が含まれています。

これらの変更により、godoc が生成するHTMLは、JavaScriptがこれらのクラスを検出してクリックイベントリスナーをアタッチし、collapsed と expanded の表示を切り替えることで、動的な折りたたみ/展開機能を提供できるようになります。ユーザーは、ドキュメントの目次や例を必要に応じて表示・非表示にすることで、より効率的に情報を参照できるようになります。

関連リンク

参考にした情報源リンク

  • GitHubのコミットページ: https://github.com/golang/go/commit/516306f67781279e175fe0697446ba087b8ac793
  • Go CL 6591066 (Gerrit): https://golang.org/cl/6591066 (このリンクは古いGerritインスタンスのものであり、現在はアクセスできない可能性がありますが、コミットメッセージに記載されているため参考として記載します。)
  • 一般的なHTML/CSS/JavaScriptによる折りたたみUIの実装パターンに関する知識。
  • Go言語のドキュメンテーションに関する一般的な知識。