builtin: document all functions in float.v (#7904)

vlib/builtin/float.v

@@ -5,8 +5,11 @@ module builtin
 import strconv
 
 #include <float.h>
-// ----- f64 to string functions -----
-// str return a f64 as string in suitable notation
+/*
+-----------------------------------
+----- f64 to string functions -----
+*/
+// str return a `f64` as `string` in suitable notation.
 [inline]
 pub fn (x f64) str() string {
 	abs_x := f64_abs(x)
@@ -17,12 +20,14 @@ pub fn (x f64) str() string {
 	}
 }
 
+// str returns the value of the `any_float` as a `string`.
 [inline]
 pub fn (d any_float) str() string {
 	return f64(d).str()
 }
 
-// return a string of the input f64 in scientific notation with digit_num deciamals displayed, max 17 digits
+// strsci returns the `f64` as a `string` in scientific notation with `digit_num` deciamals displayed, max 17 digits.
+// Example: assert f64(1.234).strsci(3) == '1.234e+00'
 [inline]
 pub fn (x f64) strsci(digit_num int) string {
 	mut n_digit := digit_num
@@ -34,14 +39,18 @@ pub fn (x f64) strsci(digit_num int) string {
 	return strconv.f64_to_str(x, n_digit)
 }
 
-// return a decimal notation of the input f64
+// strlong returns a decimal notation of the `f64` as a `string`.
+// Example: assert f64(1.23456).strlong() == '1.23456'
 [inline]
 pub fn (x f64) strlong() string {
 	return strconv.f64_to_str_l(x)
 }
 
-// ----- f32 to string functions -----
-// str return a f32 as string in suitable notation
+/*
+-----------------------------------
+----- f32 to string functions -----
+*/
+// str returns a `f32` as `string` in suitable notation.
 [inline]
 pub fn (x f32) str() string {
 	abs_x := f32_abs(x)
@@ -52,7 +61,8 @@ pub fn (x f32) str() string {
 	}
 }
 
-// return a string of the input f32 in scientific notation with digit_num deciamals displayed, max 8 digits
+// strsci returns the `f32` as a `string` in scientific notation with `digit_num` deciamals displayed, max 8 digits.
+// Example: assert f32(1.234).strsci(3) == '1.234e+00'
 [inline]
 pub fn (x f32) strsci(digit_num int) string {
 	mut n_digit := digit_num
@@ -64,13 +74,18 @@ pub fn (x f32) strsci(digit_num int) string {
 	return strconv.f32_to_str(x, n_digit)
 }
 
-// return a decimal notation of the input f32
+// strlong returns a decimal notation of the `f32` as a `string`.
 [inline]
 pub fn (x f32) strlong() string {
 	return strconv.f32_to_str_l(x)
 }
 
-// ----- C functions -----
+/*
+-----------------------
+----- C functions -----
+*/
+// f32_abs returns the absolute value of `a` as a `f32` value.
+// Example: assert f32_abs(-2.0) == 2.0
 [inline]
 pub fn f32_abs(a f32) f32 {
 	return if a < 0 {
@@ -80,6 +95,8 @@ pub fn f32_abs(a f32) f32 {
 	}
 }
 
+// f64_abs returns the absolute value of `a` as a `f64` value.
+// Example: assert f64_abs(-2.0) == f64(2.0)
 [inline]
 fn f64_abs(a f64) f64 {
 	return if a < 0 {
@@ -89,7 +106,8 @@ fn f64_abs(a f64) f64 {
 	}
 }
 
-
+// f32_max returns the largest `f32` of input `a` and `b`.
+// Example: assert f32_max(2.0,3.0) == 3.0
 [inline]
 pub fn f32_max(a f32, b f32) f32 {
 	return if a > b {
@@ -99,6 +117,8 @@ pub fn f32_max(a f32, b f32) f32 {
 	}
 }
 
+// f32_min returns the smallest `f32` of input `a` and `b`.
+// Example: assert f32_min(2.0,3.0) == 2.0
 [inline]
 pub fn f32_min(a f32, b f32) f32 {
 	return if a < b {
@@ -108,6 +128,8 @@ pub fn f32_min(a f32, b f32) f32 {
 	}
 }
 
+// f64_max returns the largest `f64` of input `a` and `b`.
+// Example: assert f64_max(2.0,3.0) == 3.0
 [inline]
 pub fn f64_max(a f64, b f64) f64 {
 	return if a > b {
@@ -117,6 +139,8 @@ pub fn f64_max(a f64, b f64) f64 {
 	}
 }
 
+// f64_min returns the smallest `f64` of input `a` and `b`.
+// Example: assert f64_min(2.0,3.0) == 2.0
 [inline]
 fn f64_min(a f64, b f64) f64 {
 	return if a < b {
@@ -126,6 +150,9 @@ fn f64_min(a f64, b f64) f64 {
 	}
 }
 
+// eq_epsilon returns true if the `f32` is equal to input `b`.
+// using an epsilon of typically 1E-5 or higher (backend/compiler dependent).
+// Example: assert f32(2.0).eq_epsilon(2.0)
 [inline]
 pub fn (a f32) eq_epsilon(b f32) bool {
 	hi := f32_max(f32_abs(a), f32_abs(b))
@@ -137,6 +164,9 @@ pub fn (a f32) eq_epsilon(b f32) bool {
 	}
 }
 
+// eq_epsilon returns true if the `f64` is equal to input `b`.
+// using an epsilon of typically 1E-9 or higher (backend/compiler dependent).
+// Example: assert f64(2.0).eq_epsilon(2.0)
 [inline]
 pub fn (a f64) eq_epsilon(b f64) bool {
 	hi := f64_max(f64_abs(a), f64_abs(b))