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

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

このコミットは、Go言語のドキュメント関連ファイルから、もはや使用されていないプログラムやスクリプトを削除し、既存のスクリプトを更新することを目的としています。具体的には、go_tutorial の削除に伴い不要となったサンプルプログラム群と、makehtml スクリプトが削除されました。また、doc/progs/run スクリプトが更新され、残されたドキュメントプログラムのコンパイルとテストを適切に行うように修正されています。これにより、ドキュメント関連のファイルが整理され、メンテナンス性が向上しました。

コミット

commit efbd79ce5a1f200c02bd18e59b4e2c11808e6ab4
Author: Shenghou Ma <minux.ma@gmail.com>
Date:   Wed Mar 7 08:05:10 2012 +1100

    doc: remove unsued progs and makehtml script, update progs/run
            Due to removal of go_tutorial, unused programs are removed.
            makehtml is unnecessary (it also gives wrong messages when
            the destination file doesn't exist)
            progs/run now compiles all remaining programs under doc/progs.
            Fixes #3076 (again)
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/5755053
---
 doc/Makefile              |  5 +++--
 doc/makehtml              | 17 --------------
 doc/progs/helloworld.go   | 11 ---------
 doc/progs/helloworld3.go  | 21 -----------------
 doc/progs/print.go        | 23 ------------------
 doc/progs/print_string.go | 21 -----------------
 doc/progs/run             | 11 +++++++--
 doc/progs/server.go       | 51 ----------------------------------------
 doc/progs/server1.go      | 56 --------------------------------------------
 doc/progs/sort.go         | 59 -----------------------------------------------
 doc/progs/strings.go      | 17 --------------
 doc/progs/sum.go          | 21 -----------------
 12 files changed, 13 insertions(+), 300 deletions(-)

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

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

元コミット内容

doc: remove unsued progs and makehtml script, update progs/run （ドキュメント: 未使用のプログラムと makehtml スクリプトを削除し、progs/run を更新）

Due to removal of go_tutorial, unused programs are removed. （go_tutorial の削除に伴い、未使用のプログラムが削除されました。）

makehtml is unnecessary (it also gives wrong messages when the destination file doesn't exist) （makehtml は不要です（また、出力先ファイルが存在しない場合に誤ったメッセージを出力していました））

progs/run now compiles all remaining programs under doc/progs. （progs/run は doc/progs 下の残りの全てのプログラムをコンパイルするようになりました。）

Fixes #3076 (again) （Issue #3076 を修正（再度））

変更の背景

このコミットの主な背景は、Go言語のドキュメント構造の変更と、それに伴う不要なファイルの整理です。

  1. go_tutorial の削除: コミットメッセージに明記されているように、go_tutorial が削除されたことが、多くのサンプルプログラムが不要になった直接的な原因です。Go言語のドキュメントは進化しており、特定のチュートリアルが廃止されたり、内容が統合されたりすることがあります。この場合、go_tutorial に関連付けられていた多数の小さなGoプログラムが、もはやドキュメントの一部として必要なくなりました。

  2. makehtml スクリプトの非効率性と問題点: makehtml スクリプトは、GoのドキュメントをHTML形式に変換するために使用されていましたが、コミットメッセージによると「不要」であり、「出力先ファイルが存在しない場合に誤ったメッセージを出力する」という問題も抱えていました。これは、ドキュメント生成プロセスにおける潜在的なバグや混乱の原因となっていました。より堅牢で効率的な tmpltohtml というGoプログラムが既に存在していたため、makehtml はその役割を終え、削除されることになりました。

  3. progs/run の更新: 上記の変更により、doc/progs ディレクトリ内のプログラム構成が大きく変わったため、これらのプログラムをコンパイル・実行・テストするためのスクリプトである progs/run も更新する必要がありました。これにより、残された有効なサンプルプログラムが引き続き正しく機能することを確認できます。

  4. Issue #3076 の修正 (再度): コミットメッセージには「Fixes #3076 (again)」とあります。これは、以前にも Issue #3076 に関連する修正が行われたが、今回の変更で再度その問題に対処していることを示唆しています。GoプロジェクトのIssueトラッカーで #3076 を検索すると、複数のプロジェクトで異なる内容のIssueが存在することがわかりますが、このコミットの文脈では、Go言語のドキュメント関連の特定の不具合や非効率性に関するものと考えられます。

これらの背景から、このコミットはGo言語のドキュメントシステムをよりクリーンで効率的、かつ正確な状態に保つためのメンテナンス作業の一環であると理解できます。

前提知識の解説

このコミットを理解するためには、以下のGo言語およびドキュメント生成に関する基本的な知識が必要です。

  1. Go言語のドキュメント構造: Go言語の公式ドキュメントは、単にコードコメントから生成される godoc だけでなく、チュートリアル、ブログ記事、仕様書など、様々な形式で提供されています。これらは通常、doc ディレクトリ以下に配置され、特定のツールによってHTMLなどの形式に変換されます。

  2. go_tutorial: これは、Go言語の初期のチュートリアルの一つであったと考えられます。Go言語は継続的に進化しており、ドキュメントもそれに合わせて更新されます。古いチュートリアルが新しいものに置き換えられたり、内容が統合されたりすることはよくあります。

  3. Makefile: Unix系のシステムでプログラムのビルドやドキュメントの生成など、一連のタスクを自動化するために使われるツールです。Makefile には、ターゲット（例: all, clean, %.html）と、そのターゲットを達成するためのコマンドが記述されます。このコミットでは、doc/Makefile が変更されており、ドキュメント生成のワークフローが更新されたことを示しています。

  4. tmpltohtml と makehtml:

    • tmpltohtml: これはGo言語で書かれたプログラム（tmpltohtml.go）で、Goのテンプレートファイル（.tmpl 拡張子を持つファイル）を読み込み、HTML出力を生成する役割を担っていました。Goの標準ライブラリである text/template や html/template パッケージを利用して、テンプレート内のGoプログラムのソースコードをHTMLに埋め込む機能などを持っていました。これは、Goのドキュメント内でコード例を整形して表示するために使われていたと考えられます。
    • makehtml: これはシェルスクリプトであり、tmpltohtml を呼び出して .tmpl ファイルからHTMLファイルを生成するラッパーのような役割を果たしていました。コミットメッセージにあるように、このスクリプト自体に問題があったり、tmpltohtml を直接呼び出すことで十分になったりしたため、不要と判断されました。

  5. doc/progs ディレクトリ: このディレクトリには、Go言語のドキュメント内で使用されるサンプルプログラムやコード例が格納されていました。これらのプログラムは、特定の概念や機能を示すために使われます。

  6. progs/run スクリプト: doc/progs ディレクトリ内のサンプルプログラムをビルドし、テストするためのシェルスクリプトです。ドキュメント内のコード例が常に正しく動作することを確認するために重要です。

  7. Issue #3076: GitリポジトリにおけるIssueトラッカーの参照です。通常、特定のバグや機能改善の要望がIssueとして登録され、そのIssueを解決するコミットには Fixes #<issue_number> のように記述されます。このコミットでは「(again)」と付いていることから、過去にもこのIssueに関連する修正があったものの、今回の変更で再度対処が必要になったことを示唆しています。

これらの要素を理解することで、このコミットがGo言語のドキュメント生成パイプラインの改善と、それに伴うコードベースのクリーンアップであるという全体像を把握できます。

技術的詳細

このコミットの技術的詳細は、主に以下の3つの側面に集約されます。

  1. makehtml スクリプトの廃止と tmpltohtml への一本化:

    • 変更前: doc/Makefile は makehtml スクリプトを呼び出して .tmpl ファイルからHTMLを生成していました。makehtml はシェルスクリプトであり、内部で tmpltohtml を実行していました。
    • 変更後: makehtml スクリプト自体が削除されました。doc/Makefile は直接 tmpltohtml プログラムを呼び出すように変更されました。これにより、中間的なシェルスクリプトのオーバーヘッドと、makehtml が抱えていた「出力先ファイルが存在しない場合に誤ったメッセージを出力する」という問題が解消されます。tmpltohtml はGoで書かれたプログラムであり、より堅牢で予測可能な動作が期待できます。これは、ドキュメント生成プロセスの簡素化と信頼性向上に寄与します。

  2. go_tutorial 関連の未使用プログラムの削除:

    • doc/progs/helloworld.go, helloworld3.go, print.go, print_string.go, server.go, server1.go, sort.go, strings.go, sum.go といった多数のGoプログラムファイルが削除されました。これらのファイルは、以前は go_tutorial の一部として、またはその関連でドキュメントに組み込まれていましたが、go_tutorial の廃止に伴い不要となりました。
    • これらのプログラムは、Go言語の基本的な機能（Hello World、入出力、並列処理、ソート、文字列操作など）を示すためのシンプルな例であったと考えられます。コードベースからこれらを削除することで、リポジトリのサイズが削減され、メンテナンス対象のファイルが減り、Goプロジェクト全体のフットプリントが小さくなります。

  3. doc/progs/run スクリプトの更新:

    • doc/progs/run は、doc/progs ディレクトリ内のGoプログラムをビルドし、テストするためのシェルスクリプトです。
    • 変更前は、特定のプログラム群（defer_panic_recover, effective_go, error_handling, slices, go1）のみを対象としていました。
    • 変更後: law_of_reflection という新しいプログラム群（interface, interface2）が追加され、all 変数に含められるようになりました。これにより、Goの「リフレクションの法則」に関する新しいサンプルプログラムも run スクリプトによってビルド・テストされるようになります。
    • また、一時ファイルのパス指定が TMPFILE="/tmp/gotest3.$USER" から TMPFILE="${TMPDIR:-/tmp}/gotest3.$USER" に変更されました。これは、環境変数 TMPDIR が設定されている場合はそのディレクトリを使用し、設定されていない場合は /tmp を使用するという、より柔軟でポータブルな一時ファイルパスの指定方法です。これにより、異なるシステム環境でのスクリプトの互換性が向上します。
    • testit interface2 "^type: float64$" という行が追加され、interface2 プログラムのテストが明示的に実行されるようになりました。これは、新しいリフレクション関連のサンプルが正しく動作することを確認するためのものです。

これらの技術的変更は、Go言語のドキュメント生成およびテストインフラストラクチャの合理化と近代化を反映しています。不要なコンポーネントを削除し、残されたコンポーネントをより効率的かつ堅牢にすることで、開発ワークフローが改善され、ドキュメントの品質維持が容易になります。

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

このコミットでは、以下のファイルが変更されています。

  • doc/Makefile: 5行変更 (3追加, 2削除)
  • doc/makehtml: 17行削除 (ファイル全体が削除)
  • doc/progs/helloworld.go: 11行削除 (ファイル全体が削除)
  • doc/progs/helloworld3.go: 21行削除 (ファイル全体が削除)
  • doc/progs/print.go: 23行削除 (ファイル全体が削除)
  • doc/progs/print_string.go: 21行削除 (ファイル全体が削除)
  • doc/progs/run: 11行変更 (7追加, 4削除)
  • doc/progs/server.go: 51行削除 (ファイル全体が削除)
  • doc/progs/server1.go: 56行削除 (ファイル全体が削除)
  • doc/progs/sort.go: 59行削除 (ファイル全体が削除)
  • doc/progs/strings.go: 17行削除 (ファイル全体が削除)
  • doc/progs/sum.go: 21行削除 (ファイル全体が削除)

合計で12ファイルが変更され、13行が追加、300行が削除されています。これは主にファイルの削除によるものです。

コアとなるコードの解説

doc/Makefile の変更

--- a/doc/Makefile
+++ b/doc/Makefile
@@ -16,4 +16,7 @@ tmpltohtml: tmpltohtml.go
 	go build tmpltohtml.go
 
 %.html: %.tmpl tmpltohtml
-	./makehtml $*.tmpl
+	./tmpltohtml $*.tmpl > $@
+
+clean:
+	rm -f $(HTML) tmpltohtml

この変更は、HTML生成プロセスの中核的な変更を示しています。

  • - ./makehtml $*.tmpl の行が削除され、makehtml スクリプトへの依存がなくなりました。
  • + ./tmpltohtml $*.tmpl > $@ の行が追加され、tmpltohtml プログラムを直接呼び出すようになりました。$*.tmpl は .tmpl 拡張子を持つ入力ファイル名を表し、$@ は生成されるHTMLファイル名を表します。出力はリダイレクト (>) されてHTMLファイルに書き込まれます。
  • clean: ターゲットとそれに続く rm -f $(HTML) tmpltohtml が追加されました。これは、ビルドされたHTMLファイルと tmpltohtml 実行ファイルをクリーンアップするためのルールです。これにより、ビルド環境の整理が容易になります。

doc/makehtml の削除

--- a/doc/makehtml
+++ /dev/null
@@ -1,17 +0,0 @@
-#!/bin/sh
-# Copyright 2009 The Go Authors. All rights reserved.
-# Use of this source code is governed by a BSD-style
-# license that can be found in the LICENSE file.
-
-set -e
-
-TMPL=${1:-effective_go.tmpl}                        # input file
-HTML=$(dirname $TMPL)/$(basename $TMPL .tmpl).html # output file
-
-if ! test -w $HTML
-then
-	echo 1>&2 makehtml: cannot open $HTML for write
-	exit 1
-fi
-
-make tmpltohtml && ./tmpltohtml $TMPL > $HTML

このファイルは完全に削除されました。これは、doc/Makefile の変更と合わせて、makehtml スクリプトが不要になったことを明確に示しています。このスクリプトは、tmpltohtml を呼び出すラッパーとして機能していましたが、直接 tmpltohtml を使用することで、この中間層が不要になりました。

doc/progs/run の変更

--- a/doc/progs/run
+++ b/doc/progs/run
@@ -23,14 +23,19 @@ error_handling="
 	error4
 "
 
-all=$(echo $defer_panic_recover  $effective_go $error_handling slices go1)
+law_of_reflection="
+	interface
+	interface2
+"
+
+all=$(echo $defer_panic_recover $effective_go $error_handling $law_of_reflection slices go1)
 
 for i in $all; do
 	go build $i.go
 done
 
 # Write to temporary file to avoid mingw bash bug.
-TMPFILE="/tmp/gotest3.$USER"
+TMPFILE="${TMPDIR:-/tmp}/gotest3.$USER"
 
 function testit {
 	./$1 >"$TMPFILE" 2>&1 || true
@@ -50,4 +55,6 @@ testit eff_sequence '^\\[-1 2 6 16 44\\]$'\n
 testit go1 '^Christmas is a holiday: true Sleeping for 0.123s.*go1.go already exists$'\n
 
+testit interface2 "^type: float64$"\n
+\n
 rm -f $all "$TMPFILE"

このスクリプトは、doc/progs ディレクトリ内のGoプログラムのビルドとテストを管理します。

  • law_of_reflection という新しいシェル変数と、それに含まれる interface および interface2 というプログラム名が追加されました。これらはGoのリフレクションに関する新しいサンプルプログラムであると考えられます。
  • all 変数の定義が更新され、$law_of_reflection が追加されました。これにより、interface.go と interface2.go もビルド対象に含まれるようになります。
  • 一時ファイルパスの指定が TMPFILE="/tmp/gotest3.$USER" から TMPFILE="${TMPDIR:-/tmp}/gotest3.$USER" に変更されました。これは、環境変数 TMPDIR が設定されていればそれを使用し、そうでなければ /tmp を使用するという、よりポータブルな方法です。
  • testit interface2 "^type: float64$" という新しいテストケースが追加されました。これは、interface2 プログラムの出力が正規表現 ^type: float64$ にマッチするかどうかを検証します。これにより、新しいリフレクションのサンプルが期待通りに動作することを確認します。

その他のGoプログラムファイルの削除

doc/progs/helloworld.go, helloworld3.go, print.go, print_string.go, server.go, server1.go, sort.go, strings.go, sum.go は全て完全に削除されました。これらのファイルは、go_tutorial の削除に伴い、もはやドキュメントの例として必要なくなったためです。これにより、コードベースが整理され、不要なファイルのメンテナンスが不要になります。

これらの変更は全体として、Go言語のドキュメント生成およびテストのワークフローを合理化し、より効率的でクリーンな状態に保つことを目的としています。

関連リンク

参考にした情報源リンク