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

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

このコミットは、Go言語の公式ドキュメント生成ツールである tmpltohtml の挙動を修正し、ドキュメント内のGoプログラム例のフォーマットを gofmt に準拠させることを目的としています。具体的には、tmpltohtml がコードブロックから不要な空白を削除する際に、strings.TrimSpace を使用していたために改行以外の空白も削除されてしまう問題を修正し、strings.Trim(text, "\n") を使用して改行のみを削除するように変更しました。これにより、ドキュメントに埋め込まれるコード例の整形がより適切に行われるようになります。また、ドキュメント内のGoプログラム例自体も gofmt によって整形され、一貫したコードスタイルが保たれています。

コミット

  • コミットハッシュ: 468e692e38fd2442a64ba8d8e6c4a789e60c3891
  • 作者: Andrew Gerrand adg@golang.org
  • コミット日時: Mon Jan 9 20:05:34 2012 +1100

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

https://github.com/golang/go/commit/468e692e38fd2442a64ba8d8e6c4a789e60c3891

元コミット内容

doc: only trim newlines in tmpltohtml, gofmt progs

R=golang-dev, r, r
CC=golang-dev
https://golang.org/cl/5530048

変更の背景

この変更の背景には、Go言語のドキュメント生成プロセスにおけるコード例の表示に関する問題がありました。

  1. tmpltohtml の strings.TrimSpace の問題: Goのドキュメントは、HTML形式で提供されており、その中にGoのコード例が埋め込まれています。これらのコード例は、tmpltohtml.go というツールによって処理され、HTMLに変換されます。以前のバージョンでは、このツールがコードブロックのテキストを処理する際に strings.TrimSpace() 関数を使用していました。strings.TrimSpace() は、文字列の先頭と末尾からすべての空白文字（スペース、タブ、改行など）を削除します。しかし、ドキュメント内のコード例においては、行頭のインデント（スペースやタブ）はコードの構造を示す上で重要であり、これらが削除されてしまうとコードの可読性が損なわれるという問題がありました。このコミットの目的は、改行のみを削除し、インデントは保持することでした。

  2. Goプログラム例の gofmt 適用: Go言語には gofmt という公式のコードフォーマッタが存在し、Goコミュニティ全体で一貫したコードスタイルを維持するために広く利用されています。ドキュメント内のコード例も、この gofmt の規約に準拠していることが望ましいとされていました。しかし、一部の既存のコード例は gofmt の規約に完全に準拠していない可能性がありました。このコミットでは、ドキュメント内のGoプログラム例に対して gofmt を適用し、コードスタイルの一貫性を確保することも目的としています。

これらの問題に対処するため、tmpltohtml の空白削除ロジックが修正され、同時にドキュメント内のGoプログラム例が gofmt によって整形されました。

前提知識の解説

このコミットを理解するためには、以下のGo言語および関連ツールの基本的な知識が必要です。

  • Go言語のドキュメントシステム: Go言語の公式ドキュメントは、特定のマークアップとGoのコード例を組み合わせて生成されます。tmpltohtml.go は、これらのソースファイルから最終的なHTMLドキュメントを生成する内部ツールの一つです。
  • gofmt: gofmt はGo言語の公式なコードフォーマッタです。Goのソースコードを自動的に整形し、Goコミュニティ全体で統一されたコードスタイルを強制します。これにより、コードの可読性が向上し、チーム開発におけるスタイルの不一致による摩擦が減少します。gofmt は、インデント、空白、改行、括弧の位置など、多くのフォーマットルールを自動的に適用します。
  • strings.TrimSpace() 関数: Go言語の標準ライブラリ strings パッケージに含まれる関数です。この関数は、引数として与えられた文字列の先頭と末尾から、Unicodeで定義されているすべての空白文字（スペース、タブ、改行、キャリッジリターンなど）を削除した新しい文字列を返します。
  • strings.Trim(s, cutset string) 関数: Go言語の標準ライブラリ strings パッケージに含まれる別の関数です。この関数は、文字列 s の先頭と末尾から、cutset 文字列に含まれる任意の文字を削除した新しい文字列を返します。例えば、strings.Trim(" hello \n", " \n") は "hello" を返します。strings.TrimSpace と異なり、削除する文字を明示的に指定できるため、より細かい制御が可能です。

技術的詳細

このコミットの技術的な核心は、tmpltohtml.go における文字列トリミングロジックの変更と、ドキュメント内のGoプログラム例への gofmt の適用です。

  1. tmpltohtml.go の変更: 以前の tmpltohtml.go では、ドキュメントに埋め込むGoコードのテキストを処理する際に、strings.TrimSpace(text) を使用していました。これは、コードブロックの先頭と末尾にある不要な空白（特に改行）を削除することを意図していました。しかし、strings.TrimSpace は改行だけでなく、スペースやタブといったインデントも削除してしまいます。これにより、HTMLとしてレンダリングされたコード例のインデントが失われ、コードの構造が分かりにくくなるという副作用がありました。

    このコミットでは、この問題を解決するために text = strings.Trim(text, "\n") に変更されました。

    • strings.Trim(text, "\n") は、文字列 text の先頭と末尾から、指定された cutset である "\n"（改行文字）のみを削除します。
    • これにより、コードブロックの先頭と末尾にある余分な改行は削除されますが、コード行の先頭にあるインデント（スペースやタブ）はそのまま保持されます。
    • 結果として、ドキュメントに表示されるGoコード例は、適切なインデントを保ちつつ、不要な改行が取り除かれた状態で表示されるようになります。これは、コードの可読性を高め、Goの標準的なフォーマットに近い形でコード例を提示するために非常に重要です。

  2. Goプログラム例の gofmt 適用: コミットメッセージの「gofmt progs」が示すように、doc/progs/ ディレクトリ以下のGoプログラム例のファイル群に対して gofmt が実行されました。これにより、これらのファイル内のコードは gofmt の規約に従って自動的に整形されています。

    • 具体的には、インデントの統一、演算子やキーワードの周りの空白の調整、不要な空行の削除、インポート文のソートなどが自動的に行われます。
    • これにより、Goのドキュメントに掲載されているすべてのコード例が、Goコミュニティで推奨される一貫したスタイルで記述されることになり、読者がコードを理解しやすくなります。また、読者がこれらのコードをコピー＆ペーストして自分のプロジェクトで使用する際にも、すぐに gofmt に準拠したコードとして利用できるという利点があります。

これらの変更は、Go言語のドキュメントの品質と一貫性を向上させる上で重要な役割を果たしています。

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

このコミットにおける主要なコード変更は、doc/tmpltohtml.go ファイル内の1行の変更と、複数の doc/progs/ ディレクトリ以下のGoプログラムファイルのフォーマット変更です。

doc/tmpltohtml.go の変更

--- a/doc/tmpltohtml.go
+++ b/doc/tmpltohtml.go
@@ -114,7 +114,7 @@ func code(file string, arg ...interface{}) (string, error) {
 		return "", fmt.Errorf("incorrect code invocation: code %q %q", file, arg)
 	}
 	// Trim spaces from output.
-	text = strings.TrimSpace(text)
+	text = strings.Trim(text, "\n")
 	// Replace tabs by spaces, which work better in HTML.
 	text = strings.Replace(text, "\t", "    ", -1)
 	// Escape the program text for HTML.

この変更により、code 関数内でテキストをトリミングする際に、strings.TrimSpace から strings.Trim(text, "\n") へと変更されました。

doc/progs/ ディレクトリ以下のGoプログラムファイルの変更

以下のファイルで、gofmt によるコードフォーマットの変更が行われています。具体的な変更内容は、インデントの調整、空白の追加/削除、インポート文の並び替え、不要なコメント行の削除など、gofmt が適用されることによって生じる典型的な整形です。

  • doc/articles/error_handling.html (HTMLファイル内のコード例のインデント調整)
  • doc/go1.html (HTMLファイル内のコード例のインデント調整)
  • doc/go_tutorial.html (HTMLファイル内のコード例のインデント調整)
  • doc/progs/cat_rot13.go
  • doc/progs/defer2.go
  • doc/progs/echo.go
  • doc/progs/error.go
  • doc/progs/error2.go
  • doc/progs/error3.go
  • doc/progs/error4.go
  • doc/progs/go1.go
  • doc/progs/sortmain.go

これらのファイルでは、主にコードのインデントが統一され、gofmt の標準的なスタイルに準拠するように変更されています。例えば、HTMLファイル内のコード例では、<!--{{code ...}}--> の後に続くコードブロックのインデントが調整されています。Goのソースファイルでは、インポート文の順序が変更されたり、不要な空行が削除されたりしています。

コアとなるコードの解説

doc/tmpltohtml.go の code 関数

doc/tmpltohtml.go 内の code 関数は、GoのドキュメントをHTMLに変換する際に、特定のGoソースコードスニペットを抽出し、整形してHTMLに埋め込む役割を担っています。

変更前のコード:

text = strings.TrimSpace(text)

この行は、抽出されたGoコードのテキスト text の先頭と末尾から、すべての空白文字（スペース、タブ、改行など）を削除していました。これは、コードブロックの周囲にある余分な空白を取り除くことを意図していましたが、結果としてコードのインデントも失われる問題がありました。

変更後のコード:

text = strings.Trim(text, "\n")

この変更により、strings.TrimSpace の代わりに strings.Trim が使用され、cutset として明示的に改行文字 "\n" が指定されました。これにより、code 関数は以下の挙動を示すようになります。

  1. 改行のみのトリミング: コードブロックの先頭と末尾にある余分な改行文字だけが削除されます。
  2. インデントの保持: コード行の先頭にあるスペースやタブといったインデントは、cutset に含まれていないため、削除されずにそのまま保持されます。

この修正は、ドキュメントに表示されるGoコード例の視覚的な整合性を保つ上で非常に重要です。インデントが正しく保持されることで、コードの構造が明確になり、読者がコードをより容易に理解できるようになります。

doc/progs/ ディレクトリ以下のGoプログラムファイル

doc/progs/ ディレクトリには、Goのドキュメントやチュートリアルで使用される様々なGoプログラムの例が格納されています。これらのファイルに対して gofmt が適用されたことで、各ファイルのコードはGoの標準的なフォーマット規約に準拠するようになりました。

例えば、doc/progs/echo.go のインポート文の変更を見てみましょう。

変更前:

import (
	"os"
	"flag" // command line option parser
)

変更後:

import (
	"flag" // command line option parser
	"os"
)

gofmt は、インポートパスをアルファベット順にソートするルールを持っています。この例では、flag が os よりもアルファベット順で先に来るため、gofmt によって順序が入れ替えられました。

このように、gofmt の適用は、個々のファイルのコードスタイルを統一し、Goコミュニティ全体で期待されるコードの見た目を維持するのに役立ちます。これは、ドキュメントの品質を向上させ、読者がGoのベストプラクティスを学ぶ上でも有益です。

関連リンク

参考にした情報源リンク

  • コミットメッセージと差分情報 (./commit_data/11051.txt)
  • Go言語の公式ドキュメント (go.dev/doc)
  • Go言語の strings パッケージのドキュメント (pkg.go.dev/strings)
  • gofmt に関するGoブログの記事 (go.dev/blog/gofmt)