From 4cdadeedc3b46f91dd9d863b9a8f94d9ac820067 Mon Sep 17 00:00:00 2001
From: alec hodgkinson <ahodgkinson@perimetrics.ai>
Date: Thu, 11 Apr 2024 09:55:43 -0700
Subject: [PATCH] Added docs for trig function procedure groups

---
 core/math/math.odin | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/core/math/math.odin b/core/math/math.odin
index 570c2d255..8d85c2381 100644
--- a/core/math/math.odin
+++ b/core/math/math.odin
@@ -60,6 +60,7 @@ sqrt :: proc{
 @(require_results) sin_f32be :: proc "contextless" (θ: f32be) -> f32be { return #force_inline f32be(sin_f32(f32(θ))) }
 @(require_results) sin_f64le :: proc "contextless" (θ: f64le) -> f64le { return #force_inline f64le(sin_f64(f64(θ))) }
 @(require_results) sin_f64be :: proc "contextless" (θ: f64be) -> f64be { return #force_inline f64be(sin_f64(f64(θ))) }
+// Return the sine of θ in radians.
 sin :: proc{
 	sin_f16, sin_f16le, sin_f16be,
 	sin_f32, sin_f32le, sin_f32be,
@@ -72,6 +73,7 @@ sin :: proc{
 @(require_results) cos_f32be :: proc "contextless" (θ: f32be) -> f32be { return #force_inline f32be(cos_f32(f32(θ))) }
 @(require_results) cos_f64le :: proc "contextless" (θ: f64le) -> f64le { return #force_inline f64le(cos_f64(f64(θ))) }
 @(require_results) cos_f64be :: proc "contextless" (θ: f64be) -> f64be { return #force_inline f64be(cos_f64(f64(θ))) }
+// Return the cosine of θ in radians.
 cos :: proc{
 	cos_f16, cos_f16le, cos_f16be,
 	cos_f32, cos_f32le, cos_f32be,
@@ -378,6 +380,7 @@ log10 :: proc{
 @(require_results) tan_f64   :: proc "contextless" (θ: f64)   -> f64   { return sin(θ)/cos(θ) }
 @(require_results) tan_f64le :: proc "contextless" (θ: f64le) -> f64le { return f64le(tan_f64(f64(θ))) }
 @(require_results) tan_f64be :: proc "contextless" (θ: f64be) -> f64be { return f64be(tan_f64(f64(θ))) }
+// Return the tangent of θ in radians.
 tan :: proc{
 	tan_f16, tan_f16le, tan_f16be,
 	tan_f32, tan_f32le, tan_f32be,
@@ -1752,7 +1755,28 @@ atan2_f64be :: proc "contextless" (y, x: f64be) -> f64be {
 	// TODO(bill): Better atan2_f32
 	return f64be(atan2_f64(f64(y), f64(x)))
 }
+/*
+ Return the arc tangent of y/x in radians. Defined on the domain [-∞, ∞] for x and y with a range of [-π, π]
 
+ Special cases:
+	atan2(y, NaN)     = NaN
+	atan2(NaN, x)     = NaN
+	atan2(+0, x>=0)   = + 0
+	atan2(-0, x>=0)   = - 0
+	atan2(+0, x<=-0)  = + π
+	atan2(-0, x<=-0)  = - π
+	atan2(y>0, 0)     = + π/2
+	atan2(y<0, 0)     = - π/2
+	atan2(+∞, +∞)     = + π/4
+	atan2(-∞, +∞)     = - π/4
+	atan2(+∞, -∞)     =   3π/4
+	atan2(-∞, -∞)     = - 3π/4
+	atan2(y, +∞)      =   0
+	atan2(y>0, -∞)    = + π
+	atan2(y<0, -∞)    = - π
+	atan2(+∞, x)      = + π/2
+	atan2(-∞, x)      = - π/2
+*/
 atan2 :: proc{
 	atan2_f64, atan2_f32, atan2_f16,
 	atan2_f64le, atan2_f64be,
@@ -1760,6 +1784,7 @@ atan2 :: proc{
 	atan2_f16le, atan2_f16be,
 }
 
+// Return the arc tangent of x, in radians. Defined on the domain of [-∞, ∞] with a range of [-π/2, π/2]
 @(require_results)
 atan :: proc "contextless" (x: $T) -> T where intrinsics.type_is_float(T) {
 	return atan2(x, 1)
@@ -1871,6 +1896,7 @@ asin_f16le :: proc "contextless" (x: f16le) -> f16le {
 asin_f16be :: proc "contextless" (x: f16be) -> f16be {
 	return f16be(asin_f64(f64(x)))
 }
+// Return the arc sine of x, in radians. Defined on the domain of [-1, 1] with a range of [-π/2, π/2]
 asin :: proc{
 	asin_f64, asin_f32, asin_f16,
 	asin_f64le, asin_f64be,
@@ -1985,6 +2011,7 @@ acos_f16le :: proc "contextless" (x: f16le) -> f16le {
 acos_f16be :: proc "contextless" (x: f16be) -> f16be {
 	return f16be(acos_f64(f64(x)))
 }
+// Return the arc cosine of x, in radians. Defined on the domain of [-1, 1] with a range of [0, π].
 acos :: proc{
 	acos_f64, acos_f32, acos_f16,
 	acos_f64le, acos_f64be,