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

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

このコミットは、Go言語のバージョン1.1に関するドキュメントファイル doc/go1.1.html 内の壊れたリンクを修正するものです。このファイルは、Go 1.1のリリースノートや変更点をまとめたものであり、Go言語のユーザーが新しいバージョンでの変更点を理解するための重要な情報源です。

コミット

  • コミットハッシュ: 259e8cec7ad3d7c0031c53d70442fafdbdabe528
  • Author: Robert Griesemer gri@golang.org
  • Date: Fri Mar 22 16:41:27 2013 -0700
  • コミットメッセージ: 
    doc/go1.1.html: fix broken links

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

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

https://github.com/golang/go/commit/259e8cec7ad3d7c0031c53d70442fafdbdabe528

元コミット内容

doc/go1.1.html: fix broken links
    
R=golang-dev, r
CC=golang-dev
https://golang.org/cl/7834049

変更の背景

このコミットの背景には、Go 1.1のドキュメント doc/go1.1.html 内に存在する、Go標準ライブラリの net パッケージ内の特定の関数や型へのリンクが正しく機能していなかったという問題があります。元のリンクは、例えば /pkg/ResolveIPAddr/ のように、パッケージ全体を指す形式になっていましたが、実際には net パッケージ内の特定の要素（関数や型）を指す必要がありました。

Goのドキュメンテーションシステムでは、特定の関数や型へのリンクは、パッケージパスの後に # とその要素名を追加する形式（例: /pkg/net/#ResolveIPAddr）で表現されます。これにより、ブラウザはそのページの特定の位置（アンカー）に直接ジャンプできます。元のリンク形式では、ブラウザはパッケージのトップページに移動するだけで、ユーザーが目的の関数や型を見つけるためには手動でスクロールする必要がありました。これはユーザーエクスペリエンスを損なうだけでなく、リンクが「壊れている」と認識される原因にもなります。

この修正は、ドキュメントの正確性とユーザビリティを向上させるために行われました。

前提知識の解説

Go言語のドキュメンテーション

Go言語の公式ドキュメンテーションは、go doc コマンドや pkg.go.dev (旧 golang.org/pkg/) を通じて提供されています。これらのドキュメントは、Goのソースコード内のコメントから自動生成されます。

  • パッケージドキュメント: /pkg/パッケージ名/ の形式でアクセスでき、そのパッケージ全体の概要や主要な情報が記載されています。
  • 特定の要素へのリンク（アンカーリンク）: HTMLドキュメントでは、特定のセクションや要素に直接ジャンプするために「アンカー（Anchor）」が使用されます。URLの末尾に # とアンカー名を追加することで、そのアンカーが定義された位置にブラウザが自動的にスクロールします。Goのドキュメントでは、関数名や型名がアンカーとして機能し、/pkg/パッケージ名/#要素名 の形式でリンクされます。

Go 1 互換性ルール

Go言語は、バージョン1.0以降、厳格な「Go 1 互換性保証」を掲げています。これは、Go 1.xのリリース間で、既存のGo 1プログラムが新しいGo 1.xリリースでコンパイルされ、実行され続けることを保証するものです。ただし、このルールには例外があり、バグ修正やセキュリティ修正など、特定の状況下ではAPIの変更が許容される場合があります。

このコミットの差分には、net パッケージの ListenUnixgram 関数の戻り値の型変更に関する記述があります。これはGo 1.0での「明らかな間違い」を修正するためのものであり、Go 1互換性ルールによって許容される変更とされています。今回のリンク修正自体はAPIの変更ではなく、ドキュメントの修正であるため、互換性ルールには直接影響しません。

net パッケージ

net パッケージは、Go言語におけるネットワークI/Oの主要なインターフェースを提供します。TCP/IP、UDP、Unixドメインソケットなどのネットワークプロトコルを扱うための機能が含まれています。

  • ResolveIPAddr, ResolveUDPAddr, ResolveUnixAddr: それぞれIPアドレス、UDPアドレス、Unixドメインソケットアドレスを解決するための関数です。
  • UDPConn, UnixConn: それぞれUDP接続、Unixドメインソケット接続を表す型です。

技術的詳細

このコミットの技術的な詳細は、HTMLのハイパーリンクの構造と、Go言語のドキュメンテーションにおける特定の要素へのリンク方法に集約されます。

元のHTMLコードでは、<a> タグの href 属性が以下のような形式でした。

<a href="/pkg/ResolveIPAddr/"><code>ResolveIPAddr</code></a>

これは、/pkg/ResolveIPAddr/ というURLにリンクしています。Goのドキュメンテーション構造では、これは ResolveIPAddr という名前のパッケージが存在するかのように解釈される可能性がありますが、実際には net パッケージ内の関数です。

修正後のHTMLコードは以下のようになります。

<a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>

この変更により、リンクは /pkg/net/ という net パッケージのドキュメントページを指し、さらに #ResolveIPAddr というアンカー（HTML要素のID）を指定することで、そのページ内の ResolveIPAddr というIDを持つ要素（通常は関数や型の定義部分）に直接ジャンプするようになります。

同様の修正が、ResolveUDPAddr、ResolveUnixAddr、UnixConn、ListenUnixgram、UDPConn などの net パッケージ内の他の要素に対しても適用されています。これにより、ユーザーがこれらのリンクをクリックした際に、目的のドキュメントの正確な位置に移動できるようになります。

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

--- a/doc/go1.1.html
+++ b/doc/go1.1.html
@@ -384,9 +384,9 @@ that the only valid networks for
 are <code>"tcp"</code>,
 <code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string.
 The Go 1.1 implementation returns an error if the network is not one of those strings.
-The same is true of the other protocol-specific resolvers <a href="/pkg/ResolveIPAddr/"><code>ResolveIPAddr</code></a>,
-<a href="/pkg/ResolveUDPAddr/"><code>ResolveUDPAddr</code></a>, and
-<a href="/pkg/ResolveUnixAddr/"><code>ResolveUnixAddr</code></a>.
+The same is true of the other protocol-specific resolvers <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
+<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
+<a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>.
 </p>
 
 <p>
@@ -396,7 +396,7 @@ returned a
 <a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as
 a representation of the connection endpoint.
 The Go 1.1 implementation instead returns a
-<a href="/pkg/UnixConn/"><code>UnixConn</code></a>
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
 to allow reading and writing
 with its
 <a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a>
@@ -683,11 +683,11 @@ to define the boundary separator used to package the output.
 <li>
 The
 <a href="/pkg/net/"><code>net</code></a> package's
-<a href="/pkg/net/ListenUnixgram/"><code>net/ListenUnixgram</code></a>
+<a href="/pkg/net/#ListenUnixgram"><code>net/ListenUnixgram</code></a>
 function has changed return types: it now returns a
-<a href="/pkg/net/UnixConn/"><code>net/UnixConn</code></a>
+<a href="/pkg/net/#UnixConn"><code>net/UnixConn</code></a>
 rather than a
-<a href="/pkg/net/UDPConn/"><code>net/UDPConn</code></a>, which was
+<a href="/pkg/net/#UDPConn"><code>net/UDPConn</code></a>, which was
 clearly a mistake in Go 1.0.
 Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
 </li>

コアとなるコードの解説

この差分は、doc/go1.1.html ファイル内の複数の <a> タグの href 属性を変更しています。

  • 行 387-389 の変更:

    • 修正前: 
      <a href="/pkg/ResolveIPAddr/"><code>ResolveIPAddr</code></a>,
<a href="/pkg/ResolveUDPAddr/"><code>ResolveUDPAddr</code></a>, and
<a href="/pkg/ResolveUnixAddr/"><code>ResolveUnixAddr</code></a>.
    • 修正後: 
      <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
<a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>.
    • 解説: ResolveIPAddr, ResolveUDPAddr, ResolveUnixAddr は net パッケージ内の関数であるため、リンク先を /pkg/net/ に変更し、さらに # を使ってそれぞれの関数名に直接リンクするように修正されています。これにより、ユーザーは net パッケージのドキュメントページ内の該当する関数定義に直接移動できます。

  • 行 399 の変更:

    • 修正前: 
      <a href="/pkg/UnixConn/"><code>UnixConn</code></a>
    • 修正後: 
      <a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
    • 解説: UnixConn は net パッケージ内の型であるため、リンク先を /pkg/net/ に変更し、#UnixConn で直接リンクするように修正されています。

  • 行 686-691 の変更:

    • 修正前: 
      <a href="/pkg/net/ListenUnixgram/"><code>net/ListenUnixgram</code></a>
function has changed return types: it now returns a
<a href="/pkg/net/UnixConn/"><code>net/UnixConn</code></a>
rather than a
<a href="/pkg/net/UDPConn/"><code>net/UDPConn</code></a>, which was
    • 修正後: 
      <a href="/pkg/net/#ListenUnixgram"><code>net/ListenUnixgram</code></a>
function has changed return types: it now returns a
<a href="/pkg/net/#UnixConn"><code>net/UnixConn</code></a>
rather than a
<a href="/pkg/net/#UDPConn"><code>net/UDPConn</code></a>, which was
    • 解説: ListenUnixgram 関数、UnixConn 型、UDPConn 型もすべて net パッケージ内の要素であるため、同様に /pkg/net/ にリンク先を変更し、それぞれの要素名に # を使って直接リンクするように修正されています。

これらの変更はすべて、Goのドキュメンテーションにおけるアンカーリンクの正しい使用法に準拠させるためのものです。

関連リンク

参考にした情報源リンク