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

このコミットは、Go言語の公式ドキュメントツールであるgodocのフロントエンドにおけるUI/UXの改善を目的としています。具体的には、ドキュメントページのセクション表示順序を修正し、「Examples（例）」や「Index（インデックス）」といったセクションがクリックによって展開・折りたたみ可能になる機能を追加しています。

コミット

commit e7f453148c22789660ad064107ffa7e2541ae740
Author: Andrew Gerrand <adg@golang.org>
Date:   Thu Oct 4 11:21:37 2012 +1000

    godoc: show contents in correct order, expand sections on click
    
    R=dsymonds
    CC=gobot, golang-dev
    https://golang.org/cl/6588079

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

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

元コミット内容

godoc: show contents in correct order, expand sections on click

R=dsymonds
CC=gobot, golang-dev
https://golang.org/cl/6588079

変更の背景

godocはGo言語のソースコードからドキュメントを自動生成し、Webブラウザで閲覧可能にするツールです。このコミットが行われた2012年当時、godocが生成するHTMLドキュメントのナビゲーション部分には、いくつかのユーザビリティ上の課題がありました。

1. セクションの表示順序: ドキュメントの目次部分において、「Index（インデックス）」セクションが「Examples（例）」セクションよりも前に表示されることがありました。しかし、一般的にユーザーはコードの概要（Overview）を読んだ後、具体的な使用例（Examples）を確認し、最後に詳細なインデックスを参照することが多いため、この順序は直感的ではありませんでした。
2. セクションの展開/折りたたみ機能の欠如: godocのドキュメントページでは、一部のセクション（例: Overview）は既にクリックで展開・折りたたみ可能でしたが、「Examples」や「Index」といった重要なセクションにはこの機能がありませんでした。これにより、ページが長くなりすぎたり、ユーザーが目的の情報を素早く見つけにくかったりする問題がありました。

このコミットは、これらのユーザビリティ上の問題を解決し、godocが生成するドキュメントの閲覧体験を向上させることを目的としています。

前提知識の解説

• godoc: Go言語のソースコードからドキュメントを生成し、HTTPサーバーとして提供するツールです。Goのパッケージや型の定義、関数、メソッド、変数、定数、そしてコメントから自動的にドキュメントを生成します。
• HTMLテンプレート (package.html): godocはGoのhtml/templateパッケージを使用してHTMLドキュメントを生成します。package.htmlは、個々のGoパッケージのドキュメントページをレンダリングするためのテンプレートファイルです。このファイルには、ナビゲーションリンクやセクションの構造が定義されています。
• JavaScript (godocs.js): godocのフロントエンドには、動的なUI要素を制御するためのJavaScriptファイルが含まれています。このファイルは、セクションの展開・折りたたみ機能などを担当しています。
• godocs_bindToggleLinks関数: godocs.js内に存在するJavaScript関数で、特定のHTML要素（通常はリンク）にクリックイベントリスナーをバインドし、関連するセクションの表示/非表示を切り替える機能を提供します。この関数は、リンクのclass属性と、対象となるセクションのid属性に基づいて動作します。

技術的詳細

このコミットは、主に以下の2つのファイルに対する変更を通じて、前述の課題を解決しています。

1. lib/godoc/package.htmlの変更:

   • セクション順序の修正: ナビゲーションリスト（<dl>要素内）において、「Index」へのリンクが「Examples」へのリンク（{{if $.Examples}}...{{end}}ブロック内）の後に来るように順序が変更されました。これにより、ユーザーが期待する情報フローに沿った自然な目次順序が実現されます。
   • CSSクラスの追加: 「Examples」へのリンクにはexamplesLinkクラスが、そして「Index」へのリンクにはindexLinkクラスがそれぞれ追加されました。これらのクラスは、JavaScript側でクリックイベントをバインドするためのセレクタとして機能します。

2. doc/godocs.jsの変更:

   • イベントバインディングの追加: godocs_onload関数（ページロード時に実行される関数）内に、新しく追加されたexamplesLinkとindexLinkクラスに対してgodocs_bindToggleLinks関数を呼び出すコードが追加されました。これにより、これらのリンクがクリックされた際に、対応するセクションが展開・折りたたみされるようになります。
     • godocs_bindToggleLinks("examplesLink", "");
     • godocs_bindToggleLinks("indexLink", ""); godocs_bindToggleLinksの第二引数が空文字列であることから、対応するセクションのIDはリンクのクラス名（examplesLinkやindexLink）と直接関連付けられているか、または特定の命名規則に従って自動的に解決されることを示唆しています。

これらの変更により、godocが生成するドキュメントは、より整理されたナビゲーションと、ユーザーがコンテンツをより効率的に探索できるインタラクティブな機能を持つようになりました。

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

doc/godocs.js

--- a/doc/godocs.js
+++ b/doc/godocs.js
@@ -208,6 +208,8 @@ function godocs_onload() {
   godocs_bindToggles("toggleVisible");
   godocs_bindToggleLinks("exampleLink", "example_");
   godocs_bindToggleLinks("overviewLink", "");
+  godocs_bindToggleLinks("examplesLink", "");
+  godocs_bindToggleLinks("indexLink", "");
 }

 bindEvent(window, 'load', godocs_onload);

lib/godoc/package.html

--- 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\">Index</a></dd>
 \t\t\t{{if $.Examples}}\n-\t\t\t\t<dd><a href=\"#pkg-examples\">Examples</a></dd>\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}}\

コアとなるコードの解説

doc/godocs.jsの変更

godocs_onload関数は、ウェブページが完全にロードされた後に実行される初期化関数です。この関数内で、既存のgodocs_bindTogglesやgodocs_bindToggleLinksの呼び出しに加えて、以下の2行が追加されました。

• godocs_bindToggleLinks("examplesLink", "");
• godocs_bindToggleLinks("indexLink", "");

これは、HTMLテンプレートで新しく追加されたexamplesLinkとindexLinkというCSSクラスを持つ<a>タグ（アンカー要素）に対して、クリックイベントリスナーをバインドすることを意味します。これにより、これらのリンクがクリックされると、対応するセクション（通常はidがpkg-examplesやpkg-indexの要素）の表示/非表示が切り替わるようになります。第二引数の空文字列は、リンクのhref属性が直接ターゲットのIDを示しているか、または特定の命名規則に基づいてIDが解決されることを示唆しています。

lib/godoc/package.htmlの変更

このファイルは、Goパッケージのドキュメントページを生成するためのHTMLテンプレートです。変更は、ナビゲーションセクション（<dl>リスト）に集中しています。

1. 順序の変更: 元のコードでは「Index」リンクが「Examples」ブロックの前にありました。

   <dd><a href="#pkg-overview" class="overviewLink">Overview</a></dd>
   <dd><a href="#pkg-index">Index</a></dd>
   {{if $.Examples}}
       <dd><a href="#pkg-examples">Examples</a></dd>
   {{end}}
   

   変更後、{{if $.Examples}}...{{end}}ブロック全体が「Index」リンクの前に移動しました。

   <dd><a href="#pkg-overview" class="overviewLink">Overview</a></dd>
   {{if $.Examples}}
       <dd><a href="#pkg-examples" class="examplesLink">Examples</a></dd>
   {{end}}
   <dd><a href="#pkg-index" class="indexLink">Index</a></dd>
   

   これにより、ナビゲーションの順序が「Overview」→「Examples」（存在する場合）→「Index」となり、より論理的でユーザーフレンドリーな表示順序が実現されました。

2. CSSクラスの追加:

   • {{if $.Examples}}ブロック内の「Examples」リンクにclass="examplesLink"が追加されました。
   • 「Index」リンクにclass="indexLink"が追加されました。

これらのクラスは、godocs.jsで追加されたgodocs_bindToggleLinks関数が正しく機能するために不可欠です。JavaScriptはこれらのクラス名を使用して、どのリンクにイベントリスナーをアタッチすべきかを識別します。

関連リンク

• Go言語公式ドキュメント: https://golang.org/doc/
• godocコマンドのドキュメント: https://pkg.go.dev/cmd/godoc (現在のgodocのドキュメント)
• Goのコードレビューシステム (Gerrit): https://go-review.googlesource.com/ (コミットメッセージにあるgolang.org/cl/6588079はGerritの変更リストへのリンクです)

参考にした情報源リンク

• Go言語のソースコード (GitHub): https://github.com/golang/go
• Goのhtml/templateパッケージ: https://pkg.go.dev/html/template
• JavaScriptのイベントリスナーに関する一般的な情報 (MDN Web Docsなど)
• CSSクラスとHTML構造に関する一般的な情報 (MDN Web Docsなど)