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

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

このコミットは、Go言語のドキュメンテーションツールであるgodocの表示順序に関する変更です。具体的には、型（type）に関連するサンプルコード（examples）の表示位置を、その型に属する定数（constants）や変数（variables）のセクションの後に移動させることで、ドキュメントの可読性と論理的な流れを改善しています。

コミット

commit af848926431da0345fd78c0dba0a513df44ee1cf
Author: Volker Dobler <dr.volker.dobler@gmail.com>
Date:   Tue Dec 6 10:52:43 2011 +1100

    godoc: Show type examples between variables and methods.
    
    Fixes #2466.
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/5451094

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

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

元コミット内容

godoc: Show type examples between variables and methods.

このコミットは、godocが生成するドキュメントにおいて、型に関連するサンプルコード（examples）の表示位置を調整するものです。具体的には、型に属する変数や定数のセクションと、メソッドやファクトリ関数のセクションの間にサンプルコードを表示するように変更します。これにより、関連する情報がより論理的に配置され、ドキュメントの理解が容易になります。

この変更は、GoのIssue #2466を修正するものです。

変更の背景

Go言語の公式ドキュメンテーションツールであるgodocは、Goのソースコードから自動的にドキュメントを生成します。このドキュメントは、パッケージ、型、関数、変数などの要素について詳細な情報を提供し、特にサンプルコード（Examples）は、その要素の利用方法を具体的に示す上で非常に重要です。

このコミットが行われる前は、型に関連するサンプルコードは、型の宣言とドキュメントの直後に表示されていました。しかし、型にはその型に属する定数や変数も存在し、それらの情報も型のドキュメントの一部として重要です。サンプルコードが型の宣言直後に表示されると、定数や変数のセクションよりも前に来てしまい、ドキュメント全体の流れが不自然になる可能性がありました。

Issue #2466（"godoc: type examples should appear after variables"）は、この表示順序の問題を指摘しています。ユーザーは、型の定数や変数が先に表示され、その後に型全体の利用例としてのサンプルコードが続く方が、より自然で理解しやすいと感じていました。この変更は、このフィードバックに応え、godocが生成するドキュメントの論理的な構造と可読性を向上させることを目的としています。

前提知識の解説

godoc

godocは、Go言語のソースコードからドキュメンテーションを生成し、Webブラウザで表示するためのツールです。Goのコードに記述されたコメント（特にエクスポートされた識別子に付随するコメント）や、Example関数として記述されたサンプルコードを解析し、整形されたHTMLドキュメントとして提供します。開発者はgodocを使うことで、コードとドキュメントを密接に連携させ、常に最新のドキュメントを維持することができます。

Go言語のExamples

Go言語では、パッケージや型、関数などの利用例をExample関数として記述することができます。これらの関数は、_test.goファイル内にExample<Name>という命名規則で定義され、godocによって自動的に検出され、生成されるドキュメントに組み込まれます。Example関数は、単なるコードスニペットではなく、実際にテストとして実行可能であり、出力が期待通りであるかを検証することもできます。これにより、ドキュメントのサンプルコードが常に正しく動作することを保証します。

Goテンプレート (text/template, html/template)

godocは、Goの標準ライブラリであるhtml/templateパッケージを使用してHTMLドキュメントを生成します。html/templateは、Goのデータ構造をHTMLにレンダリングするためのテンプレートエンジンです。テンプレートファイル（例: package.html）には、プレースホルダー（{{.Field}}）や制御構造（{{range .Slice}}, {{if .Condition}}）が記述されており、godocはこれらのテンプレートに解析したGoのコード情報を流し込むことで最終的なHTMLを生成します。

このコミットで変更されているpackage.htmlは、Goパッケージのドキュメントページを生成するためのテンプレートファイルです。

技術的詳細

このコミットの技術的な変更は、godocが使用するHTMLテンプレートファイルlib/godoc/package.html内の特定の行の移動に集約されます。

package.htmlは、Goパッケージのドキュメントページをレンダリングするためのテンプレートです。このテンプレートは、パッケージ内の型、関数、変数、定数などを表示するための構造を定義しています。

変更前は、型の定義（type <name>）とドキュメント（comment_html .Doc）、そしてその型の宣言コード（node_html .Decl $.FSet）の直後に、型に関連するサンプルコード（example_html $tname $.Examples $.FSet）が表示されていました。

<!-- 変更前の一部 -->
<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
{{comment_html .Doc}}
<p><pre>{{node_html .Decl $.FSet}}</pre></p>
{{example_html $tname $.Examples $.FSet}} <!-- ここにあった -->
{{range .Consts}}
    {{comment_html .Doc}}
    <pre>{{node_html .Decl $.FSet}}</pre>
{{end}}
{{range .Vars}}
    {{comment_html .Doc}}
    <pre>{{node_html .Decl $.FSet}}</pre>
{{end}}

このコミットでは、{{example_html $tname $.Examples $.FSet}}の行が、型の定数（Consts）と変数（Vars）のセクションの後に移動されました。

<!-- 変更後の一部 -->
<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
{{comment_html .Doc}}
<p><pre>{{node_html .Decl $.FSet}}</pre></p>
{{range .Consts}}
    {{comment_html .Doc}}
    <pre>{{node_html .Decl $.FSet}}</pre>
{{end}}
{{range .Vars}}
    {{comment_html .Doc}}
    <pre>{{node_html .Decl $.FSet}}</pre>
{{end}}
{{example_html $tname $.Examples $.FSet}} <!-- ここに移動した -->
{{range .Factories}}
    {{$name_html := html .Name}}
    <h3 id="{{$name_html}}">func <a href="/{{posLink_url .Decl $.FSet}}">{{$name_html}}</a></h3>

この変更により、godocが生成するHTMLドキュメントでは、型の概要、その型に属する定数、変数、そして最後にその型全体の利用例としてのサンプルコードが順に表示されるようになります。これは、読者が型の基本的な構成要素を理解した上で、その型がどのように使われるのかを学ぶという、より自然な学習フローを提供します。

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

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

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -89,7 +89,6 @@
  		<h2 id="{{$tname_html}}">type <a href="/{{posLink_url .Decl $.FSet}}">{{$tname_html}}</a></h2>
  		{{comment_html .Doc}}
  		<p><pre>{{node_html .Decl $.FSet}}</pre></p>
-\t\t{{example_html $tname $.Examples $.FSet}}\n
  		{{range .Consts}}\n
  		\t\t\t{{comment_html .Doc}}\n
  \t\t\t<pre>{{node_html .Decl $.FSet}}</pre>\n
@@ -98,6 +97,7 @@
  		\t\t\t{{comment_html .Doc}}\n
  \t\t\t<pre>{{node_html .Decl $.FSet}}</pre>\n
  \t\t{{end}}\n
+\t\t{{example_html $tname $.Examples $.FSet}}\n
  		{{range .Factories}}\n
  		\t\t\t{{$name_html := html .Name}}\n
  \t\t\t<h3 id=\"{{$name_html}}\">func <a href=\"/{{posLink_url .Decl $.FSet}}\">{{$name_html}}</a></h3>
  • - {{example_html $tname $.Examples $.FSet}} の行が削除されています。これは、型の宣言とドキュメントの直後にあったサンプルコードの表示部分です。
  • + {{example_html $tname $.Examples $.FSet}} の行が追加されています。これは、型の定数と変数のリストを処理する{{end}}タグの直後、かつファクトリ関数（Factories）のリストを処理する{{range .Factories}}タグの直前に挿入されています。

コアとなるコードの解説

この変更は、godocがGoの型に関するドキュメントを生成する際のHTML構造を再編成するものです。

  • {{$tname_html}}: 現在処理している型の名前をHTMLエスケープしたものです。
  • {{posLink_url .Decl $.FSet}}: 型の宣言元へのリンクを生成します。
  • {{comment_html .Doc}}: 型のドキュメントコメントをHTMLとしてレンダリングします。
  • {{node_html .Decl $.FSet}}: 型の宣言コード（例: type MyType struct { ... }）をHTMLとしてレンダリングします。
  • {{example_html $tname $.Examples $.FSet}}: $tname（型名）に関連するサンプルコード（$.Examples）をHTMLとしてレンダリングします。$.FSetはファイルセット情報で、ソースコードへのリンク生成などに使われます。
  • {{range .Consts}} / {{range .Vars}}: 型に属する定数や変数をループ処理し、それぞれのドキュメントと宣言コードをレンダリングします。
  • {{range .Factories}}: 型に関連するファクトリ関数（通常はfunc NewType(...)のような関数）をループ処理し、それぞれのドキュメントと宣言コードをレンダリングします。

このコミットは、example_htmlの呼び出し位置を移動させることで、godocが生成するドキュメントのセクション順序を変更しています。これにより、型の基本的な定義、関連する定数や変数、そしてその後に型全体の利用例が続くという、より論理的で読みやすいドキュメント構造が実現されます。

関連リンク

参考にした情報源リンク