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

このコミットは、Go言語のドキュメンテーションツールである cmd/godoc において、コマンド（実行可能ファイル）のドキュメンテーション表示方法を修正するものです。具体的には、godoc がコマンドのパッケージドキュメンテーションではなく、コマンド自身のドキュメンテーションのみを表示するように変更されました。

コミット

commit d74d0b269de395aa4be7a7bc04fda23cde9ce34f
Author: Robert Griesemer <gri@golang.org>
Date:   Mon Mar 11 13:38:59 2013 -0700

    cmd/godoc: only show package documentation for commands
    
    Fixed package.txt and adjusted package.html to match
    structure (swapped if branches).
    
    Fixes #4861.
    
    R=golang-dev, adg, rsc
    CC=golang-dev
    https://golang.org/cl/7714043

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

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

元コミット内容

cmd/godoc: コマンドに対してはパッケージドキュメンテーションのみを表示する。 package.txt を修正し、package.html を構造に合わせて調整した（if分岐を入れ替えた）。 Issue #4861 を修正。

この変更は、Goのドキュメンテーションツール godoc の表示に関するバグ修正（Issue #4861）に対応するものです。従来の godoc は、main パッケージとしてビルドされるコマンド（実行可能ファイル）に対しても、そのパッケージのドキュメンテーションを表示していました。しかし、コマンドの場合、ユーザーが本当に知りたいのはそのコマンドが何をするのか、どのように使うのかといったコマンド自体の説明であり、内部的なパッケージ構造の説明ではありません。

例えば、go コマンド自体を godoc で見た場合、go コマンドの機能説明ではなく、main パッケージとしての一般的な情報が表示されてしまうという問題がありました。このコミットは、この挙動を修正し、コマンドに対してはコマンドのドキュメンテーション（main パッケージのコメント）を優先的に表示し、通常のライブラリパッケージに対してはパッケージのドキュメンテーションを表示するように切り替えることを目的としています。

前提知識の解説

godoc: Go言語のソースコードからドキュメンテーションを生成し、表示するためのツールです。Goの標準ライブラリやサードパーティのパッケージのドキュメンテーションを閲覧する際に広く利用されます。ソースコード内のコメント（特にパッケージ、関数、型、変数などの宣言の直前にあるコメント）を解析して、HTML形式やプレーンテキスト形式で表示します。
Goのパッケージとコマンド:
- パッケージ (Package): Goのコードはパッケージにまとめられます。パッケージは関連する機能の集合であり、再利用可能なコードの単位です。他のパッケージからインポートして利用されます。
- コマンド (Command): main パッケージとして定義され、main 関数を持つGoプログラムは、コンパイルされると実行可能なコマンド（バイナリ）になります。これらのプログラムは、ライブラリとして他のプログラムからインポートされるのではなく、単体で実行されることを意図しています。
main パッケージ: Goプログラムのエントリポイントとなるパッケージです。main パッケージは、go build コマンドによって実行可能なバイナリを生成します。
package.html と package.txt: godoc ツールがドキュメンテーションを生成する際に使用するテンプレートファイルです。
- package.html: HTML形式のドキュメンテーションを生成するためのテンプレート。
- package.txt: プレーンテキスト形式のドキュメンテーションを生成するためのテンプレート。これらのテンプレートは、Goの text/template および html/template パッケージの構文を使用しており、godoc が解析したソースコードの情報（PDoc など）を埋め込んで最終的な出力を生成します。
$.IsMain: godoc のテンプレート内で利用できるコンテキスト変数の一つで、現在処理しているパッケージが main パッケージ（つまりコマンド）であるかどうかを示すブール値です。

技術的詳細

このコミットの技術的な核心は、godoc がドキュメンテーションを生成する際に使用するテンプレート (package.html と package.txt) 内の条件分岐ロジックを変更することにあります。

変更前は、テンプレート内で {{if not $.IsMain}} という条件が使われていました。これは「もし main パッケージでなければ（つまり通常のライブラリパッケージであれば）」という条件で、その中にパッケージドキュメンテーションを表示するロジックが記述されていました。そして、else ブロックにコマンドのドキュメンテーションを表示するロジックがありました。

このロジックの問題点は、main パッケージの場合に else ブロックが実行され、コマンドのドキュメンテーションが表示されるのは正しいのですが、通常のパッケージの場合にパッケージドキュメンテーションが表示される部分が、コマンドのドキュメンテーションと構造的に異なっていたり、意図しない情報が含まれていたりする可能性がありました。

このコミットでは、この条件分岐を {{if $.IsMain}} に変更し、その直下にコマンドのドキュメンテーションを表示するロジックを配置しました。そして、else ブロックに通常のパッケージドキュメンテーションを表示するロジックを移動させました。これにより、main パッケージであるかどうかに応じて、より明確かつ意図した通りのドキュメンテーション表示が実現されます。

具体的には、package.html では、$.IsMain が真の場合（コマンドの場合）に {{comment_html .Doc}} を使ってコマンドのドキュメンテーション（main パッケージのコメント）を直接表示し、それ以外の場合（通常のパッケージの場合）に import パスやショートナビゲーション、関数リストなどを含むパッケージドキュメンテーションの構造を表示するように変更されています。

同様に、package.txt でも、$.IsMain が真の場合に "COMMAND DOCUMENTATION" というヘッダーと {{comment_text .Doc}} を表示し、それ以外の場合に "PACKAGE DOCUMENTATION" というヘッダーとパッケージ名、インポートパスなどを表示するように変更されています。

この変更により、godoc はコマンドに対しては簡潔なコマンド説明を、ライブラリパッケージに対しては詳細なパッケージ情報を提供するようになり、ユーザーエクスペリエンスが向上します。

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

diff --git a/lib/godoc/package.html b/lib/godoc/package.html
index 1df1f9151d..1fe6e7595f 100644
--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -10,7 +10,11 @@
  	correspond to Go identifiers).\n -->
 {{with .PDoc}}
-	{{if not $.IsMain}}
+	{{if $.IsMain}}
+		{{/* command documentation */}}
+		{{comment_html .Doc}}
+	{{else}}
+		{{/* package documentation */}}
 		<div id="short-nav">
 			<dl>
 			<dd><code>import "{{html .ImportPath}}"</code></dd>
@@ -160,8 +164,6 @@
 				{{example_html $name $.Examples $.Fset}}
 			{{end}}
 		{{end}}
-	{{else}}  {{/* not a package; is a command */}}
-		{{comment_html .Doc}}
 	{{end}}
 
 	{{with $.Notes}}
diff --git a/lib/godoc/package.txt b/lib/godoc/package.txt
index 94239ca1a5..de40a749b6 100644
--- a/lib/godoc/package.txt
+++ b/lib/godoc/package.txt
@@ -2,14 +2,15 @@
 
 ---------------------------------------
 
-*/}}{{with .PDoc}}{{if not $.IsMain}}PACKAGE
+*/}}{{with .PDoc}}{{if $.IsMain}}COMMAND DOCUMENTATION
+\
+{{comment_text .Doc "    " "\t"}}
+{{else}}PACKAGE DOCUMENTATION
 
 package {{.Name}}
     import "{{.ImportPath}}"
 
-{{else}}COMMAND DOCUMENTATION
-\
-{{end}}{{comment_text .Doc "    " "\t"}}
+{{comment_text .Doc "    " "\t"}}
 {{example_text "" $.Examples $.Fset "    "}}{{/*
 
 ---------------------------------------
@@ -58,7 +59,7 @@ TYPES
 {{end}}{{range .Methods}}{{node .Decl $.Fset}}
 {{comment_text .Doc "    " "\t"}}
 {{$name := printf "%s_%s" $tname .Name}}{{example_text $name $.Examples $.Fset "    "}}
-{{end}}{{end}}{{end}}{{/*
+{{end}}{{end}}{{end}}{{end}}{{/*
 
 ---------------------------------------

コアとなるコードの解説

`lib/godoc/package.html` の変更

変更前:
```
{{if not $.IsMain}}
	
	...
{{else}}  {{/* not a package; is a command */}}
	{{comment_html .Doc}}
{{end}}
```
$.IsMain が false の場合（通常のパッケージ）にパッケージドキュメンテーションを表示し、true の場合（コマンド）に comment_html .Doc でコマンドのドキュメンテーションを表示していました。
変更後:
```
{{if $.IsMain}}
	{{/* command documentation */}}
	{{comment_html .Doc}}
{{else}}
	{{/* package documentation */}}
	<div id="short-nav">
	...
{{end}}
```
条件分岐の if と else の内容が入れ替わりました。$.IsMain が true の場合（コマンド）に comment_html .Doc を表示し、false の場合（通常のパッケージ）にパッケージドキュメンテーションの構造（short-nav など）を表示するように修正されました。これにより、コマンドとパッケージのドキュメンテーション表示ロジックがより直感的かつ意図通りに機能するようになりました。

`lib/godoc/package.txt` の変更

変更前:
```
{{if not $.IsMain}}PACKAGE

package {{.Name}}
    import "{{.ImportPath}}"

{{else}}COMMAND DOCUMENTATION

{{end}}{{comment_text .Doc "    " "\t"}}
```
package.html と同様に、$.IsMain が false の場合に "PACKAGE" ヘッダーとパッケージ情報を表示し、true の場合に "COMMAND DOCUMENTATION" ヘッダーを表示していました。comment_text .Doc は条件分岐の外にあり、どちらの場合でも表示されていました。
変更後:
```
{{if $.IsMain}}COMMAND DOCUMENTATION

{{comment_text .Doc "    " "\t"}}
{{else}}PACKAGE DOCUMENTATION

package {{.Name}}
    import "{{.ImportPath}}"

{{comment_text .Doc "    " "\t"}}
{{end}}
```
こちらも if と else の内容が入れ替わりました。$.IsMain が true の場合（コマンド）に "COMMAND DOCUMENTATION" ヘッダーと comment_text .Doc を表示し、false の場合（通常のパッケージ）に "PACKAGE DOCUMENTATION" ヘッダーとパッケージ情報、そして comment_text .Doc を表示するように修正されました。これにより、プレーンテキスト形式のドキュメンテーションでも、コマンドとパッケージで適切な情報が適切な順序で表示されるようになりました。

これらの変更は、godoc が生成するドキュメンテーションの正確性とユーザーエクスペリエンスを向上させるための重要な修正です。

参考にした情報源リンク

特になし。コミットメッセージと差分、およびGo言語のドキュメンテーションツールの一般的な知識に基づいて解説を生成しました。

comemo