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

このコミットは、Go言語の公式ドキュメントにおけるいくつかの壊れたリンクを修正することを目的としています。具体的には、doc/code.html、doc/go1.1.html、doc/go1.2.html の3つのファイル内のハイパーリンクが更新されています。これらの修正は、ドキュメントの正確性とユーザビリティを向上させるためのものです。

コミット

commit cf694aac346fefc0383ebf2ecb83b365c0357920
Author: Andrew Gerrand <adg@golang.org>
Date:   Wed Oct 9 07:05:43 2013 +1100

    doc: fix a few broken links
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/14494044

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

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

元コミット内容

doc: fix a few broken links

Go言語のドキュメントは、Goのツール、言語仕様、標準ライブラリなど、多岐にわたる情報を提供しています。時間の経過とともに、ドキュメントの構造変更、新しい機能の追加、既存の機能の改訂などにより、内部リンクが古くなったり、参照先が変更されたりすることがあります。このコミットは、そのような状況で発生したいくつかの壊れたリンクを特定し、修正することで、ユーザーが正確な情報にアクセスできるようにすることを目的としています。特に、Go 1.1およびGo 1.2のリリースノートやコードに関するドキュメントにおいて、参照先の変更やアンカー名の変更に対応する必要がありました。

前提知識の解説

Go言語ドキュメントの構造: Go言語の公式ドキュメントは、HTML形式で提供されており、go.dev (旧 golang.org) ドメインで公開されています。これらのドキュメントは、言語仕様 (/ref/spec)、コマンドラインツール (/cmd/go)、標準ライブラリのパッケージ (/pkg) など、論理的に分割されたセクションで構成されています。各セクション内では、特定の要素（関数、型、メソッド、セクション見出しなど）に直接リンクするためのアンカー（#に続く文字列）が使用されます。
HTMLハイパーリンク: HTMLの <a> タグはハイパーリンクを作成するために使用されます。href 属性はリンク先のURLを指定します。URLには、絶対パス、相対パス、そして特定のページ内のセクションを指すためのフラグメント識別子（#で始まる部分）を含めることができます。例えば、/pkg/io/#Reader は /pkg/io ページの Reader というIDを持つ要素にリンクします。
Goツールのヘルプ: go コマンドには、様々なサブコマンドや機能に関するヘルプドキュメントが組み込まれています。これらのヘルプは、go help <topic> の形式でアクセスでき、ドキュメント内でも参照されることがあります。
Go言語仕様: Go言語の仕様は、言語の構文、セマンティクス、型システムなどを定義する公式ドキュメントです。仕様内の特定のセクションも、ドキュメント内で参照されます。
Go標準ライブラリ: Goは豊富な標準ライブラリを提供しており、各パッケージのドキュメントは /pkg 以下に配置されています。パッケージ内の特定の型やメソッドへのリンクも頻繁に使用されます。

技術的詳細

このコミットで行われた修正は、主に以下のパターンに分類できます。

アンカー名の変更: ドキュメント内の特定のセクションや要素のID（アンカー名）が変更された場合、それらを参照しているリンクも更新する必要があります。例えば、#hdr-Remote_import_path_syntax が #hdr-Remote_import_paths に変更されたケースがこれに該当します。これは、go help コマンドの出力やドキュメントの再編成に伴って発生する可能性があります。
パスの修正: URLパス自体に誤りがあった場合や、より正確なパスに変更された場合に修正が行われます。例えば、/ref/spec/#Terminating_statements のように、# の前に余分な / が入っていたものを /ref/spec#Terminating_statements に修正するケースです。これは、パスの正規化や、ドキュメント生成ツールの挙動の変更によって発生することがあります。
パッケージ/型の参照の明確化: Goの標準ライブラリでは、インターフェースや型のドキュメントが特定のパッケージに属しています。以前は Reader や Writer のように、パッケージ名を省略して参照されていたものが、より明確に io パッケージの Reader や Writer であることを示すために /pkg/io/#Reader のように修正されています。これは、曖昧さをなくし、ユーザーが正しいドキュメントにたどり着けるようにするための改善です。
メソッドのアンカー名の修正: 特定の型に属するメソッドへのリンクは、#Type.Method の形式でアンカーが指定されることが一般的です。例えば、compress/flate パッケージの Writer 型の Reset メソッドへのリンクが /pkg/compress/flate/#Reset から /pkg/compress/flate/#Writer.Reset に修正されています。これは、メソッドのアンカー名の命名規則が変更されたか、より厳密に適用されるようになったことを示唆しています。
不要なリンクの削除: go/build パッケージの Package 型の AllTags フィールドに関する記述で、以前は AllTags 自体にリンクが張られていましたが、このリンクが削除され、代わりに Package 型自体にリンクが張られるように変更されています。これは、AllTags フィールド自体に独立したアンカーが必要ないと判断されたか、Package 型のドキュメント内で AllTags が適切に説明されているため、重複するリンクが不要になったためと考えられます。

これらの修正は、Goドキュメントのメンテナンスの一環として、ユーザーエクスペリエンスを向上させるために定期的に行われる作業です。

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

diff --git a/doc/code.html b/doc/code.html
index 2bf50601e4..f9aa6ac171 100644
--- a/doc/code.html
+++ b/doc/code.html
@@ -576,7 +576,7 @@ provide lists of external Go projects.\
 
 <p>
 For more information on using remote repositories with the <code>go</code> tool, see
-<code><a href="/cmd/go/#hdr-Remote_import_path_syntax">go help remote</a></code>.\
+<code><a href="/cmd/go/#hdr-Remote_import_paths">go help importpath</a></code>.\
 </p>
 
 
diff --git a/doc/go1.1.html b/doc/go1.1.html
index a68664954a..87d5f5c876 100644
--- a/doc/go1.1.html
+++ b/doc/go1.1.html
@@ -129,7 +129,7 @@ only an infinite "for" loop.\
 <p>
 In Go 1.1, the rule about final "return" statements is more permissive.\
 It introduces the concept of a\
-<a href="/ref/spec/#Terminating_statements"><em>terminating statement</em></a>,\
+<a href="/ref/spec#Terminating_statements"><em>terminating statement</em></a>,\
 a statement that is guaranteed to be the last one a function executes.\
 Examples include\
 "for" loops with no condition and "if-else"\
@@ -191,7 +191,7 @@ more than 2 billion elements on 64-bit platforms.\
 <em>Updating</em>:\
 Most programs will be unaffected by this change.\
 Because Go does not allow implicit conversions between distinct\
-<a href="/ref/spec/#Numeric_types">numeric types</a>,\
+<a href="/ref/spec#Numeric_types">numeric types</a>,\
 no programs will stop compiling due to this change.\
 However, programs that contain implicit assumptions\
 that <code>int</code> is only 32 bits may change behavior.\
diff --git a/doc/go1.2.html b/doc/go1.2.html
index 4b8efb66c1..9f96836ac1 100644
--- a/doc/go1.2.html
+++ b/doc/go1.2.html
@@ -580,8 +580,8 @@ The <a href="/pkg/bufio/"><code>bufio</code></a> package\
 adds <a href="/pkg/bufio/#Reader.Reset"><code>Reset</code></a>\
 methods to <a href="/pkg/bufio/#Reader"><code>Reader</code></a> and\
 <a href="/pkg/bufio/#Writer"><code>Writer</code></a>.\
-These methods allow the <a href="/pkg/Reader/"><code>Readers</code></a>\
-and <a href="/pkg/Writer/"><code>Writers</code></a>\
+These methods allow the <a href="/pkg/io/#Reader"><code>Readers</code></a>\
+and <a href="/pkg/io/#Writer"><code>Writers</code></a>\
 to be re-used on new input and output readers and writers, saving\
 allocation overhead. \
 </li>\
@@ -593,7 +593,7 @@ can now decompress concatenated archives.\
 
 <li>\
 The <a href="/pkg/compress/flate/"><code>compress/flate</code></a>\
-package adds a <a href="/pkg/compress/flate/#Reset"><code>Reset</code></a> \
+package adds a <a href="/pkg/compress/flate/#Writer.Reset"><code>Reset</code></a> \
 method on the <a href="/pkg/compress/flate/#Writer"><code>Writer</code></a>,\
 to make it possible to reduce allocation when, for instance, constructing an\
 archive to hold multiple compressed files.\
@@ -621,9 +621,9 @@ method to provide a more efficient way to update an item's position in the heap.\
 
 <li>\
 The <a href="/pkg/container/list/"><code>container/list</code></a> package\
-adds the <a href="/pkg/container/list/#MoveBefore"><code>MoveBefore</code></a>\
+adds the <a href="/pkg/container/list/#List.MoveBefore"><code>MoveBefore</code></a>\
 and\
-<a href="/pkg/container/list/#MoveAfter"><code>MoveAfter</code></a>\
+<a href="/pkg/container/list/#List.MoveAfter"><code>MoveAfter</code></a>\
 methods, which implement the obvious rearrangement.\
 </li>\
 
@@ -745,7 +745,7 @@ The default is false, representing the usual two-index form.\
 
 <li>\
 The <a href="/pkg/go/build/"><code>go/build</code></a> package adds\
-the <a href="/pkg/go/build/#Package.AllTags"><code>AllTags</code></a> field\
+the <code>AllTags</code> field\
 to the <a href="/pkg/go/build/#Package"><code>Package</code></a> type,\
 to make it easier to process build tags.\
 </li>\
@@ -910,7 +910,7 @@ in agreement with that of other printing functions such as "printf".\
 In the <a href="/pkg/time/"><code>time</code></a> package, the\
 <a href="/pkg/time/#Parse"><code>Parse</code></a> function\
 and\
-<a href="/pkg/time/#Format"><code>Format</code></a>\
+<a href="/pkg/time/#Time.Format"><code>Format</code></a>\
 method\
 now handle time zone offsets with seconds, such as in the historical\
 date "1871-01-01T05:33:02+00:34:08".\

コアとなるコードの解説

このコミットは、Go言語のドキュメント内の複数のHTMLファイルにおいて、ハイパーリンクの href 属性を修正しています。

doc/code.html の変更:
- go ツールのリモートインポートパスに関するヘルプへのリンクが修正されました。
- 変更前: /cmd/go/#hdr-Remote_import_path_syntax
- 変更後: /cmd/go/#hdr-Remote_import_paths
- これは、go help コマンドの特定のトピックのアンカー名が変更されたことに対応しています。
doc/go1.1.html の変更:
- Go 1.1 のリリースノートにおける「終端ステートメント (terminating statement)」と「数値型 (numeric types)」に関するGo言語仕様へのリンクが修正されました。
- 変更前: /ref/spec/#Terminating_statements および /ref/spec/#Numeric_types
- 変更後: /ref/spec#Terminating_statements および /ref/spec#Numeric_types
- # の前の余分な / が削除され、正しいフラグメント識別子の形式に修正されました。
doc/go1.2.html の変更:
- Go 1.2 のリリースノートにおける複数の標準ライブラリパッケージへのリンクが修正されました。
- bufio パッケージの Reader と Writer へのリンクが、より一般的な io パッケージの Reader と Writer を指すように修正されました。
  - 変更前: /pkg/Reader/ および /pkg/Writer/
  - 変更後: /pkg/io/#Reader および /pkg/io/#Writer
  - これは、io パッケージが Reader と Writer インターフェースの基本的な定義を提供しているため、より適切な参照先となります。
- compress/flate パッケージの Writer 型の Reset メソッドへのリンクが修正されました。
  - 変更前: /pkg/compress/flate/#Reset
  - 変更後: /pkg/compress/flate/#Writer.Reset
  - メソッドへのリンクは、通常 TypeName.MethodName の形式でアンカーが指定されるため、これに合わせる修正です。
- container/list パッケージの List 型の MoveBefore および MoveAfter メソッドへのリンクが修正されました。
  - 変更前: /pkg/container/list/#MoveBefore および /pkg/container/list/#MoveAfter
  - 変更後: /pkg/container/list/#List.MoveBefore および /pkg/container/list/#List.MoveAfter
  - これも TypeName.MethodName の形式に合わせた修正です。
- go/build パッケージの Package 型の AllTags フィールドに関する記述から、AllTags 自体への直接リンクが削除されました。
  - 変更前: <a href="/pkg/go/build/#Package.AllTags"><code>AllTags</code></a> field
  - 変更後: the <code>AllTags</code> field
  - AllTags は Package 型のフィールドであり、Package 型のドキュメント内で説明されるため、AllTags 自体への独立したリンクは不要と判断されたと考えられます。
- time パッケージの Format メソッドへのリンクが修正されました。
  - 変更前: <a href="/pkg/time/#Format"><code>Format</code></a>
  - 変更後: <a href="/pkg/time/#Time.Format"><code>Format</code></a>
  - Format メソッドは Time 型のメソッドであるため、Time.Format の形式に修正されました。

これらの変更は、Goドキュメントの整合性を保ち、ユーザーが正確な情報に迅速にアクセスできるようにするために重要です。

参考にした情報源リンク

GitHub上のコミットページ: https://github.com/golang/go/commit/cf694aac346fefc0383ebf2ecb83b365c0357920
Go言語の公式ドキュメント (一般的な知識の参照)
HTMLの <a> タグとフラグメント識別子に関する一般的なWeb技術情報

comemo