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

コミット

commit 71b1c6d3c98b0f34070be4c8f5e9d4c0cb2731ac
Author: Russ Cox <rsc@golang.org>
Date:   Thu Jan 26 13:02:03 2012 -0500

    godoc: move overview before API TOC
    
    Compare:
    http://swtch.com/junk/regexp0.html [old]
    http://swtch.com/junk/regexp.html [new]
    
    Especially for packages with large APIs, this makes the
    overview more promiment, so that it can give the appropriate
    context for reading the API list.  This should help significantly
    in packages with large APIs, like net, so that the first thing users
    see is not a jumble of functions but an introduction to the package.
    
    R=adg, gri, r, kevlar, dsymonds, rogpeppe
    CC=golang-dev
    https://golang.org/cl/5573068

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

https://github.com/golang/go/commit/71b1c6d3c98b0f34070be4c8f5e9d4c0cb2731ac

元コミット内容

このコミットは、Go言語のドキュメンテーションツールであるgodocが生成するパッケージドキュメントの表示順序を変更するものです。具体的には、APIの目次（Table of Contents, TOC）よりも前にパッケージの概要（Overview）が表示されるように変更されました。

コミットメッセージでは、この変更の意図が明確に述べられています。特に大規模なAPIを持つパッケージ（例: netパッケージ）において、ユーザーが最初に目にするのが多数の関数や型の羅列ではなく、パッケージ全体の導入部分となることで、APIリストを読み解くための適切なコンテキストを提供し、理解を深める助けとなることが期待されています。

変更前後のregexpパッケージのドキュメントの比較リンクも提供されており、視覚的な違いを確認できます。

変更の背景

Go言語の公式ドキュメンテーションツールであるgodocは、Goのソースコードから自動的にドキュメントを生成し、ウェブブラウザで閲覧可能な形式で提供します。このツールは、Goのコードベースにおけるコメントの書き方やパッケージ構造の慣習と密接に結びついており、開発者がコードとドキュメントを同時に管理しやすいように設計されています。

このコミットが行われた2012年当時、Go言語はまだ比較的新しい言語であり、そのエコシステムやツールも進化の途上にありました。godocが生成するドキュメントの初期のレイアウトでは、パッケージのAPI目次が概要よりも先に表示されていました。これは、小規模なパッケージでは問題となりにくいものの、netパッケージのように非常に多くの関数、型、メソッドを持つ大規模なパッケージでは、ユーザーがページを開いた瞬間に膨大なAPIリストに直面し、パッケージ全体の目的や使い方を把握する前に詳細な情報に圧倒されてしまうという課題がありました。

開発者体験（Developer Experience, DX）の観点から見ると、ユーザーが新しいパッケージを学ぶ際、まずそのパッケージが何をするものなのか、どのような概念に基づいているのかといった「概要」を理解することが重要です。その上で、具体的なAPIの詳細（関数、型、変数など）を参照するのが自然な学習フローです。このコミットは、このようなユーザーの学習フローを改善し、godocが提供するドキュメントのユーザビリティを向上させることを目的としています。概要をAPI目次よりも上位に配置することで、ユーザーはまずパッケージの全体像を把握し、その後に必要に応じて詳細なAPI情報を参照できるようになります。

前提知識の解説

godoc

godocは、Go言語のソースコードからドキュメントを生成し、HTTPサーバーとして提供するツールです。Goのソースコード内のコメント（特にパッケージ、関数、型、変数などの宣言の直前にあるコメント）を解析し、それらを整形されたHTMLドキュメントとして出力します。これにより、開発者はコードとドキュメントを密接に連携させ、常に最新のドキュメントを維持しやすくなります。godocは、Go言語の標準ライブラリのドキュメント（pkg.go.devで閲覧可能）の基盤ともなっています。

Go言語のパッケージドキュメンテーションの慣習

Go言語では、パッケージのドキュメンテーションは通常、パッケージ宣言の直前にあるコメントブロックに記述されます。このコメントは、パッケージ全体の目的、主要な機能、使用例などを説明する「概要（Overview）」として機能します。godocは、この概要をドキュメントの冒頭に表示します。また、エクスポートされた各関数、型、変数、メソッドにもそれぞれコメントを付与し、それらがAPIドキュメントとして生成されます。

HTMLテンプレート

このコミットで変更されたlib/godoc/package.htmlファイルは、Go言語のhtml/templateパッケージ（またはその前身であるtext/templateパッケージ）によって処理されるHTMLテンプレートです。テンプレートエンジンは、データ（この場合はgodocが解析したGoのパッケージ情報）を受け取り、それをテンプレート内のプレースホルダーや制御構造（{{if}}, {{range}}, {{with}}など）に適用して最終的なHTML出力を生成します。

• {{if .IsPkg}}: 現在のドキュメントがパッケージのものである場合にのみ、内部のコンテンツをレンダリングします。
• {{with .PDoc}}: パッケージドキュメントのデータ構造が存在する場合に、そのデータ構造をコンテキストとして内部のコンテンツをレンダリングします。
• {{range .Funcs}}: パッケージ内の関数リストをイテレートし、各関数に対して内部のコンテンツをレンダリングします。
• {{html .Name}}: 変数.Nameの値をHTMLエスケープして出力します。
• {{node_html .Decl $.FSet}}: GoのAST（抽象構文木）ノードである.DeclをHTML形式で整形して出力します。$.FSetはファイルセット情報を提供します。
• {{comment_html .Doc}}: コメントブロック.DocをHTML形式で整形して出力します。

これらのテンプレート構文を理解することで、package.htmlがどのように動的にパッケージドキュメントを生成しているかを把握できます。

技術的詳細

このコミットの技術的な核心は、godocがパッケージドキュメントを生成する際に使用するHTMLテンプレートファイルlib/godoc/package.htmlの構造変更にあります。

変更前は、package.html内でAPIの目次（<div id="manual-nav">で囲まれた部分）が、パッケージの概要（<h2 id="Overview">Overview</h2>）よりも先に配置されていました。これにより、生成されるHTMLドキュメントでは、ページの上部にまずAPIの目次が表示され、その後に概要が続く形となっていました。

このコミットでは、以下の主要な変更が行われました。

1. 概要セクションの移動:

   • <h2 id="Overview">Overview</h2>とその関連コンテンツ（importパスの表示やcomment_html .Docによるパッケージコメントのレンダリング）が、HTMLファイルのより上部、具体的にはAPI目次を定義する<div id="manual-nav">ブロックよりも前に移動されました。
   • これにより、ブラウザでドキュメントを開いた際に、ユーザーはまずパッケージの概要を読み、そのパッケージが何であるかを理解できるようになります。

2. 新しいナビゲーション要素の導入 (short-nav):

   • <div id="short-nav">という新しいHTML要素が導入されました。この要素は、パッケージのimportパス、そして「Overview」と「Index」へのクイックリンクを含んでいます。
   • このshort-navは、ページの上部に常に表示されることを意図しており、ユーザーが概要とAPI目次（Index）の間を素早く移動できるようにします。

3. API目次の再編成と「Index」セクションの導入:

   • 以前のAPI目次（manual-nav）は、新たに導入された<h2 id="Index">Index</h2>セクションの下に移動されました。
   • この「Index」セクションは、定数、変数、関数、型、メソッド、そしてパッケージファイルへのリンクを含む、パッケージのAPI全体を網羅する目次として機能します。
   • これにより、APIの目次が「Index」という明確なセクション名の下に整理され、概要とAPI詳細の間の論理的な区切りがより明確になりました。

これらの変更は、単にHTML要素の順序を入れ替えるだけでなく、ドキュメントのセマンティックな構造とユーザーインターフェースの設計を改善するものです。特に、大規模なAPIを持つパッケージのドキュメントにおいて、情報過多によるユーザーの混乱を防ぎ、より段階的かつ直感的な情報アクセスを可能にすることを目的としています。

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

変更はlib/godoc/package.htmlファイルに対して行われました。以下に主要な変更点をdiff形式で示します。

--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -3,118 +3,121 @@
  	Use of this source code is governed by a BSD-style
  	license that can be found in the LICENSE file.
 -->
-{{if .IsPkg}}
-<!-- Table of contents; must be named manual-nav to turn off auto nav. -->
-<div id="manual-nav">
 {{with .PDoc}}
--	<dl>
--	<dd><a href="#Overview">Overview</a></dd>
--	{{if .Consts}}
--	... (API TOC content) ...
--	</dl>
-{{end}}
-</div>
-{{end}}
-
-<!-- Main page -->		
-{{with .PAst}}
--	<pre>{{node_html . $.FSet}}</pre>
-{{end}}
-{{with .PDoc}}
--	<h2 id="Overview">Overview</h2>
--	<!-- The package's Name is printed as title by the top-level template -->
--	{{if $.IsPkg}}
--		<p><code>import "{{html .ImportPath}}"</code></p>
--	{{end}}
--	{{comment_html .Doc}}
  	{{if $.IsPkg}}
-+		<div id="short-nav">
-+			<dl>
-+			<dd><code>import "{{html .ImportPath}}"</code></dd>
-+			</dl>
-+			<dl>
-+			<dd><a href="#Overview">Overview</a></dd>
-+			<dd><a href="#Index">Index</a></dd>
-+			</dl>
-+		</div>
-+		<h2 id="Overview">Overview</h2>
-+		<!-- The package's Name is printed as title by the top-level template -->
-+		{{comment_html .Doc}}
-+	
-+		<h2 id="Index">Index</h2>
-+		<!-- Table of contents for API; must be named manual-nav to turn off auto nav. -->
-+		<div id="manual-nav">
-+			<dl>
-+			{{if .Consts}}
-+			... (API TOC content, largely unchanged but moved) ...
-+			</dl>
-+		
-+		{{with .Consts}}
-+			<h2 id="Constants">Constants</h2>
-+			...
-+		{{end}}
-+		{{with .Vars}}
-+			<h2 id="Variables">Variables</h2>
-+			...
-+		{{end}}
-+		{{range .Funcs}}
-+			...
-+		{{end}}
-+		{{range .Types}}
-+			...
-+		{{end}}
-+	{{else}}  {{/* not a package; is a command */}}
-+		{{comment_html .Doc}}
  	{{end}}
-+
  	{{with .Bugs}}
  	...
  	{{end}}
 {{end}}
-+
-+{{with .PAst}}
-+	<pre>{{node_html . $.FSet}}</pre>
-+{{end}}
-+
 {{with .PList}}
  	...
 {{end}}

主な変更点:

1. 旧API目次 (manual-nav) の削除と再配置:

   • ファイルの冒頭にあった{{if .IsPkg}}ブロック内の<div id="manual-nav">（API目次）が削除されました。
   • この内容は、新しい<h2 id="Index">Index</h2>セクションの下に再配置されました。

2. 概要セクションの早期配置:

   • 以前はAPI目次の後にあった<h2 id="Overview">Overview</h2>とその内容（importパス、パッケージコメント）が、{{if $.IsPkg}}ブロックの直下、つまりファイルのより早い位置に移動されました。

3. short-navの導入:

   • 概要セクションの直前に、<div id="short-nav">が新しく追加されました。これにはimportパスと、OverviewおよびIndexへのクイックリンクが含まれます。

4. Indexセクションの導入:

   • <h2 id="Index">Index</h2>という新しい見出しが追加され、その下に旧manual-navの内容（API目次）が配置されました。これにより、APIのリストが「Index」という明確なセクションとして提供されます。

5. PAstブロックの移動:

   • {{with .PAst}}ブロック（パッケージのASTを整形して表示する部分）が、ファイルの末尾近くに移動されました。これは、通常ユーザーが最初に必要とする情報ではないため、ドキュメントの下部に配置することで、主要なコンテンツの邪魔にならないようにするためと考えられます。

これらの変更により、HTMLのレンダリング順序が変わり、ユーザーがドキュメントを閲覧する際の情報の流れが改善されました。

コアとなるコードの解説

変更されたlib/godoc/package.htmlは、Goのhtml/templateパッケージによって解釈されるテンプレートです。このテンプレートは、godocツールがGoのソースコードを解析して得たパッケージ情報（PDoc、PAstなどの構造体）を基に、動的にHTMLを生成します。

変更前の構造（概念図）

[パッケージがGoパッケージの場合]
  [API目次 (manual-nav)]
    - Overviewへのリンク
    - 定数、変数、関数、型、メソッドへのリンク
  [パッケージのAST表示]
  [パッケージドキュメント (PDoc)]
    [Overviewセクション]
      - importパス
      - パッケージコメント
    [定数セクション]
    [変数セクション]
    [関数セクション]
    [型セクション]
      - 型の定数、変数、関数、メソッド
    [バグセクション]
[その他のパッケージリスト]
[サブディレクトリリスト]

変更前は、ユーザーはまずAPI目次を見て、その後に概要や詳細なAPI定義に進む必要がありました。

変更後の構造（概念図）

[パッケージがGoパッケージの場合]
  [ショートナビゲーション (short-nav)]
    - importパス
    - Overviewへのクイックリンク
    - Indexへのクイックリンク
  [Overviewセクション]
    - パッケージコメント
  [Indexセクション]
    [API目次 (manual-nav)]
      - 定数、変数、関数、型、メソッドへのリンク
      - パッケージファイルへのリンク
    [定数セクション]
    [変数セクション]
    [関数セクション]
    [型セクション]
      - 型の定数、変数、関数、メソッド
  [バグセクション]
[パッケージのAST表示]
[その他のパッケージリスト]
[サブディレクトリリスト]

変更点の詳細な解説

1. short-navの導入:

   <div id="short-nav">
       <dl>
       <dd><code>import "{{html .ImportPath}}"</code></dd>
       </dl>
       <dl>
       <dd><a href="#Overview">Overview</a></dd>
       <dd><a href="#Index">Index</a></dd>
       </dl>
   </div>
   

   この新しいブロックは、ドキュメントの最上部に配置され、パッケージのインポートパスと、主要なセクションである「Overview」と「Index」への直接リンクを提供します。これにより、ユーザーはページをスクロールすることなく、これらの重要なセクションに素早くアクセスできるようになります。特に、長いドキュメントの場合にナビゲーションの利便性が向上します。

2. Overviewセクションの昇格:

   <h2 id="Overview">Overview</h2>
   <!-- The package's Name is printed as title by the top-level template -->
   {{comment_html .Doc}}
   

   以前はAPI目次の後にあったOverviewセクションが、short-navの直後に移動されました。これにより、ユーザーがページを開くと、まずパッケージの目的や機能に関する説明（comment_html .Docでレンダリングされるパッケージコメント）が目に入るようになります。これは、パッケージの全体像を把握するための「導入」として機能し、その後の詳細なAPI情報の理解を助けます。

3. Indexセクションとmanual-navの統合:

   <h2 id="Index">Index</h2>
   <!-- Table of contents for API; must be named manual-nav to turn off auto nav. -->
   <div id="manual-nav">
       <dl>
       {{if .Consts}}
           <dd><a href="#Constants">Constants</a></dd>
       {{end}}
       ... (既存のAPI目次項目) ...
       <dd>
       {{with .Filenames}}
           <h4>Package files</h4>
           <p>
           <span style="font-size:90%">
           {{range .}}
               <a href="/{{.|srcLink}}">{{.|filename|html}}</a>
           {{end}}
           </span>
           </p>
       {{end}}
       </dd>
       </dl>
   </div>
   

   以前は独立していたAPI目次（manual-nav）が、新たに導入されたIndexセクションの下に配置されました。このIndexセクションは、パッケージ内のすべてのエクスポートされた要素（定数、変数、関数、型、メソッド）へのリンクを含む包括的な目次として機能します。また、パッケージを構成するソースファイルへのリンクもこのセクションに含まれるようになりました。これにより、APIの構造がより明確に整理され、ユーザーは必要なAPI要素を効率的に見つけられるようになります。

4. PAstブロックの移動: {{with .PAst}}ブロックは、パッケージの抽象構文木（AST）を整形して表示する部分です。これは主にデバッグや詳細なコード構造の確認に用いられるため、一般的なユーザーが最初に必要とする情報ではありません。このコミットでは、このブロックがドキュメントの末尾近くに移動され、主要なドキュメントコンテンツの邪魔にならないように配慮されています。

これらの変更は、godocが生成するドキュメントの論理的な流れと視覚的な階層を改善し、特に大規模なGoパッケージのドキュメントの可読性とユーザビリティを大幅に向上させる効果があります。

関連リンク

• 変更前後のregexpパッケージドキュメントの比較:
  • 旧バージョン: http://swtch.com/junk/regexp0.html
  • 新バージョン: http://swtch.com/junk/regexp.html
• Gerrit Change-ID:
  • https://golang.org/cl/5573068

参考にした情報源リンク

• Go言語公式ドキュメント: https://go.dev/doc/
• godocコマンドのドキュメント: https://pkg.go.dev/cmd/godoc
• html/templateパッケージのドキュメント: https://pkg.go.dev/html/template
• Go言語のパッケージドキュメンテーションに関する慣習（Effective Goなど）: https://go.dev/doc/effective_go#commentary