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

このコミットは、Go言語の標準ライブラリの一部であるgo/scannerおよびgo/tokenパッケージ内のドキュメンテーションコメントの調整に関するものです。具体的には、関数名を参照する際に慣習的に付けられていた括弧()を削除し、より簡潔で自然な記述に修正しています。

コミット

commit efbb120d8e7af19b7c2bbb2dbacce73f73d5916b
Author: Robert Griesemer <gri@golang.org>
Date:   Mon Mar 9 18:53:11 2009 -0700

    - more documentation adjustments
    
    R=rsc
    DELTA=6  (0 added, 1 deleted, 5 changed)
    OCL=25970
    CL=25973

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

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

元コミット内容

- more documentation adjustments

変更の背景

このコミットは、Go言語の初期開発段階におけるドキュメンテーションの品質向上と一貫性確保の一環として行われました。当時のGo言語のドキュメンテーションスタイルガイドでは、関数名を参照する際に、その関数が引数を取らない場合でも()を付けて記述する慣習が見られました。しかし、これは冗長であり、自然言語としての読みやすさを損なう可能性がありました。

この変更の目的は、ドキュメンテーション内の関数名への参照をより簡潔にし、コード内の関数呼び出しと混同されないようにすること、そして全体的なドキュメンテーションの一貫性と可読性を向上させることにありました。特に、Scan()やInit()のように引数を取らない関数であっても、ドキュメンテーション内で()が付いていると、あたかも引数が必要であるかのような誤解を与える可能性がありました。

前提知識の解説

Go言語のドキュメンテーション: Go言語では、コードのコメントがそのままドキュメンテーションとして機能する「godoc」というツールが提供されています。開発者はコード内に特定の形式でコメントを記述することで、自動的にAPIドキュメントを生成できます。そのため、コメントの記述スタイルや正確性は非常に重要です。
go/scannerパッケージ: このパッケージは、Goのソースコードを字句解析（トークン化）するためのスキャナーを提供します。ソースコードの文字列を読み込み、キーワード、識別子、演算子、リテラルなどの個々の「トークン」に分解する役割を担います。
go/tokenパッケージ: このパッケージは、go/scannerパッケージと連携し、Go言語のトークン（字句）の種類を定義します。例えば、token.IDENT（識別子）、token.INT（整数リテラル）、token.ADD（加算演算子）などが含まれます。

技術的詳細

このコミットは、Go言語のソースコード内のコメント、特にgo/scannerパッケージとgo/tokenパッケージのドキュメンテーションコメントに焦点を当てています。変更内容は非常にシンプルで、ドキュメンテーション内で関数名を参照している箇所から、その関数が引数を取らない場合でも付けられていた()を削除するというものです。

例えば、Scan()関数への参照はScanに、Init()関数への参照はInitに変更されています。これは、ドキュメンテーションがコードの動作を説明するものであり、具体的な関数呼び出しの構文を示すものではないという原則に基づいています。これにより、ドキュメンテーションはより自然な文章として読めるようになり、読者が関数名と関数呼び出しの区別を明確にできるようになります。

この種のドキュメンテーションの調整は、コードの機能には直接影響しませんが、プロジェクト全体の品質、特に新規開発者やライブラリ利用者がコードベースを理解する上での障壁を低減する上で非常に重要です。

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

このコミットによる変更は、以下の2つのファイルにわたっています。

src/lib/go/scanner.go
src/lib/go/token.go

具体的な変更は、ドキュメンテーションコメント内の文字列の置換です。

src/lib/go/scanner.go の変更点:

--- a/src/lib/go/scanner.go
+++ b/src/lib/go/scanner.go
@@ -3,7 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // A scanner for Go source text. Takes a []byte as source which can
-// then be tokenized through repeated calls to the Scan() function.
+// then be tokenized through repeated calls to the Scan function.
 //
 // Sample use:
 //
@@ -33,7 +33,7 @@ import (
 
 
 // An implementation of an ErrorHandler must be provided to the Scanner.
-// If a syntax error is encountered, Error() is called with the exact
+// If a syntax error is encountered, Error is called with the exact
 // token position (the byte position of the token in the source) and the
 // error message.
 //
@@ -44,7 +44,7 @@ type ErrorHandler interface {
 
 // A Scanner holds the scanner's internal state while processing
 // a given text.  It can be allocated as part of another data
-// structure but must be initialized via Init() before use.
+// structure but must be initialized via Init before use.
 // See also the package comment for a sample use.
 //
 type Scanner struct {
@@ -99,7 +99,7 @@ func (S *Scanner) next() {
 }
 
 
-// Init() prepares the scanner S to tokenize the text src. Calls to Scan()
+// Init prepares the scanner S to tokenize the text src. Calls to Scan
 // will use the error handler err if they encounter a syntax error. The boolean
 // scan_comments specifies whether newline characters and comments should be
 // recognized and returned by Scan as token.COMMENT. If scan_comments is false,
@@ -401,7 +401,7 @@ func (S *Scanner) switch4(tok0, tok1, ch2, tok2, tok3 int) int {
 }
 
 
-// Scan() scans the next token and returns the token byte position in the
+// Scan scans the next token and returns the token byte position in the
 // source, its token value, and the corresponding literal text if the token
 // is an identifier, basic type literal (token.IsLiteral(tok) == true), or
 // comment.

src/lib/go/token.go の変更点:

--- a/src/lib/go/token.go
+++ b/src/lib/go/token.go
@@ -11,7 +11,6 @@ package token
 import "strconv"
 
 // The list of tokens.
-//
 const (
 	// Special tokens
 	ILLEGAL = iota;

コアとなるコードの解説

このコミットは、Go言語のソースコードそのもの（ロジックや機能）には一切変更を加えていません。変更は完全にドキュメンテーションコメントに限定されています。

src/lib/go/scanner.goでは、Scan()、Error()、Init()といった関数名がドキュメンテーション内で参照されている箇所から、引数を示す括弧()が削除されています。これにより、例えば「Scan()関数を繰り返し呼び出すことでトークン化できる」という記述が、「Scan関数を繰り返し呼び出すことでトークン化できる」となり、より自然な文章表現になっています。

src/lib/go/token.goでは、//で始まるコメント行が1行削除されています。これは、おそらく以前のコミットで追加された、あるいは一時的に存在した不要なコメント行を削除したものです。この変更も、コードの動作には影響せず、ドキュメンテーションの整理の一環と考えられます。

これらの変更は、Go言語のドキュメンテーションが、コードの機能説明に特化し、冗長な表現を避けるという設計思想を反映しています。

参考にした情報源リンク

Go言語の公式ドキュメンテーション
GitHubのコミット履歴
Go言語の初期開発に関する議論（Go言語のメーリングリストやIssueトラッカーなど、当時の情報源）
- （注：具体的なリンクは、このコミットが非常に古いため、当時のメーリングリストやIssueを特定して参照することは困難です。しかし、このようなドキュメンテーションの調整は、初期の言語設計やスタイルガイドの確立フェーズで頻繁に行われる一般的なプラクティスです。）

comemo