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

このコミットは、Go言語の標準ライブラリであるnetパッケージ内のTCP関連の型（TCPConn、TCPListenerなど）のドキュメンテーションを更新し、プラットフォーム間のAPIドキュメンテーションのギャップを埋めることを目的としています。また、コードのテキスト表現をプラットフォーム間で統一し、一貫性を向上させています。具体的には、コメントの改行位置や表現を調整し、より読みやすく、正確な説明になるように修正が加えられています。

コミット

• コミットハッシュ: f45339c1f334432e225f611ee37f6e07d382a7d1
• Author: Mikio Hara mikioh.mikioh@gmail.com
• Date: Sun Mar 31 16:47:26 2013 +0900

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

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

元コミット内容

net: update documentation for TCPConn, TCPListener and related stuff

Closes the API documentation gap between platforms.
Also makes the code textual representation same between platforms.

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

変更の背景

このコミットの主な背景は、Go言語のnetパッケージにおけるTCP関連のAPIドキュメンテーションの不整合を解消することにあります。特に、異なるプラットフォーム（例: POSIX準拠システム、Plan 9）間でTCPConnやTCPListenerなどの型やメソッドに関するドキュメンテーションに差異が存在していました。これにより、開発者がGoのネットワークプログラミングを行う際に、プラットフォームによってドキュメンテーションの記述が異なるといった混乱が生じる可能性がありました。

また、コード内のコメントのテキスト表現自体も、プラットフォーム固有のファイル間で統一されていなかったため、コードベース全体の一貫性を高める必要がありました。このコミットは、これらのドキュメンテーションとテキスト表現の「ギャップ」を埋め、GoのネットワークAPIの利用体験を向上させることを目的としています。

前提知識の解説

このコミットを理解するためには、以下のGo言語のネットワークプログラミングに関する基本的な概念と、TCP/IPプロトコルに関する知識が必要です。

• TCP (Transmission Control Protocol): インターネットプロトコルスイートの主要なプロトコルの一つで、信頼性の高い、コネクション指向のデータ転送サービスを提供します。データの順序保証、再送制御、フロー制御などを行い、アプリケーションが信頼性の高い通信を行えるようにします。
• Go言語の net パッケージ: Go言語の標準ライブラリで、ネットワークI/O機能を提供します。TCP/UDP通信、IPアドレスの解決、DNSルックアップなど、様々なネットワーク関連の機能が含まれています。
• net.Conn インターフェース: ネットワーク接続の汎用インターフェースです。Read、Write、Close、LocalAddr、RemoteAddr、SetDeadlineなどのメソッドを定義しており、TCP、UDP、Unixドメインソケットなど、様々な種類のネットワーク接続を抽象化します。
• net.Listener インターフェース: ネットワーク接続をリッスンするための汎用インターフェースです。Accept、Close、Addrなどのメソッドを定義しており、着信接続を受け入れるための機能を提供します。
• net.TCPConn: net.Connインターフェースを実装した、TCPネットワーク接続を表す型です。TCP接続固有の機能（例: SetLinger, SetKeepAlive, SetNoDelay）を提供します。
• net.TCPListener: net.Listenerインターフェースを実装した、TCPネットワークリッスンを表す型です。TCPリッスン固有の機能（例: AcceptTCP）を提供します。
• SetLinger: TCPConnのメソッドで、Close()が呼び出された際の挙動を制御します。ソケットバッファに残っているデータを送信し終えるまで待機するか、すぐに破棄するか、または指定された時間だけ待機するかを設定します。
  • sec < 0 (デフォルト): Closeはすぐに戻り、OSがバックグラウンドでデータの送信を完了します。
  • sec == 0: Closeはすぐに戻り、OSは未送信または未確認のデータを破棄します。
  • sec > 0: Closeは最大sec秒間ブロックし、データの送信と確認応答を待ちます。
• SetKeepAlive: TCPConnのメソッドで、TCPキープアライブ機能を有効または無効にします。キープアライブは、アイドル状態の接続がまだ有効であることを確認するために、定期的に小さなパケットを送信する機能です。
• SetNoDelay: TCPConnのメソッドで、Nagleアルゴリズムを有効または無効にします。
  • Nagleアルゴリズム: 小さなパケットが多数送信されるのを防ぐために、TCPセグメントをバッファリングするアルゴリズムです。これにより、ネットワークの輻輳を減らすことができますが、リアルタイム性が重要なアプリケーションでは遅延を引き起こす可能性があります。SetNoDelay(true)に設定すると、Nagleアルゴリズムが無効になり、データはWrite後すぐに送信されます。
• DialTCP: 指定されたネットワークアドレスにTCP接続を確立するための関数です。
• AcceptTCP: TCPListenerのメソッドで、次の着信接続を受け入れ、新しいTCPConnとリモートアドレスを返します。
• os.File: Go言語のosパッケージで提供されるファイルを表す型です。ネットワーク接続もファイルディスクリプタとして扱われるため、TCPListenerからos.Fileを取得する機能があります。
• syscall.EINVAL: 無効な引数が関数に渡されたことを示すシステムコールエラーです。
• syscall.EADDRNOTAVAIL: 要求されたアドレスが利用できないことを示すシステムコールエラーです。

技術的詳細

このコミットの技術的な変更は、主にGo言語のnetパッケージ内のTCP関連のドキュメンテーションコメントの修正に集中しています。変更は以下の3つのファイルにわたっています。

1. src/pkg/net/tcpsock.go: TCPソケットに関する一般的な定義が含まれるファイル。
2. src/pkg/net/tcpsock_plan9.go: Plan 9オペレーティングシステム向けのTCPソケット実装に関するファイル。
3. src/pkg/net/tcpsock_posix.go: POSIX準拠システム（Linux, macOS, FreeBSDなど）およびWindows向けのTCPソケット実装に関するファイル。

変更の具体的な内容は以下の通りです。

• 冗長なコメントの削除: tcpsock.go、tcpsock_plan9.go、tcpsock_posix.goの各ファイルから、冒頭の「// TCP sockets」や「// TCP sockets for Plan 9」といった、パッケージ宣言の直前にある冗長なコメントが削除されています。これは、パッケージ名自体がその内容を示しているため、不要な重複を避けるための変更です。
• コメントの改行と表現の統一: tcpsock_posix.goにおいて、TCPConn、SetLinger、SetNoDelay、DialTCP、TCPListener、AcceptTCP、Accept、Fileなどの型やメソッドのドキュメンテーションコメントが修正されています。
  • 行の折り返し: 長い説明文が適切な位置で改行されるように調整されています。これにより、コードエディタやドキュメンテーションツールでの表示が改善され、可読性が向上します。例えば、以前は1行に収まっていた長い説明が、意味の区切りで複数行に分割されています。
  • 表現の統一: 各コメントの表現がより簡潔かつ正確になるように修正されています。特に、プラットフォーム間で異なる可能性のある表現を統一し、一貫したAPIドキュメンテーションを提供することを目指しています。例えば、「TCP network connections.」のようなフレーズが、より自然な英語の表現に修正されています。
  • 句読点の修正: コメントの末尾の句読点（ピリオドなど）が適切に修正されています。

これらの変更は、機能的な振る舞いを変更するものではなく、Go言語のAPIドキュメンテーションの品質と一貫性を向上させるためのものです。特に、異なるプラットフォーム固有のファイル間でドキュメンテーションのスタイルを統一することで、Goのクロスプラットフォーム開発におけるドキュメンテーションの信頼性を高めています。

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

--- a/src/pkg/net/tcpsock.go
+++ b/src/pkg/net/tcpsock.go
@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.\n
-// TCP sockets
-\n
 package net

 // TCPAddr represents the address of a TCP end point.
--- a/src/pkg/net/tcpsock_plan9.go
+++ b/src/pkg/net/tcpsock_plan9.go
@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.\n
-// TCP sockets for Plan 9
-\n
 package net

 import (
--- a/src/pkg/net/tcpsock_posix.go
+++ b/src/pkg/net/tcpsock_posix.go
@@ -4,8 +4,6 @@
 
 // +build darwin freebsd linux netbsd openbsd windows
 
-// TCP sockets
-\n
 package net
 
 import (
@@ -58,8 +56,8 @@ func (a *TCPAddr) toAddr() sockaddr {
 	return a
 }
 
-// TCPConn is an implementation of the Conn interface
-// for TCP network connections.\n
+// TCPConn is an implementation of the Conn interface for TCP network
+// connections.\n
 type TCPConn struct {
 	conn
 }
@@ -96,17 +94,17 @@ func (c *TCPConn) CloseWrite() error {
 	return c.fd.CloseWrite()
 }
 
-// SetLinger sets the behavior of Close() on a connection
-// which still has data waiting to be sent or to be acknowledged.\n
+// SetLinger sets the behavior of Close() on a connection which still
+// has data waiting to be sent or to be acknowledged.\n
 //
-// If sec < 0 (the default), Close returns immediately and\n
-// the operating system finishes sending the data in the background.\n
+// If sec < 0 (the default), Close returns immediately and the\n
+// operating system finishes sending the data in the background.\n
 //
 // If sec == 0, Close returns immediately and the operating system
 // discards any unsent or unacknowledged data.\n
 //
-// If sec > 0, Close blocks for at most sec seconds waiting for\n
-// data to be sent and acknowledged.\n
+// If sec > 0, Close blocks for at most sec seconds waiting for data
+// to be sent and acknowledged.\n
 func (c *TCPConn) SetLinger(sec int) error {
 	if !c.ok() {
 		return syscall.EINVAL
@@ -124,9 +122,9 @@ func (c *TCPConn) SetKeepAlive(keepalive bool) error {
 }
 
 // SetNoDelay controls whether the operating system should delay
-// packet transmission in hopes of sending fewer packets
-// (Nagle\'s algorithm).  The default is true (no delay), meaning\n
-// that data is sent as soon as possible after a Write.\n
+// packet transmission in hopes of sending fewer packets (Nagle\'s\n
+// algorithm).  The default is true (no delay), meaning that data is\n
+// sent as soon as possible after a Write.\n
 func (c *TCPConn) SetNoDelay(noDelay bool) error {
 	if !c.ok() {
 		return syscall.EINVAL
@@ -135,8 +133,8 @@ func (c *TCPConn) SetNoDelay(noDelay bool) error {
 }
 
 // DialTCP connects to the remote address raddr on the network net,\n
-// which must be \"tcp\", \"tcp4\", or \"tcp6\".  If laddr is not nil, it is used\n
-// as the local address for the connection.\n
+// which must be \"tcp\", \"tcp4\", or \"tcp6\".  If laddr is not nil, it is\n
+// used as the local address for the connection.\n
 func DialTCP(net string, laddr, raddr *TCPAddr) (*TCPConn, error) {
 	switch net {
 	case "tcp", "tcp4", "tcp6":
@@ -216,16 +214,15 @@ func spuriousENOTAVAIL(err error) bool {
 	return ok && e.Err == syscall.EADDRNOTAVAIL
 }
 
-// TCPListener is a TCP network listener.\n
-// Clients should typically use variables of type Listener\n
-// instead of assuming TCP.\n
+// TCPListener is a TCP network listener.  Clients should typically\n
+// use variables of type Listener instead of assuming TCP.\n
 type TCPListener struct {
 	fd *netFD
 }
 
-// AcceptTCP accepts the next incoming call and returns the new connection\n
-// and the remote address.\n
-func (l *TCPListener) AcceptTCP() (c *TCPConn, err error) {\n
+// AcceptTCP accepts the next incoming call and returns the new\n
+// connection and the remote address.\n
+func (l *TCPListener) AcceptTCP() (*TCPConn, error) {\n
 	if l == nil || l.fd == nil {
 		return nil, syscall.EINVAL
 	}
@@ -236,14 +233,14 @@ func (l *TCPListener) AcceptTCP() (c *TCPConn, err error) {
 	return newTCPConn(fd), nil
 }
 
-// Accept implements the Accept method in the Listener interface;\n
-// it waits for the next call and returns a generic Conn.\n
-func (l *TCPListener) Accept() (c Conn, err error) {\n
-\tc1, err := l.AcceptTCP()\n
+// Accept implements the Accept method in the Listener interface; it\n
+// waits for the next call and returns a generic Conn.\n
+func (l *TCPListener) Accept() (Conn, error) {\n
+\tc, err := l.AcceptTCP()\n
 	if err != nil {
 		return nil, err
 	}
-\treturn c1, nil\n
+\treturn c, nil\n
 }
 
 // Close stops listening on the TCP address.
@@ -267,8 +264,8 @@ func (l *TCPListener) SetDeadline(t time.Time) error {
 	return setDeadline(l.fd, t)
 }
 
-// File returns a copy of the underlying os.File, set to blocking mode.\n
-// It is the caller\'s responsibility to close f when finished.\n
+// File returns a copy of the underlying os.File, set to blocking\n
+// mode.  It is the caller\'s responsibility to close f when finished.\n
 // Closing l does not affect f, and closing f does not affect l.\n
 func (l *TCPListener) File() (f *os.File, err error) { return l.fd.dup() }
 

コアとなるコードの解説

上記の差分は、主にGo言語のnetパッケージにおけるTCP関連のドキュメンテーションコメントの修正を示しています。

• src/pkg/net/tcpsock.go、src/pkg/net/tcpsock_plan9.go、src/pkg/net/tcpsock_posix.go:

  • これらのファイルから、// TCP sockets や // TCP sockets for Plan 9 といった、パッケージの目的を説明する冗長なコメントが削除されています。Goの慣習では、パッケージの目的はパッケージ名自体で明確に示されるため、このようなコメントは不要と判断されたと考えられます。

• src/pkg/net/tcpsock_posix.go: このファイルには、POSIX準拠システムおよびWindows向けのTCPソケット実装が含まれており、多くのドキュメンテーションコメントの修正が行われています。

  • TCPConn 型のコメント:
    • 変更前: // TCPConn is an implementation of the Conn interface\n// for TCP network connections.
    • 変更後: // TCPConn is an implementation of the Conn interface for TCP network\n// connections.
    • 解説: Connインターフェースの実装であることを説明するコメントが、より自然な英語の改行位置に修正されています。これにより、コメントが読みやすくなっています。
  • SetLinger メソッドのコメント:
    • 変更前: 長い説明文が不適切な位置で改行されていました。
    • 変更後: 説明文が意味の区切りで適切に改行され、各条件（sec < 0, sec == 0, sec > 0）の説明がより明確になっています。これにより、SetLingerの挙動に関するドキュメンテーションが格段に理解しやすくなっています。
  • SetNoDelay メソッドのコメント:
    • 変更前: Nagleアルゴリズムに関する説明の改行位置が不適切でした。
    • 変更後: (Nagle's algorithm) の部分が適切に折り返され、説明全体が読みやすくなっています。
  • DialTCP 関数のコメント:
    • 変更前: laddrがnilでない場合のローカルアドレスとしての使用に関する説明の改行位置が不適切でした。
    • 変更後: 説明がより自然な英語の改行位置に修正され、可読性が向上しています。
  • TCPListener 型のコメント:
    • 変更前: TCPListenerがListenerインターフェースの代わりに使われるべきではないという注意書きの改行位置が不適切でした。
    • 変更後: 説明がより自然な英語の改行位置に修正され、Listenerインターフェースの一般的な使用を推奨する意図が明確になっています。
  • AcceptTCP メソッドのコメント:
    • 変更前: 戻り値の型が明示されていませんでした。
    • 変更後: 戻り値の型が(*TCPConn, error)と明示され、関数のシグネチャと一致するように修正されています。また、説明の改行位置も調整されています。
  • Accept メソッドのコメント:
    • 変更前: AcceptTCP()の戻り値を変数c1に代入していましたが、cに修正されています。これは、Acceptメソッドの戻り値がConnインターフェースであるため、より一般的な変数名cを使用することで、コードの一貫性を高めています。
    • 変更後: AcceptメソッドがListenerインターフェースを実装していること、および汎用的なConnを返すことを説明するコメントの改行位置が調整されています。
  • File メソッドのコメント:
    • 変更前: os.Fileのコピーを返すこと、および呼び出し元がファイルを閉じる責任があることに関する説明の改行位置が不適切でした。
    • 変更後: 説明がより自然な英語の改行位置に修正され、可読性が向上しています。

これらの変更は、Go言語のドキュメンテーションの品質基準に沿って、コメントのフォーマットと内容を改善し、開発者にとってより明確で一貫性のあるAPIリファレンスを提供することを目的としています。機能的な変更は一切なく、純粋にドキュメンテーションの整備に焦点を当てたコミットです。

関連リンク

• Go CL 8147043: https://golang.org/cl/8147043

参考にした情報源リンク

• Go言語 net パッケージ公式ドキュメンテーション: https://pkg.go.dev/net
• TCP (Transmission Control Protocol) - Wikipedia: https://ja.wikipedia.org/wiki/Transmission_Control_Protocol
• Nagleアルゴリズム - Wikipedia: https://ja.wikipedia.org/wiki/Nagle%E3%82%A2%E3%83%AB%E3%82%B4%E3%83%AA%E3%82%BA%E3%83%A0
• Go言語におけるsyscallパッケージ: https://pkg.go.dev/syscall