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

このコミットは、Go言語のドキュメンテーションツールであるgodocの表示機能に関する改善です。具体的には、パッケージの概要（Overview）セクションを折りたたみ可能（collapsible）にすることで、特に長いパッケージコメントを持つ場合のドキュメントの閲覧性を向上させています。この変更は、既存のコード例（Examples）の折りたたみ機能の汎用化と、その新しい汎用メカニズムをOverviewセクションに適用することによって実現されています。

コミット

commit 0b762d9523a8b672143556739726d3d4e8ac6c94
Author: Andrew Gerrand <adg@golang.org>
Date:   Mon Mar 26 14:10:27 2012 +1100

    godoc: make 'Overview' section collapsable
    
    This makes packages with lengthly package comments easier to browse.
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/5901055

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

https://github.com/golang/go/commit/0b762d9523a8b672143556739726d3d4e8ac6c94

元コミット内容

godoc: make 'Overview' section collapsable

This makes packages with lengthly package comments easier to browse.

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5901055

変更の背景

godocで生成されるドキュメントにおいて、パッケージの概要（Overview）セクションに非常に長いコメントが含まれる場合、ユーザーがドキュメント全体をスクロールして閲覧する際に不便が生じていました。このコミットの目的は、Overviewセクションを折りたたみ可能にすることで、ユーザーがドキュメントの他の部分に素早くアクセスできるようにし、全体的な閲覧体験を向上させることです。これにより、特に詳細な説明が記述されたパッケージにおいて、ドキュメントの可読性とナビゲーションが改善されます。

前提知識の解説

この変更を理解するためには、以下の技術要素と概念に関する基本的な知識が必要です。

• godoc: Go言語のソースコードからドキュメンテーションを生成するツールです。Goのパッケージ、関数、型などに記述されたコメントを解析し、HTML形式のドキュメントとして表示します。開発者がコードとドキュメントを同時に管理できる「ドキュメント駆動開発」を促進します。
• HTML (HyperText Markup Language): ウェブページの構造を定義するためのマークアップ言語です。div（汎用的なコンテナ）、h2（セクションの見出し）、p（段落）、a（ハイパーリンク）などの要素が使用されます。
• CSS (Cascading Style Sheets): HTML要素の見た目（スタイル）を定義するためのスタイルシート言語です。classセレクタを用いて特定の要素グループにスタイルを適用したり、displayプロパティで要素の表示/非表示を制御したりします。
• JavaScript: ウェブページに動的な振る舞いを追加するためのプログラミング言語です。DOM (Document Object Model) を操作してHTML要素の内容やスタイルを変更したり、イベントリスナー（例: clickイベント）を設定してユーザーの操作に応答したりします。
• DOM (Document Object Model): HTMLやXMLドキュメントの構造を、プログラムからアクセス・操作できるようにするためのAPIです。JavaScriptはDOMを通じてウェブページの要素にアクセスし、そのプロパティ（例: className）を変更することで、動的なUIを実現します。
• 折りたたみ可能なセクション (Collapsible Sections): ウェブUIにおける一般的なデザインパターンの一つで、コンテンツの一部を初期状態で非表示にし、ユーザーがクリックなどの操作を行うことで表示/非表示を切り替えられるようにする機能です。これにより、ページの初期表示を簡潔にし、ユーザーが必要な情報に集中できるようにします。通常、JavaScriptで要素のクラスを変更し、CSSでそのクラスに応じた表示/非表示のスタイルを適用することで実現されます。

技術的詳細

このコミットの技術的な核心は、既存のコード例（Examples）の折りたたみ機能を汎用化し、それをパッケージの概要（Overview）セクションにも適用した点にあります。

1. 汎用的なトグルメカニズムへのリファクタリング:

   • これまでexampleという特定のクラス名に依存していたJavaScript関数（godocs_bindExampleToggle, godocs_bindExampleLink）が、より汎用的なtoggleという概念に基づく関数（godocs_bindToggle, godocs_bindToggleLink）にリファクタリングされました。
   • これに伴い、CSSのクラス名も.example、.exampleVisible、.exampleHeadingなどが、それぞれ.toggle、.toggleVisible、.toggleButtonといった汎用的な名前に変更されました。これにより、同じJavaScriptとCSSのロジックを異なる種類の折りたたみ可能な要素に再利用できるようになります。
   • 新しいヘルパー関数godocs_bindTogglesとgodocs_bindToggleLinksが導入され、特定のクラス名を持つすべての要素に対して一括でトグル機能をバインドできるようになりました。

2. Overviewセクションへの適用:

   • lib/godoc/package.htmlにおいて、OverviewセクションのHTML構造が大幅に変更されました。従来のシンプルな<h2>タグとコメント表示部分が、toggleVisibleクラスを持つ<div>要素でラップされました。
   • この<div>内部には、collapsed（折りたたまれた状態）とexpanded（展開された状態）の2つの<div>が用意され、それぞれにtoggleButtonクラスを持つ<h2>見出しが配置されました。これにより、ユーザーがクリックする見出し（トグルボタン）と、そのクリックによって表示/非表示が切り替わるコンテンツが明確に分離されます。
   • 初期状態ではtoggleVisibleクラスが適用されているため、Overviewセクションは展開された状態で表示されます。ユーザーがtoggleButtonをクリックすると、JavaScriptが親要素のクラスをtoggleVisibleからtoggleに切り替えることで、CSSのルールに基づいてcollapsedの内容が表示され、expandedの内容が非表示になります。
   • ナビゲーション内の「Overview」リンクにはoverviewLinkという新しいクラスが追加され、JavaScriptがこのリンクをクリックした際に、対応するOverviewセクションを強制的に展開する（toggleVisibleクラスを適用する）ように設定されました。

この一連の変更により、godocはより柔軟なUIコンポーネントを持つようになり、将来的に他のセクションにも同様の折りたたみ機能を容易に適用できる基盤が構築されました。

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

このコミットでは、以下の4つのファイルが変更されています。

1. doc/godocs.js:

   • JavaScriptのトグル関連関数が汎用化され、godocs_bindExampleToggleがgodocs_bindToggleに、godocs_bindExampleLinkがgodocs_bindToggleLinkにリファクタリングされました。
   • 新しいヘルパー関数godocs_bindTogglesとgodocs_bindToggleLinksが追加されました。
   • godocs_onload関数が更新され、これらの新しい汎用関数を使用してExamplesとOverviewセクションのトグル機能を初期化するようになりました。

2. doc/style.css:

   • CSSのクラス名が、exampleプレフィックスからtoggleプレフィックスへと汎用化されました。これにより、JavaScriptの変更と連携して、折りたたみ可能な要素のスタイルを統一的に管理できるようになりました。

3. lib/godoc/example.html:

   • コード例のラッパーdivのクラスがexampleからtoggleに変更されました。
   • コード例の見出しpタグにtoggleButtonクラスが追加されました。これにより、コード例も新しい汎用トグルメカニズムの恩恵を受けるようになりました。

4. lib/godoc/package.html:

   • パッケージの概要（Overview）セクションのHTML構造が大幅に変更されました。
   • Overviewセクション全体がtoggleVisibleクラスを持つdivでラップされ、その内部にcollapsedとexpandedのdivが配置されました。
   • 各状態の見出しにtoggleButtonクラスが適用され、クリック可能なトグルボタンとして機能するようになりました。
   • ナビゲーション内の「Overview」リンクにoverviewLinkクラスが追加され、このリンクからの遷移時にOverviewセクションが展開されるようにJavaScriptと連携します。

コアとなるコードの解説

doc/godocs.js

// godocs_bindExampleToggle から godocs_bindToggle へ汎用化
function godocs_bindToggle(el) {
  var button = getElementsByClassName(el, "toggleButton"); // クリック可能なボタン要素を取得
  var callback = function() {
    if (el.className == "toggle") { // 現在折りたたまれている場合
      el.className = "toggleVisible"; // 展開状態にする
    } else { // 現在展開されている場合
      el.className = "toggle"; // 折りたたみ状態にする
    }
  };
  for (var i = 0; i < button.length; i++) {
    bindEvent(button[i], "click", callback); // ボタンにクリックイベントをバインド
  }
}

// godocs_bindExampleLink から godocs_bindToggleLink へ汎用化
function godocs_bindToggleLink(l, prefix) {
  bindEvent(l, "click", function() {
    var i = l.href.indexOf("#"+prefix);
    if (i < 0) {
      return;
    }
    var id = prefix + l.href.slice(i+1+prefix.length);
    var eg = document.getElementById(id);
    eg.className = "toggleVisible"; // リンククリックで対象要素を展開状態にする
  });
}

// 特定のクラス名を持つ全ての要素にトグル機能をバインド
function godocs_bindToggles(className) {
  var els = getElementsByClassName(document, className);
  for (var i = 0; i < els.length; i++) {
    godocs_bindToggle(els[i]);
  }
}

// 特定のクラス名を持つ全てのリンクにトグルリンク機能をバインド
function godocs_bindToggleLinks(className, prefix) {
  var links = getElementsByClassName(document, className);
  for (i = 0; i < links.length; i++) {
    godocs_bindToggleLink(links[i], prefix);
  }
}

// ページロード時の初期化処理
function godocs_onload() {
  godocs_bindSearchEvents();
  godocs_generateTOC();
  godocs_bindToggles("toggle"); // 初期状態で折りたたまれている要素にトグル機能をバインド
  godocs_bindToggles("toggleVisible"); // 初期状態で展開されている要素にトグル機能をバインド
  godocs_bindToggleLinks("exampleLink", "example_"); // コード例へのリンクにトグルリンク機能をバインド
  godocs_bindToggleLinks("overviewLink", ""); // Overviewセクションへのリンクにトグルリンク機能をバインド
}

doc/style.css

/* 汎用的なトグルボタンのカーソルスタイル */
.toggleButton { cursor: pointer; }

/* 折りたたみ状態の要素: collapsed を表示し、expanded を非表示 */
.toggle .collapsed { display: block; }
.toggle .expanded { display: none; }

/* 展開状態の要素: collapsed を非表示にし、expanded を表示 */
.toggleVisible .collapsed { display: none; }
.toggleVisible .expanded { display: block; }

lib/godoc/package.html

<!-- ナビゲーション内のOverviewリンクに overviewLink クラスを追加 -->
<dd><a href="#overview" class="overviewLink">Overview</a></dd>

<!-- Overviewセクションの新しいHTML構造 -->
<div id="overview" class="toggleVisible"> <!-- 初期状態で展開されるように toggleVisible クラスを付与 -->
    <div class="collapsed"> <!-- 折りたたみ状態の表示内容 -->
        <h2 class="toggleButton" title="Click to show Overview section">Overview ▹</h2>
    </div>
    <div class="expanded"> <!-- 展開状態の表示内容 -->
        <h2 class="toggleButton" title="Click to hide Overview section">Overview ▾</h2>
        {{comment_html .Doc}} <!-- 実際のパッケージコメントの内容 -->
    </div>
</div>

これらのコード変更により、JavaScriptがHTML要素のクラスを切り替えることで、CSSの表示/非表示ルールが適用され、ユーザーはOverviewセクションをインタラクティブに折りたたんだり展開したりできるようになります。

関連リンク

• Go言語のgodocツール
• このコミットのGerrit変更リスト

参考にした情報源リンク

• 上記のGitHubコミットページとGerrit変更リストのdiff情報。
• Go言語の公式ドキュメント（godocに関する一般的な情報）。
• HTML, CSS, JavaScriptの基本的なウェブ技術に関する知識。