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

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

このコミットは、Go言語のドキュメンテーションツールがパッケージの概要（synopsis）を生成する際の挙動に関する変更を元に戻すものです。具体的には、src/pkg/go/doc/synopsis.go ファイル内の firstSentenceLen 関数が、ドキュメンテーションコメントの最初の文の長さをどのように決定するかというロジックが修正されています。また、この変更に伴い、関連するテストケースが src/pkg/go/doc/synopsis_test.go から削除されています。

コミット

commit ea6cfc57b3161c9658694c8d802b019ca1ac7be1
Author: David Symonds <dsymonds@golang.org>
Date:   Fri Aug 16 14:36:06 2013 +1000

    undo CL 12822043 / 96fefaa02ae3
    
    Fixes #6160.
    
    ««« original CL description
    go/doc: permit a package synopsis to end with ":\n".
    
    R=gri, r
    CC=golang-dev
    https://golang.org/cl/12822043
    »»»
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/13040043

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

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

元コミット内容

このコミットは、以前の変更（CL 12822043 / コミットハッシュ 96fefaa02ae3）を元に戻すものです。元々のCLの目的は以下の通りでした。

go/doc: permit a package synopsis to end with ":\n".

これは、go/doc パッケージが生成するパッケージの概要（synopsis）が、コロンと改行（:\n）で終わることを許可するという変更でした。

変更の背景

このコミットは、以前の変更であるCL 12822043を「undo（元に戻す）」するものです。元の変更は、パッケージのドキュメンテーションコメントの最初の文（概要）が :\n で終わることを許可するように go/doc ツールを修正することを意図していました。これは、例えば「Package foo does these things:\n - a\n - b」のような形式のドキュメンテーションコメントがあった場合に、「Package foo does these things:」までを概要として正しく認識させるためのものであったと推測されます。

しかし、この変更が導入された後、何らかの問題が発生したため、このコミットで元に戻されることになりました。コミットメッセージには「Fixes #6160」と記載されており、これはCL 12822043が導入したバグや望ましくない挙動を修正するために、その変更自体を元に戻すという判断がなされたことを示唆しています。具体的な問題点については、公開されているGoのIssueトラッカーでは#6160が見つかりませんでしたが、内部的な問題追跡システムで管理されていた可能性があります。一般的に、このような変更の巻き戻しは、予期せぬ副作用や、当初の意図とは異なるドキュメンテーションの解釈が生じた場合に発生します。

前提知識の解説

  • Go言語のドキュメンテーションツール (go/doc パッケージ): Go言語には、ソースコードから自動的にドキュメンテーションを生成する強力なツールセットが組み込まれています。その中心となるのが go/doc パッケージです。このパッケージは、Goのソースコードを解析し、パッケージ、関数、型、変数などのドキュメンテーションコメントを抽出し、構造化されたデータとして提供します。go doc コマンドや pkg.go.dev のようなオンラインドキュメンテーションサイトは、この go/doc パッケージを利用してドキュメンテーションを表示しています。
  • パッケージの概要 (Synopsis): Goのドキュメンテーションにおいて、パッケージの概要（synopsis）とは、パッケージのドキュメンテーションコメントの最初の「文」を指します。これは、パッケージの目的や機能を手短に説明するために使用され、go doc コマンドの出力やオンラインドキュメンテーションのリスト表示などで重要な役割を果たします。この概要は、ユーザーがパッケージの目的を素早く理解するための要約として機能します。
  • firstSentenceLen 関数: go/doc パッケージ内で、ドキュメンテーションコメントから最初の文を正確に抽出するために使用される内部関数です。この関数は、与えられた文字列のどこまでが最初の文であるかを判断し、その長さを返します。文の終わりを判断するロジックは、句読点（ピリオド、コロンなど）や改行文字の組み合わせに基づいて定義されます。
  • CL (Change List): Goプロジェクトでは、コードの変更は「Change List (CL)」として提出され、レビュープロセスを経てマージされます。これはGitのコミットに相当しますが、Goプロジェクトでは Gerrit というコードレビューシステムを使用しており、各変更はCLとして管理されます。コミットメッセージに記載されている https://golang.org/cl/XXXXXXX は、そのCLのGerrit上のURLを示しています。

技術的詳細

このコミットの核心は、src/pkg/go/doc/synopsis.go 内の firstSentenceLen 関数のロジック変更です。この関数は、Goのドキュメンテーションコメントからパッケージの概要となる最初の文を抽出する際に、その文の終わりを判断します。

元の firstSentenceLen 関数のコメントには、文の終わりに関する以下のルールが記述されていました（このコミットで削除される部分）：

// The sentence ends at the first colon followed by a newline,
// or at the first period followed by space and not preceded by
// exactly one uppercase letter.

これは、以下の2つの条件のいずれかが満たされた場合に文の終わりと判断することを示していました。

  1. コロンと改行 (:\n): 最初のコロン（:）の直後に改行文字（\n）が続く場合。
  2. ピリオドとスペース: 最初のピリオド（.）の直後にスペースが続き、かつそのピリオドの直前が1つの大文字ではない場合（例: "U.S.A." のような略語を誤って文の終わりと判断しないため）。

CL 12822043は、このルールに「コロンと改行」の条件を追加しました。これは、例えば以下のようなドキュメンテーションコメントがあった場合に、「Package foo does these things:」までを概要として認識させるためのものでした。

Package foo does these things:
  - a
  - b

しかし、このコミット（CL 13040043）は、その「コロンと改行」の条件を削除し、firstSentenceLen 関数のロジックを元に戻しています。これにより、:\n で終わるドキュメンテーションコメントは、その :\n の部分で文が終了したとは見なされなくなります。結果として、:\n の後に続くテキストも最初の文の一部として扱われるか、あるいは別のルール（ピリオドとスペースのルールなど）が適用されるまで文が続くと判断されるようになります。

この変更の意図は、:\n を文の終わりと見なすことが、Goのドキュメンテーションの一般的な慣習や、他の文の終わりを判断するロジックとの整合性において問題を引き起こしたためと考えられます。例えば、:\n の後に続く内容が、実際には最初の文の補足説明であるにもかかわらず、概要から切り離されてしまうといった問題が発生した可能性があります。

テストケースの削除もこの変更を裏付けています。synopsis_test.go から削除されたテストケースは、まさに :\n で終わる文字列が正しく概要として抽出されることを期待するものでした。このテストケースが削除されたということは、その挙動がもはや期待されない、つまり :\n で文が終了しないという新しい（元の）ロジックが正しいと見なされたことを意味します。

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

src/pkg/go/doc/synopsis.go

--- a/src/pkg/go/doc/synopsis.go
+++ b/src/pkg/go/doc/synopsis.go
@@ -10,15 +10,12 @@ import (
 )
 
 // firstSentenceLen returns the length of the first sentence in s.
-// The sentence ends at the first colon followed by a newline,
-// or at the first period followed by space and not preceded by
-// exactly one uppercase letter.
+// The sentence ends after the first period followed by space and
+// not preceded by exactly one uppercase letter.
+//
 func firstSentenceLen(s string) int {
  	var ppp, pp, p rune
  	for i, q := range s {
-	if p == ':' && q == '\n' {
-		return i
-	}
  	if q == '\n' || q == '\r' || q == '\t' {
  		q = ' '
  	}
  • firstSentenceLen 関数のコメントから、コロンと改行に関する説明が削除されました。
  • firstSentenceLen 関数内のループから、if p == ':' && q == '\n' の条件とそのブロック（return i）が削除されました。

src/pkg/go/doc/synopsis_test.go

--- a/src/pkg/go/doc/synopsis_test.go
+++ b/src/pkg/go/doc/synopsis_test.go
@@ -29,7 +29,6 @@ var tests = []struct {
  	{"Package Καλημέρα κόσμε.", 36, "Package Καλημέρα κόσμε."},
  	{"Package こんにちは 世界\n", 31, "Package こんにちは 世界"},
  	{"Package foo does bar.", 21, "Package foo does bar."},
-	{"Package foo does these things:\n  - a\n  - b", 30, "Package foo does these things:"},
  	{"Copyright 2012 Google, Inc. Package foo does bar.", 27, ""},
  	{"All Rights reserved. Package foo does bar.", 20, ""},
  	{"All rights reserved. Package foo does bar.", 20, ""},
  • tests スライスから、{"Package foo does these things:\n - a\n - b", 30, "Package foo does these things:"} というテストケースが削除されました。

コアとなるコードの解説

src/pkg/go/doc/synopsis.go の変更

firstSentenceLen 関数は、ドキュメンテーション文字列 s の最初の文の長さを計算します。この関数は、文字列をルーン（Unicodeコードポイント）ごとに走査し、文の終わりを示すパターンを探します。

削除されたコードブロック:

if p == ':' && q == '\n' {
    return i
}

このブロックは、直前のルーン p がコロン（:）であり、現在のルーン q が改行（\n）である場合に、現在のインデックス i を文の終わりとして即座に返していました。これは、CL 12822043で追加されたロジックであり、「コロンと改行で文が終了する」というルールを実装していました。

このコミットでは、このロジックが削除されたため、firstSentenceLen 関数はもはや :\n を文の終わりとは見なしません。これにより、:\n の後に続くテキストも最初の文の一部として扱われるか、あるいは他の文の終わりを示すパターン（例えば、ピリオドとスペース）が見つかるまで文の走査が続行されます。

関数のコメントも更新され、:\n に関する説明が削除されています。これは、コードの挙動とドキュメンテーションが一致するようにするための重要な変更です。

src/pkg/go/doc/synopsis_test.go の変更

削除されたテストケース:

{"Package foo does these things:\n  - a\n  - b", 30, "Package foo does these things:"},

このテストケースは、入力文字列 Package foo does these things:\n - a\n - b に対して、期待される概要が Package foo does these things: であることを検証していました。これは、:\n が文の終わりとして認識されることを前提としたテストです。

firstSentenceLen 関数から :\n で文が終了するロジックが削除されたため、このテストケースはもはや期待される挙動を反映していません。したがって、このテストケースを削除することは、コードの変更とテストスイートの整合性を保つために必要でした。このテストケースが削除されたことで、:\n で文が終了しないという新しい（元の）挙動が正しいと見なされることになります。

関連リンク

参考にした情報源リンク

  • コミットメッセージ自体
  • Go言語のドキュメンテーションに関する一般的な知識
  • Go言語のソースコード構造に関する一般的な知識