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

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

このコミットは、Go言語の公式ドキュメントツールであるgodocのフロントエンドスクリプトdoc/godocs.jsに対する変更です。具体的には、URLのハッシュ（#以降の部分）によって指定された要素が、ページ読み込み時に自動的に表示されるようにする機能を追加しています。これにより、例えばhttp://golang.org/pkg/net/http/#example_HijackerのようなURLに直接アクセスした場合に、example_Hijackerセクションが隠れた状態ではなく、最初から展開された状態で表示されるようになります。これは、ユーザーが特定のドキュメントセクションへのディープリンクを共有したり、ブックマークしたりする際の利便性を大幅に向上させるものです。

コミット

commit 13d6f8f7f324a5dba5e5c3c1f72d7f09b07846e9
Author: Kamil Kisiel <kamil@kamilkisiel.net>
Date:   Fri Apr 5 08:04:02 2013 +1100

    godoc: enable visibility of element linked from URL hash
    
    Expands the example when visiting a URL such as
    http://golang.org/pkg/net/http/#example_Hijacker
    
    Fixes #5212.
    
    R=golang-dev, bradfitz, adg
    CC=golang-dev
    https://golang.org/cl/8378043

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

https://github.com/golang/go/commit/13d6f8f7f324a5dba5e5c3c1f72d7f09b07846e9

元コミット内容

godoc: enable visibility of element linked from URL hash
    
Expands the example when visiting a URL such as
http://golang.org/pkg/net/http/#example_Hijacker
    
Fixes #5212.
    
R=golang-dev, bradfitz, adg
CC=golang-dev
https://golang.org/cl/8378043

変更の背景

godocによって生成されるドキュメントページでは、一部のセクション（特にexampleブロックなど）が初期状態で折りたたまれていることがあります。これは、ページの全体的な見通しを良くし、ユーザーが興味のある部分だけを展開して閲覧できるようにするためのUI/UX上の配慮です。しかし、URLのフラグメント識別子（ハッシュ、例: #example_Hijacker）を使用して特定のセクションに直接リンクした場合、そのセクションが折りたたまれたままだと、ユーザーは目的のコンテンツを見つけるために手動で展開する必要がありました。

このコミットは、このユーザーエクスペリエンス上の課題を解決するために導入されました。URLハッシュで指定された要素が、もし初期状態で折りたたまれているべき要素（toggleクラスを持つ要素）であれば、ページ読み込み時に自動的に展開（toggleVisibleクラスを付与）することで、ユーザーが直接目的のコンテンツにアクセスできるようにします。これにより、ディープリンクの有用性が向上し、ドキュメントのナビゲーションがよりスムーズになります。

前提知識の解説

godoc

godocは、Go言語のソースコードからドキュメントを生成し、HTTPサーバーとして提供するためのツールです。Goのコードは、コメントの書き方によって自動的にドキュメントとして認識され、godocはそのコメントとコード構造を解析して、開発者やユーザーが参照しやすい形式で表示します。これは、Go言語のエコシステムにおける重要な部分であり、ライブラリやパッケージの利用方法を理解するために広く使われています。

URLハッシュ（フラグメント識別子）

URLの末尾に#記号とそれに続く文字列がある場合、その部分は「フラグメント識別子」または「URLハッシュ」と呼ばれます。これは、Webページ全体ではなく、そのページ内の特定のセクションや要素を指し示すために使用されます。ブラウザは、URLハッシュが存在する場合、ページが読み込まれた後にそのハッシュに対応するIDを持つ要素まで自動的にスクロールします。例えば、http://example.com/page.html#section2というURLは、page.html内のIDがsection2の要素に直接ジャンプします。

JavaScriptとDOM操作

JavaScriptは、Webページに動的な機能を追加するためのプログラミング言語です。DOM（Document Object Model）は、Webページの構造をオブジェクトとして表現するAPIであり、JavaScriptはDOMを操作することで、HTML要素の追加、削除、変更、スタイルの適用、イベントの処理などを行うことができます。

jQuery

jQueryは、JavaScriptのライブラリであり、DOM操作、イベント処理、アニメーション、Ajaxなどをより簡単に行えるようにするためのものです。このコミットのコードでは、$記号がjQueryオブジェクトを指し、.is(), .addClass(), .removeClass(), $(document).ready()などのメソッドが使用されています。

  • $(selector): 指定されたセレクタに一致するDOM要素をjQueryオブジェクトとしてラップします。
  • .is(selector): jQueryオブジェクトが指定されたセレクタに一致するかどうかを判定します。
  • .addClass(className): 要素に指定されたCSSクラスを追加します。
  • .removeClass(className): 要素から指定されたCSSクラスを削除します。
  • $(document).ready(function): DOMツリーが完全に構築された後に、指定された関数を実行します。これにより、JavaScriptコードがHTML要素にアクセスしようとしたときに、まだ要素が存在しないという問題を避けることができます。

CSSクラス（.toggle, .toggleVisible）

CSSクラスは、HTML要素にスタイルを適用するための識別子です。この文脈では、toggleクラスは要素が初期状態で折りたたまれていることを示し、toggleVisibleクラスは要素が展開されて表示されていることを示すために使用されていると推測されます。JavaScriptがこれらのクラスを動的に追加・削除することで、要素の表示状態を切り替えます。

技術的詳細

この変更は、クライアントサイドのJavaScriptによって実現されています。godocのドキュメントページがブラウザに読み込まれた際、JavaScriptコードが実行され、現在のURLのハッシュ部分をチェックします。

  1. URLハッシュの取得: window.location.hashプロパティを使用して、現在のURLのハッシュ部分（例: #example_Hijacker）を取得します。
  2. 要素の特定: 取得したハッシュをセレクタとして使用し、jQueryの$(window.location.hash)によって、そのハッシュに対応するIDを持つDOM要素を特定します。
  3. 条件付き展開: 特定された要素が、もしtoggleというCSSクラスを持っている場合（これは、その要素が通常は折りたたまれていることを意味します）、その要素からtoggleクラスを削除し、代わりにtoggleVisibleクラスを追加します。これにより、CSSのルールに基づいて、その要素が展開された状態で表示されるようになります。
  4. 実行タイミング: このtoggleHash関数は、$(document).ready()コールバック内で実行されます。これは、HTMLドキュメントが完全に読み込まれ、DOMツリーが構築された後にこの処理が行われることを保証します。これにより、JavaScriptが操作しようとする要素が確実に存在している状態で行われます。

このアプローチにより、サーバーサイドの変更なしに、クライアントサイドでユーザーエクスペリエンスを向上させています。

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

--- a/doc/godocs.js
+++ b/doc/godocs.js
@@ -179,6 +179,13 @@ function fixFocus() {
   }).resize();
 }
 
+function toggleHash() {
+    var hash = $(window.location.hash);
+    if (hash.is('.toggle')) {
+      hash.addClass('toggleVisible').removeClass('toggle');
+    }
+}
+
 $(document).ready(function() {
   bindSearchEvents();
   generateTOC();
@@ -190,6 +197,7 @@ $(document).ready(function() {
   bindToggleLinks(".indexLink", "");
   setupDropdownPlayground();
   fixFocus();
+  toggleHash();
 });
 
 })();

コアとなるコードの解説

新しい関数 toggleHash()

function toggleHash() {
    var hash = $(window.location.hash);
    if (hash.is('.toggle')) {
      hash.addClass('toggleVisible').removeClass('toggle');
    }
}
  • function toggleHash() { ... }: toggleHashという名前の新しいJavaScript関数を定義しています。
  • var hash = $(window.location.hash);:
    • window.location.hashは、現在のURLのフラグメント識別子（例: "#example_Hijacker"）を文字列として返します。
    • $()はjQueryのファクトリ関数で、引数にセレクタ文字列（この場合はURLハッシュ）を受け取り、そのセレクタに一致するDOM要素をラップしたjQueryオブジェクトを返します。結果として、hash変数には、URLハッシュに対応するIDを持つ要素のjQueryオブジェクトが格納されます。
  • if (hash.is('.toggle')) { ... }:
    • hash.is('.toggle')は、hashが表す要素が.toggleというCSSクラスを持っているかどうかをチェックします。toggleクラスは、通常、初期状態で折りたたまれている要素に付与されていると想定されます。
    • もし要素がtoggleクラスを持っていれば、条件が真となり、ifブロック内のコードが実行されます。
  • hash.addClass('toggleVisible').removeClass('toggle');:
    • hash.addClass('toggleVisible'): hashが表す要素にtoggleVisibleというCSSクラスを追加します。このクラスは、要素を展開して表示するためのスタイルを適用すると考えられます。
    • .removeClass('toggle'): hashが表す要素からtoggleというCSSクラスを削除します。これにより、要素が折りたたまれた状態ではなくなります。
    • これらのメソッドはjQueryチェーンとして記述されており、addClassの戻り値がremoveClassの対象となるため、簡潔に記述できます。

$(document).ready()内での呼び出し

$(document).ready(function() {
  // ... 既存のコード ...
  fixFocus();
  toggleHash(); // ここで新しい関数が呼び出される
});
  • $(document).ready(function() { ... });: このブロック内のコードは、HTMLドキュメントが完全に読み込まれ、DOMツリーが構築された後に実行されます。これにより、toggleHash関数が操作しようとするDOM要素が確実に存在していることが保証されます。
  • toggleHash();: $(document).ready()コールバックの最後にtoggleHash関数が呼び出されています。これにより、ページが読み込まれた直後に、URLハッシュに基づく要素の表示状態の調整が行われます。

この変更により、godocのドキュメントページにディープリンクでアクセスした際に、目的のセクションが自動的に展開され、ユーザーがすぐにコンテンツを閲覧できるようになります。

関連リンク

参考にした情報源リンク