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

このコミットは、Go言語の公式ツールである cmd/go から go doc コマンドを削除する変更を記録しています。この変更は、go doc がその目的において「ほとんど役に立たず、混乱を招く」と判断されたためであり、代わりに godoc ツール自体の改善に注力するという方針転換を示しています。

コミット

commit 71eae5a46a1ecb21dfe5eacd42fcdad8145fac52
Author: Rob Pike <r@golang.org>
Date:   Fri Aug 16 10:30:05 2013 +1000

    cmd/go: delete 'go doc'
    It's next to useless and confusing as well. Let's make godoc better instead.
    
    Fixes #4849.
    
    R=golang-dev, dsymonds, adg, rogpeppe, rsc
    CC=golang-dev
    https://golang.org/cl/12974043

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

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

元コミット内容

cmd/go: delete 'go doc'
It's next to useless and confusing as well. Let's make godoc better instead.

Fixes #4849.

R=golang-dev, dsymonds, adg, rogpeppe, rsc
CC=golang-dev
https://golang.org/cl/12974043

変更の背景

このコミットの背景には、Go言語のドキュメンテーションツールに関する設計思想の明確化があります。Go言語には、ソースコードからドキュメンテーションを生成し、表示するための godoc ツールが古くから存在します。一方で、go コマンド（cmd/go）にも go doc というサブコマンドが存在していました。

コミットメッセージにある「It's next to useless and confusing as well. Let's make godoc better instead.」（ほとんど役に立たず、混乱を招く。代わりに godoc をより良くしよう）という記述が、この変更の核心を突いています。

具体的な問題点としては、以下が挙げられます。

1. 機能の重複と混乱: go doc と godoc はどちらもドキュメンテーションを表示する機能を持っていましたが、その機能範囲や使い勝手に違いがありました。これにより、ユーザーはどちらを使うべきか、それぞれの違いは何かについて混乱を招いていました。特に go doc は godoc の機能の一部をラップしているに過ぎず、godoc が提供する豊富な機能（例えば、HTTPサーバーとしてドキュメントを提供する機能など）をカバーしていませんでした。
2. 限定的な機能: go doc は主にパッケージのドキュメントを表示することに特化しており、godoc が提供するような、より詳細なシンボルレベルのドキュメント表示や、ローカルのGoモジュール全体をブラウズする機能は持っていませんでした。
3. 開発リソースの集中: 2つの類似したコマンドを維持・改善するよりも、より強力で汎用的な godoc ツールに開発リソースを集中させることで、Go言語全体のドキュメンテーション体験を向上させるという戦略的な判断がありました。

この変更は、Go言語のツールセットをよりシンプルで、かつ強力なものにするための継続的な取り組みの一環として行われました。関連するIssueである Fixes #4849 は、この go doc コマンドの削除に関する議論や提案がなされていたことを示唆しています。

前提知識の解説

このコミットを理解するためには、Go言語のドキュメンテーションシステムと、go コマンドおよび godoc ツールの役割について理解しておく必要があります。

Go言語のドキュメンテーション

Go言語は、ソースコードに直接ドキュメンテーションコメントを記述する文化を強く推奨しています。これは、JavaDocやJSDocのような形式に似ていますが、よりシンプルで、特定のフォーマット規則に従います。

• パッケージコメント: package 宣言の直前に記述されたコメントは、パッケージ全体のドキュメントとして扱われます。
• シンボルコメント: エクスポートされた（大文字で始まる）関数、変数、定数、型、メソッドの宣言の直前に記述されたコメントは、そのシンボルのドキュメントとして扱われます。

これらのドキュメンテーションコメントは、Goのツールによって自動的に解析され、整形されたドキュメントとして表示されます。

go コマンド (cmd/go)

go コマンドは、Go言語のビルド、テスト、依存関係管理、コードフォーマットなど、開発ワークフローのほとんどを担う統合ツールです。go build, go test, go run, go get, go fmt など、多くのサブコマンドを持っています。 このコミット以前は、go doc というサブコマンドも存在していました。これは go コマンドの一部として提供され、Goのドキュメントを表示する機能を持っていました。

godoc ツール

godoc は、Go言語のソースコードからドキュメンテーションを抽出し、整形して表示するためのスタンドアロンツールです。godoc は以下の主要な機能を提供します。

• コマンドラインでのドキュメント表示: 特定のパッケージやシンボルのドキュメントをターミナルに表示できます。
• HTTPサーバーとしてのドキュメント提供: godoc -http=:6060 のように実行することで、ローカルのGoワークスペース内のすべてのドキュメントをWebブラウザ経由で閲覧できるHTTPサーバーを起動できます。これは、pkg.go.dev（旧 godoc.org）のようなオンラインのGoドキュメントサイトの基盤ともなっています。
• 詳細な情報表示: パッケージ、ファイル、関数、変数、型、メソッドなど、Goコードのあらゆる要素に関する詳細なドキュメントを表示できます。

go doc と godoc の関係性（削除前）

このコミット以前の go doc は、内部的に godoc ツールを呼び出すラッパーのような役割を果たしていました。つまり、go doc を実行すると、go コマンドが godoc バイナリを探し、適切な引数を与えて実行していました。しかし、このラッパー機能は godoc の全機能をカバーしておらず、ユーザーにとっては go doc と godoc のどちらを使うべきか、あるいは両者の違いが何であるかが不明瞭でした。

技術的詳細

このコミットの技術的詳細は、主に cmd/go ツール内部での go doc コマンドの定義と、それに関連するコードの削除に集約されます。

cmd/go は、Go言語で書かれた単一のバイナリであり、その内部で様々なサブコマンドを定義しています。各サブコマンドは Command 構造体として表現され、その Run フィールドに実際の処理を行う関数が割り当てられています。

go doc コマンドの削除は、以下の3つの主要なファイルに影響を与えています。

1. src/cmd/go/doc.go:

   • このファイルは、go doc コマンドのヘルプメッセージや使用方法に関するドキュメンテーションを定義していました。
   • コミットでは、go doc に関する説明文が完全に削除されています。これは、go help コマンドを実行した際に表示されるヘルプメッセージから doc コマンドが消えることを意味します。

2. src/cmd/go/fmt.go:

   • Goのツール群では、fmt.go のようなファイルが複数のコマンドの初期化や共通処理を担うことがあります。
   • このファイルには、cmdDoc という Command 構造体の定義と、runDoc という go doc コマンドの実際の処理を行う関数が含まれていました。
   • runDoc 関数は、exec.LookPath("godoc") を使って godoc バイナリの存在を確認し、その後 godoc を呼び出してドキュメントを表示するロジックを持っていました。
   • コミットでは、cmdDoc 構造体と runDoc 関数の定義、および cmdDoc を init 関数で初期化する行がすべて削除されています。これにより、go doc コマンドの実装が完全にGoツールチェーンから取り除かれました。

3. src/cmd/go/main.go:

   • main.go は cmd/go ツールのエントリポイントであり、利用可能なすべてのサブコマンドのリストを定義しています。
   • var commands = []*Command{...} というスライスに、cmdBuild, cmdClean, cmdFmt など、すべてのサブコマンドの Command 構造体へのポインタが格納されています。
   • コミットでは、この commands スライスから cmdDoc への参照が削除されています。これにより、go コマンドが起動された際に、doc というサブコマンドが認識されなくなり、実行できなくなります。

この変更は、単にヘルプメッセージを削除するだけでなく、go doc コマンドの実装コード自体を完全に削除することで、Goツールチェーンのバイナリサイズをわずかに削減し、コードベースの複雑さを軽減する効果も持っています。

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

このコミットにおけるコアとなるコードの変更箇所は、go コマンドのサブコマンド定義と、go doc コマンドの実装そのものの削除です。

src/cmd/go/doc.go

--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -16,7 +16,6 @@ The commands are:
 
     build       compile packages and dependencies
     clean       remove object files
-    doc         run godoc on package sources
     env         print Go environment information
     fix         run go tool fix on packages
     fmt         run gofmt on package sources
@@ -162,26 +161,6 @@ The -x flag causes clean to print remove commands as it executes them.
 For more about specifying packages, see 'go help packages'.
 
 
-Run godoc on package sources
-
-Usage:
-
-	go doc [-n] [-x] [packages]
-
-Doc runs the godoc command on the packages named by the
-import paths.
-
-For more about godoc, see 'godoc godoc'.
-For more about specifying packages, see 'go help packages'.
-
-The -n flag prints commands that would be executed.
-The -x flag prints commands as they are executed.
-
-To run godoc with specific options, run godoc itself.
-
-See also: go fix, go fmt, go vet.
-
-
 Print Go environment information
 
 Usage:
@@ -229,7 +208,7 @@ The -x flag prints commands as they are executed.
 
 To run gofmt with specific options, run gofmt itself.
 
-See also: go doc, go fix, go vet.
+See also: go fix, go vet.
 
 
 Download and install packages and dependencies
@@ -880,5 +859,3 @@ See the documentation of the testing package for more information.
 
 */
 package main
-
-// NOTE: cmdDoc is in fmt.go.

src/cmd/go/fmt.go

--- a/src/cmd/go/fmt.go
+++ b/src/cmd/go/fmt.go
@@ -4,11 +4,8 @@
 
 package main
 
-import "os/exec"
-
 func init() {
  	addBuildFlagsNX(cmdFmt)
-\taddBuildFlagsNX(cmdDoc)
 }
 
 var cmdFmt = &Command{
@@ -27,7 +24,7 @@ The -x flag prints commands as they are executed.
 
 To run gofmt with specific options, run gofmt itself.
 
-See also: go doc, go fix, go vet.
+See also: go fix, go vet.
  	`,
 }
 
@@ -39,42 +36,3 @@ func runFmt(cmd *Command, args []string) {
  		run(stringList("gofmt", "-l", "-w", relPaths(pkg.allgofiles)))
  	}
 }
-
-var cmdDoc = &Command{
-	Run:       runDoc,
-	UsageLine: "doc [-n] [-x] [packages]",
-	Short:     "run godoc on package sources",
-	Long: `
-Doc runs the godoc command on the packages named by the
-import paths.
-
-For more about godoc, see 'godoc godoc'.
-For more about specifying packages, see 'go help packages'.
-
-The -n flag prints commands that would be executed.
-The -x flag prints commands as they are executed.
-
-To run godoc with specific options, run godoc itself.
-
-See also: go fix, go fmt, go vet.
-	`,
-}
-
-func runDoc(cmd *Command, args []string) {
-	_, err := exec.LookPath("godoc")
-	if err != nil {
-		errorf("go doc: can't find godoc; to install:\n\tgo get code.google.com/p/go.tools/cmd/godoc")
-		return
-	}
-	for _, pkg := range packages(args) {
-		if pkg.ImportPath == "command-line arguments" {
-			errorf("go doc: cannot use package file list")
-			continue
-		}
-		if pkg.local {
-			run("godoc", pkg.Dir)
-		} else {
-			run("godoc", pkg.ImportPath)
-		}
-	}
-}

src/cmd/go/main.go

--- a/src/cmd/go/main.go
+++ b/src/cmd/go/main.go
@@ -76,7 +76,6 @@ func (c *Command) Runnable() bool {
 var commands = []*Command{
 	cmdBuild,
 	cmdClean,
-\tcmdDoc,
 	cmdEnv,
 	cmdFix,
 	cmdFmt,
@@ -213,8 +212,6 @@ var documentationTemplate = `// Copyright 2011 The Go Authors.  All rights reser
 
 {{end}}*/
 package main
-
-// NOTE: cmdDoc is in fmt.go.
 `
 
 // tmpl executes the given template text on data, writing the result to w.

コアとなるコードの解説

上記の差分から、以下の点が明確に読み取れます。

1. src/cmd/go/doc.go の変更:

   • doc コマンドに関する説明文が完全に削除されています。これは、go help や go help doc といったコマンドを実行しても、もはや go doc に関する情報が表示されないことを意味します。
   • See also: go doc, go fix, go vet. のような関連コマンドのリストからも go doc が削除され、他のコマンドのヘルプメッセージからも参照がなくなっています。

2. src/cmd/go/fmt.go の変更:

   • import "os/exec" が削除されています。これは、go doc コマンドが godoc バイナリを外部プロセスとして実行するために os/exec パッケージを使用していたため、その機能が不要になったことを示します。
   • func init() { ... addBuildFlagsNX(cmdDoc) ... } の行が削除されています。init 関数はパッケージが初期化される際に実行され、ここで cmdDoc コマンドにビルドフラグを追加する設定が行われていました。この行の削除は、cmdDoc がもはや存在しないことを反映しています。
   • 最も重要な変更は、var cmdDoc = &Command{...} と func runDoc(cmd *Command, args []string) { ... } の定義が完全に削除されたことです。
     • cmdDoc は go doc コマンドのメタデータ（名前、短い説明、長い説明、実行関数など）を保持する Command 構造体でした。
     • runDoc 関数は go doc コマンドが実行されたときに呼び出される実際のロジックを含んでいました。この関数は、godoc バイナリのパスを検索し、見つかった場合は godoc を適切な引数（パッケージパスやディレクトリ）で実行していました。godoc が見つからない場合は、インストール方法を案内するエラーメッセージを表示していました。
   • See also: go doc, go fix, go vet. のような関連コマンドのリストからも go doc が削除されています。

3. src/cmd/go/main.go の変更:

   • var commands = []*Command{...} というスライスから cmdDoc, の行が削除されています。この commands スライスは、go コマンドが認識するすべてのサブコマンドのリストを定義しています。この行の削除により、go コマンドは doc というサブコマンドを認識しなくなり、ユーザーが go doc を実行しようとすると「unknown command」エラーを返すようになります。
   • // NOTE: cmdDoc is in fmt.go. というコメントも削除されています。これは、cmdDoc がもはや存在しないため、その場所を注記する必要がなくなったためです。

これらの変更は、go doc コマンドの定義、実装、および go コマンドのサブコマンドリストからの参照を完全に削除することで、このコマンドをGoツールチェーンから完全に抹消しています。これにより、Go開発者はドキュメンテーションの表示には godoc ツールを直接使用することが推奨されるようになりました。

関連リンク

• Go Issue #4849: go doc コマンドの削除に関する議論が行われたGitHub Issue。このコミットメッセージに Fixes #4849 と記載されていることから、このIssueが直接的なトリガーとなったことがわかります。
  • https://github.com/golang/go/issues/4849
• Go Code Review CL 12974043: このコミットに対応するGoのコードレビューシステム（Gerrit）上の変更リスト。
  • https://golang.org/cl/12974043 (現在は go.googlesource.com にリダイレクトされます)
• godoc ツール: Go言語のドキュメンテーション生成・表示ツール。
  • https://pkg.go.dev/golang.org/x/tools/cmd/godoc (現在の godoc ツールのドキュメント)

参考にした情報源リンク

• Go言語の公式ドキュメンテーション:
  • https://go.dev/doc/
• go コマンドのドキュメンテーション:
  • https://go.dev/cmd/go/
• godoc コマンドのドキュメンテーション:
  • https://go.dev/cmd/godoc/
• Go言語のソースコードリポジトリ:
  • https://github.com/golang/go
• Go言語のコードレビューシステム (Gerrit):
  • https://go-review.googlesource.com/
• Go言語のIssueトラッカー:
  • https://github.com/golang/go/issues
• 過去の go doc と godoc の機能に関するコミュニティの議論やブログ記事 (具体的なURLは変動するため、一般的な参照として記載)
  • Go言語のツールに関する議論は、Goコミュニティのメーリングリストやフォーラムで活発に行われていました。I have generated the detailed technical explanation in Markdown format, following all the specified instructions and chapter structure. The output is sent to standard output as requested.