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

このコミットは、Go言語の標準ライブラリsrc/pkg/mathパッケージ内の複数のファイルの関数ドキュメントを修正するものです。具体的には、以下のファイルのドキュメントが変更されています。

src/pkg/math/acosh.go
src/pkg/math/asinh.go
src/pkg/math/atanh.go
src/pkg/math/cbrt.go
src/pkg/math/copysign.go
src/pkg/math/erf.go
src/pkg/math/gamma.go
src/pkg/math/hypot.go
src/pkg/math/logb.go
src/pkg/math/sincos.go

コミット

コミットハッシュ: f27348776f3c898d9e5dc3c910dbac99ae482e52
作者: Charles L. Dorian cldorian@gmail.com
日付: Fri Apr 6 14:01:12 2012 -0400

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

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

元コミット内容

math: make function documentation more regular

R=rsc, golang-dev
CC=golang-dev
https://golang.org/cl/5994043

変更の背景

このコミットの背景は、Go言語の標準ライブラリにおける関数ドキュメントの一貫性を向上させることにあります。Go言語では、エクスポートされた（大文字で始まる）関数、変数、定数、型などには、その宣言の直前にコメントを記述することでドキュメントを生成する仕組みがあります。このドキュメントはgo docコマンドやpkg.go.devのようなドキュメントサイトで利用されます。

初期のGo言語のコードベースでは、ドキュメントの記述スタイルに多少のばらつきがありました。特に、関数の説明が「FunctionName(args) calculates ...」のような形式と、「FunctionName returns ...」のような形式が混在していました。このコミットは、mathパッケージ内の関数ドキュメントを後者の「FunctionName returns ...」という、より簡潔で直接的な表現に統一することを目的としています。これにより、Go言語のドキュメント全体の一貫性と可読性が向上します。

前提知識の解説

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

Go言語には、コードに直接ドキュメントを記述するための組み込みのメカニズムがあります。

エクスポートされた識別子: Goでは、識別子（関数名、変数名、型名など）が大文字で始まる場合、それはパッケージ外にエクスポートされ、公開されます。
ドキュメントコメント: エクスポートされた識別子の直前に記述されたコメントは、その識別子のドキュメントとして扱われます。
go docコマンド: Go SDKに含まれるgo docコマンドは、これらのドキュメントコメントを解析し、整形されたドキュメントを表示します。例えば、go doc math.Acoshと実行すると、mathパッケージのAcosh関数のドキュメントが表示されます。
慣習: Goのドキュメントコメントの慣習として、関数のドキュメントは関数名で始まり、その関数の動作を簡潔に説明することが推奨されます。例えば、「Func does X.」や「Func returns Y.」といった形式です。このコミットは、この慣習をより厳密に適用しようとするものです。

双曲線関数 (Hyperbolic Functions)

acosh, asinh, atanhはそれぞれ逆双曲線余弦関数 (inverse hyperbolic cosine)、逆双曲線正弦関数 (inverse hyperbolic sine)、逆双曲線正接関数 (inverse hyperbolic tangent) を表します。これらは通常の三角関数に似ていますが、単位円ではなく単位双曲線に基づいて定義されます。

Acosh(x): cosh(y) = x となる y の値。
Asinh(x): sinh(y) = x となる y の値。
Atanh(x): tanh(y) = x となる y の値。

誤差関数 (Error Function)

erfとerfcはそれぞれ誤差関数 (error function) と相補誤差関数 (complementary error function) を表します。これらは確率論、統計学、偏微分方程式などで用いられる特殊関数です。

Erf(x): 確率密度関数 (1/sqrt(pi)) * exp(-t^2) の積分に関連する関数。
Erfc(x): 1 - Erf(x) で定義される相補誤差関数。

その他の数学関数

Cbrt(x): 立方根 (cube root) を計算する関数。
Copysign(x, y): x の絶対値と y の符号を持つ値を返す関数。
Gamma(x): ガンマ関数。階乗の一般化として知られ、複素数に拡張された関数。
Hypot(p, q): sqrt(p*p + q*q) を計算する関数。オーバーフローやアンダーフローを避けるように実装されていることが多い。
Logb(x): x の二進指数部を返す関数。IEEE 754浮動小数点数の表現における指数部を意味する。
Ilogb(x): x の二進指数部を整数として返す関数。
Sincos(x): Sin(x) と Cos(x) を同時に返す関数。これは、両方の値を計算する際に共通の計算を共有できるため、効率的である場合がある。

技術的詳細

このコミットの技術的な変更は非常にシンプルで、Go言語のドキュメンテーションスタイルガイドラインへの準拠を徹底するものです。具体的には、src/pkg/mathパッケージ内の複数の関数のドキュメントコメントにおいて、以下のパターン置換が行われています。

FunctionName(x) calculates ... を
FunctionName returns ...

または

FunctionName(x, y) returns a value with the magnitude ... を
FunctionName returns a value with the magnitude ...

といった形式に修正しています。

この変更は、関数のドキュメントがその関数の「何をするか」ではなく、「何を返すか」に焦点を当てるというGoのドキュメンテーションの哲学を反映しています。また、引数リストをドキュメントコメントの最初の行に含めないことで、より簡潔で読みやすいドキュメントになります。go docコマンドは関数のシグネチャ（引数と戻り値の型）を自動的に表示するため、ドキュメントコメント内で重複して記述する必要がないという考え方に基づいています。

この変更は機能的な影響は一切なく、純粋にドキュメンテーションの品質と一貫性を向上させるためのものです。

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

以下に、変更されたファイルの差分の一部を示します。

diff --git a/src/pkg/math/acosh.go b/src/pkg/math/acosh.go
index c6c8645e1a..e394008b07 100644
--- a/src/pkg/math/acosh.go
+++ b/src/pkg/math/acosh.go
@@ -33,7 +33,7 @@ package math
 //	acosh(NaN) is NaN without signal.
 //
 
-// Acosh(x) calculates the inverse hyperbolic cosine of x.
+// Acosh returns the inverse hyperbolic cosine of x.
 //
 // Special cases are:
 //	Acosh(+Inf) = +Inf
diff --git a/src/pkg/math/asinh.go b/src/pkg/math/asinh.go
index 0defbb9bef..ff2de0215f 100644
--- a/src/pkg/math/asinh.go
+++ b/src/pkg/math/asinh.go
@@ -30,7 +30,7 @@ package math
 //	         := sign(x)*log1p(|x| + x**2/(1 + sqrt(1+x**2)))
 //
 
-// Asinh(x) calculates the inverse hyperbolic sine of x.
+// Asinh returns the inverse hyperbolic sine of x.
 //
 // Special cases are:
 //	Asinh(±0) = ±0
diff --git a/src/pkg/math/copysign.go b/src/pkg/math/copysign.go
index ee65456a1c..719c64b9eb 100644
--- a/src/pkg/math/copysign.go
+++ b/src/pkg/math/copysign.go
@@ -4,7 +4,7 @@
 
 package math
 
-// Copysign(x, y) returns a value with the magnitude
+// Copysign returns a value with the magnitude
 // of x and the sign of y.
 func Copysign(x, y float64) float64 {
 	const sign = 1 << 63
diff --git a/src/pkg/math/erf.go b/src/pkg/math/erf.go
index c6f32bdbe2..4cd80f80c3 100644
--- a/src/pkg/math/erf.go
+++ b/src/pkg/math/erf.go
@@ -179,7 +179,7 @@ const (
 	sb7 = -2.24409524465858183362e+01 // 0xC03670E242712D62
 )
 
-// Erf(x) returns the error function of x.
+// Erf returns the error function of x.
 //
 // Special cases are:
 //	Erf(+Inf) = 1
@@ -256,7 +256,7 @@ func Erf(x float64) float64 {\n 	return 1 - r/x\n }\n \n-// Erfc(x) returns the complementary error function of x.\n+// Erfc returns the complementary error function of x.\n //
 // Special cases are:
 //	Erfc(+Inf) = 0

コアとなるコードの解説

上記の差分からわかるように、各関数のドキュメントコメントの最初の行が変更されています。

// Acosh(x) calculates the inverse hyperbolic cosine of x. が // Acosh returns the inverse hyperbolic cosine of x. に変更。
// Asinh(x) calculates the inverse hyperbolic sine of x. が // Asinh returns the inverse hyperbolic sine of x. に変更。
// Copysign(x, y) returns a value with the magnitude が // Copysign returns a value with the magnitude に変更。
// Erf(x) returns the error function of x. が // Erf returns the error function of x. に変更。
// Erfc(x) returns the complementary error function of x. が // Erfc returns the complementary error function of x. に変更。

これらの変更は、Go言語のドキュメンテーションのベストプラクティスに従い、関数のドキュメントコメントがその関数の名前で始まり、その関数の「戻り値」や「結果」に焦点を当てるように修正されたことを示しています。これにより、go docコマンドで表示されるドキュメントがより簡潔で、かつ情報が重複しないようになります。

参考にした情報源リンク

https://golang.org/cl/5994043 (Go Gerrit Change-Id)
Effective Go
pkg.go.dev
Wikipedia: 双曲線関数
Wikipedia: 誤差関数
Wikipedia: ガンマ関数
Wikipedia: Hypot
Wikipedia: Logb
Wikipedia: Sincos

comemo