[インデックス 12638] ファイルの概要
このコミットは、godoc ツールによって生成されるドキュメント内の「Example」セクションの見出しのスタイルを、通常のリンクと同じように見せるように変更するものです。具体的には、CSS を修正して .exampleHeading .text クラスを持つ要素にリンクと同じ色と下線（ホバー時）を適用し、HTML テンプレートを更新して該当する見出しテキストを <span> タグで囲み、そのクラスを付与しています。これにより、ユーザーインターフェースの一貫性が向上し、見出しがクリック可能であることを視覚的に示唆するようになります。
コミット
commit 9d08068d216163d900843a53b12caac31890e9a1
Author: Andrew Gerrand <adg@golang.org>
Date: Thu Mar 15 08:09:54 2012 +1100
godoc: style example headings like links
R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5819048
GitHub上でのコミットページへのリンク
https://github.com/golang/go/commit/9d08068d216163d900843a53b12caac31890e9a1
元コミット内容
godoc: style example headings like links
R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5819048
変更の背景
godoc は Go 言語のソースコードからドキュメントを生成するツールであり、その出力はウェブブラウザで閲覧されることが一般的です。このコミットが行われた当時、godoc が生成するドキュメント内の「Example」セクションの見出しは、通常のテキストとして表示されていました。しかし、これらの見出しは通常、クリックすることで詳細なコード例の表示/非表示を切り替える機能を持っていました。
ユーザーインターフェースの設計において、クリック可能な要素は視覚的にそのように認識されるべきです。一般的なウェブサイトでは、リンクは青色で表示され、マウスカーソルを合わせると下線が表示されるなど、特定のスタイルが適用されることで、それがインタラクティブな要素であることが示唆されます。
このコミットの背景には、godoc のユーザーエクスペリエンスを向上させ、Example 見出しがクリック可能であることをより明確にユーザーに伝えるという目的があります。見出しを通常のリンクと同じスタイルにすることで、ユーザーは直感的にその機能性を理解し、ドキュメントの操作性が向上します。これは、UI/UX の一貫性を保ち、ユーザーがウェブページをより効率的に操作できるようにするための一般的なプラクティスです。
前提知識の解説
godoc
godoc は Go 言語に標準で付属するツールで、Go のソースコードからドキュメントを生成し、ウェブサーバーとして提供する機能を持っています。開発者は godoc を利用することで、コード内のコメントや構造から自動的に API ドキュメントやコード例（Example）を含むリファレンスを生成できます。これは、Go の「ドキュメントはコードと共に書かれるべき」という哲学を反映したもので、コードの可読性と保守性を高める上で非常に重要なツールです。
CSS (Cascading Style Sheets)
CSS は、HTML や XML ドキュメントの表示（色、フォント、レイアウトなど）を記述するためのスタイルシート言語です。ウェブページのデザインとレイアウトを制御するために使用されます。CSS はセレクタ（どのHTML要素にスタイルを適用するか）とプロパティ（どのようなスタイルを適用するか）の組み合わせで構成されます。
- セレクタ: HTML要素のタグ名、クラス名 (
.class-name)、ID (#id-name)、属性などを用いて、スタイルを適用する要素を指定します。 - プロパティ:
color(文字色),text-decoration(テキスト装飾、例:noneで下線なし、underlineで下線あり) など、要素の視覚的な特性を定義します。 :hover擬似クラス: 要素にマウスカーソルが乗ったときに適用されるスタイルを定義します。これにより、インタラクティブな要素に視覚的なフィードバックを提供できます。
HTML (HyperText Markup Language)
HTML は、ウェブページの構造を定義するためのマークアップ言語です。テキスト、画像、リンクなどのコンテンツを配置し、それらの関係性を記述します。
<a>タグ: アンカー（Anchor）タグと呼ばれ、ハイパーリンクを作成するために使用されます。通常、青色で表示され、下線が引かれることが多いです。<p>タグ: 段落（Paragraph）を表すタグです。<div>タグ: ディビジョン（Division）を表すタグで、コンテンツをグループ化するために使用される汎用的なコンテナ要素です。<span>タグ: スパン（Span）タグと呼ばれ、インライン要素をグループ化するために使用される汎用的なコンテナ要素です。特定のテキスト部分にスタイルを適用する際によく使われます。
技術的詳細
このコミットの技術的変更は、主に CSS のセレクタの拡張と、それに伴う HTML 構造の微調整にあります。
-
CSS セレクタの拡張: 変更前は、
a(アンカータグ) にのみcolor: #375EAB;(青色) とtext-decoration: none;(下線なし) が適用されていました。また、a:hoverにのみtext-decoration: underline;(下線あり) が適用されていました。 変更後、これらのスタイルルールに.exampleHeading .textというセレクタが追加されました。これは、exampleHeadingクラスを持つ要素の子孫であるtextクラスを持つ要素に、同じスタイルを適用することを意味します。これにより、Example 見出しのテキストが通常のリンクと同じ色になり、ホバー時に下線が表示されるようになります。a, .exampleHeading .text:a要素と、.exampleHeadingの子孫である.textクラスを持つ要素の両方にスタイルを適用します。a:hover, .exampleHeading .text:hover:a要素がホバーされた時と、.exampleHeadingの子孫である.textクラスを持つ要素がホバーされた時の両方にスタイルを適用します。
-
HTML 構造の変更:
lib/godoc/example.htmlテンプレートでは、Example 見出しのテキスト (Example{{example_suffix .Name}}) が直接<p class="exampleHeading">タグ内に配置されていました。 この変更により、見出しテキストが新たに<span class="text">タグで囲まれるようになりました。これにより、CSS で定義された.exampleHeading .textセレクタがこのテキスト部分に正確にマッチし、スタイルが適用されるようになります。
これらの変更は、ウェブページのレンダリングにおいて、ブラウザが CSS ルールを HTML 要素にどのように適用するかという基本的なメカニズムに基づいています。CSS のカスケードと継承のルールにより、より具体的なセレクタが優先され、要素にスタイルが適用されます。この場合、<span> タグに text クラスを付与し、親要素の exampleHeading と組み合わせることで、特定のテキスト部分にのみリンクのスタイルを適用することが可能になっています。
コアとなるコードの変更箇所
doc/style.css
--- a/doc/style.css
+++ b/doc/style.css
@@ -30,11 +30,13 @@ pre .ln {
body {
color: #222;
}
-a {
+a,
+.exampleHeading .text {
color: #375EAB;
text-decoration: none;
}
-a:hover {
+a:hover,
+.exampleHeading .text:hover {
text-decoration: underline;
}
p,
lib/godoc/example.html
--- a/lib/godoc/example.html
+++ b/lib/godoc/example.html
@@ -1,9 +1,9 @@
<div id="example_{{.Name}}" class="example">\n \t<div class="collapsed">\n-\t\t<p class="exampleHeading">▹ Example{{example_suffix .Name}}</p>\n+\t\t<p class="exampleHeading">▹ <span class="text">Example{{example_suffix .Name}}</span></p>\n \t</div>\n \t<div class="expanded">\n-\t\t<p class=\"exampleHeading\">▾ Example{{example_suffix .Name}}</p>\n+\t\t<p class=\"exampleHeading\">▾ <span class=\"text\">Example{{example_suffix .Name}}</span></p>\n \t\t{{with .Doc}}<p>{{html .}}</p>{{end}}\n \t\t<p>Code:</p>\n \t\t<pre class=\"code\">{{.Code}}</pre>\n```
## コアとなるコードの解説
### `doc/style.css` の変更
このファイルでは、ウェブサイト全体のスタイルを定義する CSS が変更されています。
* **変更前**:
```css
a {
color: #375EAB;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
```
これは、すべての `<a>` タグ（リンク）に対して、文字色を `#375EAB` (青色) に設定し、デフォルトの下線をなくすことを指定しています。また、`<a>` タグにマウスカーソルが乗った際には下線を表示するように指定しています。
* **変更後**:
```css
a,
.exampleHeading .text {
color: #375EAB;
text-decoration: none;
}
a:hover,
.exampleHeading .text:hover {
text-decoration: underline;
}
```
既存の `a` セレクタに加えて、`.exampleHeading .text` というセレクタが追加されました。これは、`exampleHeading` クラスを持つ要素の内部にある `text` クラスを持つ要素にも、全く同じスタイル（青色の文字、デフォルト下線なし、ホバー時に下線あり）を適用することを意味します。これにより、Example 見出しのテキストが通常のリンクと同じ視覚的特性を持つようになります。
### `lib/godoc/example.html` の変更
このファイルは、`godoc` が Example セクションをレンダリングする際に使用する HTML テンプレートです。
* **変更前**:
```html
<p class="exampleHeading">▹ Example{{example_suffix .Name}}</p>
```
Example 見出しのテキスト (`Example{{example_suffix .Name}}`) は、直接 `<p>` タグ内に含まれていました。この `<p>` タグには `exampleHeading` クラスが付与されています。
* **変更後**:
```html
<p class="exampleHeading">▹ <span class="text">Example{{example_suffix .Name}}</span></p>
```
Example 見出しのテキスト部分が、新たに `<span class="text">` タグで囲まれました。この `<span>` タグに `text` クラスが付与されたことで、前述の `doc/style.css` で追加された `.exampleHeading .text` セレクタがこの部分にマッチし、リンクと同じスタイルが適用されるようになります。これにより、見出しのテキスト部分のみがリンクのように表示され、クリック可能であることが視覚的に示唆されます。
これらの変更は連携しており、HTML テンプレートで特定のテキスト部分に新しいクラスを付与し、そのクラスを CSS でターゲットとすることで、既存のリンクスタイルを再利用して Example 見出しに適用しています。
## 関連リンク
* Go CL 5819048: [https://golang.org/cl/5819048](https://golang.org/cl/5819048)
## 参考にした情報源リンク
* Go 言語公式ドキュメント (godoc): [https://go.dev/blog/godoc](https://go.dev/blog/godoc)
* MDN Web Docs (CSS): [https://developer.mozilla.org/ja/docs/Web/CSS](https://developer.mozilla.org/ja/docs/Web/CSS)
* MDN Web Docs (HTML): [https://developer.mozilla.org/ja/docs/Web/HTML](https://developer.mozilla.org/ja/docs/Web/HTML)
* GitHub (golang/go リポジトリ): [https://github.com/golang/go](https://github.com/golang/go)