[doc-core:math] Documentation for `core:math` package. (partials) #4961

kelreeeeey · 2025-03-23T18:56:46Z

Documented: (all of this will be gradually updated)

math.to_radians proc group
math.to_degrees proc group

DEG_PER_RAD constant
RAD_PER_DEG constant

math.asin proc group
math.acos proc group
math.atan proc group

More detail underlying explanation/issue in #2358 (comment)

…dure group

…procedure groups

… procedure groups

core/math/math.odin

flysand7 · 2025-03-23T20:49:02Z

core/math/math.odin

+/*
+Return square root of given input.
+
+**Only accept floats**


I would probably also document the behavior for when the input is an inf, nan, a negative zero and possibly subnormal.

yeah, that is a good point! I added more examples for the special cases according to Float_Class enum

gingerBill · 2025-03-24T09:49:27Z

core/math/math.odin

+        x_float :      = 4.0    ;    sqrt_x_float   := math.sqrt(x_float) // using default type of f16
+        x_f16   :f16   = 30.90  ;    sqrt_x_f16     := math.sqrt(x_f16)
+        x_f16le :f16le = 50.0   ;    sqrt_x_f16le   := math.sqrt(x_f16le)
+        x_f16be :f16be = 100    ;    sqrt_x_f16be   := math.sqrt(x_f16be)
+        x_f32   :f32   = 4.89   ;    sqrt_x_f32     := math.sqrt(x_f32)
+        x_f32le :f32le = 3.14   ;    sqrt_x_f32le   := math.sqrt(x_f32le)
+        x_f32be :f32be = 2.0    ;    sqrt_x_f32be   := math.sqrt(x_f32be)
+        x_f64   :f64   = 0.0578 ;    sqrt_x_f64     := math.sqrt(x_f64)
+        x_f64le :f64le = 1000.6 ;    sqrt_x_f64le   := math.sqrt(x_f64le)
+        x_f64be :f64be = 89.98  ;    sqrt_x_f64be   := math.sqrt(x_f64be)


Use the standard style convention here too please.

x_float: f64 = 4.0; sqrt_x_float := math.sqrt(x_float) // using default type of f64 x_f16: f16 = 30.90; sqrt_x_f16 := math.sqrt(x_f16) x_f16le: f16le = 50.0; sqrt_x_f16le := math.sqrt(x_f16le) x_f16be: f16be = 100; sqrt_x_f16be := math.sqrt(x_f16be) x_f32: f32 = 4.89; sqrt_x_f32 := math.sqrt(x_f32) x_f32le: f32le = 3.14; sqrt_x_f32le := math.sqrt(x_f32le) x_f32be: f32be = 2.0; sqrt_x_f32be := math.sqrt(x_f32be) x_f64: f64 = 0.0; sqrt_x_f64 := math.sqrt(x_f64) x_f64le: f64le = 1000.0; sqrt_x_f64le := math.sqrt(x_f64le) x_f64be: f64be = 89.98; sqrt_x_f64be := math.sqrt(x_f64be)

Thank you! fixed it and added more examples for special cases according to Float_Class

…yle to standard style convention

…e conventions according to comment odin-lang/Odin#4961 (comment) and odin-lang/Odin#4961 (comment)

… types. added doc for `RAD_PER_DEG` and `DEG_PER_RAD` constant

…cial cases

flysand7

Many of these issues repeat so not that I didn't put them on every place of occurrence.

flysand7 · 2025-03-28T22:25:48Z

core/math/math.odin

@@ -34,8 +37,8 @@ MAX_F64_PRECISION :: 16 // Maximum number of meaningful digits after the decimal
 MAX_F32_PRECISION ::  8 // Maximum number of meaningful digits after the decimal point for 'f32'
 MAX_F16_PRECISION ::  4 // Maximum number of meaningful digits after the decimal point for 'f16'

-RAD_PER_DEG :: TAU/360.0
-DEG_PER_RAD :: 360.0/TAU
+RAD_PER_DEG :: TAU/360.0 // Being used to convert degrees to radians. (see `math.to_radians`)


For documentation, although sounds counterintuitive, you should duplicate it rather than making references to other points of documentation. For constants of the kind X_PER_Y I suggest you show how to use these constants to perform the conversion.

flysand7 · 2025-03-28T22:30:12Z

core/math/math.odin

+**Only accept floats**
+
+Inputs:
+- x: input value of type floats


Although pkg.odin-lang might do this conversion automatically, you should respect the LSP and wrap inputs and return value names in backticks, like this:

- `x`: Input value.

Also please form a proper sentence when describing inputs and returns of a procedure. Meaning, capitalizing the first letter and putting a period at the end.

You don't have to specify that x in this function is a float, because you already specified this in the Note above. The point of this section is to establish a connection between the function parameters and its description.

flysand7 · 2025-03-28T22:32:30Z

core/math/math.odin

+        y_f64be_nan:  f64be = math.nan_f64be(); sqrt_y_f64be_nan    := math.sqrt(y_f64be_nan)    // NaN
+        y_f16le_nan:  f16le = math.nan_f16le(); sqrt_y_f16le_nan    := math.sqrt(y_f16le_nan)    // NaN
+
+Output:


Your example doesn't "print" anything, so there's no "output". This is going to be a problem with the documentation tester that runs all examples inside documentation and checks the output. I suggest you reformat these examples to print results. Might help to not focus on types as much as on values.

flysand7 · 2025-03-28T22:33:02Z

core/math/math.odin

+
+**Only accept floats**
+
+math.sin assumes input in radians.


Suggested change

math.sin assumes input in radians.

This procedure assumes the input angle in radians.

flysand7 · 2025-03-28T22:33:45Z

core/math/math.odin

@@ -60,7 +114,52 @@ 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.
+/*
+Return sine of given input in radian.


The result is not in "radians", better move the clarification in the description.

Suggested change

Return sine of given input in radian.

Calculates the sine of a value.

flysand7 · 2025-03-28T22:38:38Z

core/math/math.odin

 to_radians :: proc{
 	to_radians_f16, to_radians_f16le, to_radians_f16be,
 	to_radians_f32, to_radians_f32le, to_radians_f32be,
 	to_radians_f64, to_radians_f64le, to_radians_f64be,
 }
+/*
+Convert given input to degrees.


Suggested change

Convert given input to degrees.

Converts a given angle, in radians, to degrees.

flysand7 · 2025-03-28T22:39:12Z

core/math/math.odin

@@ -1790,7 +2071,91 @@ 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]
+/*
+Return inverse of tangent (arctan) of given input.


Suggested change

Return inverse of tangent (arctan) of given input.

Computes the inverse of tangent (arctan) of given input.

flysand7 · 2025-03-28T22:40:11Z

core/math/math.odin

+- x: ouput value that with same type of the input in radians
+
+Example:
+        x30_f32:     f32 = 30.0;                     tan_x30_f32     := math.tan(x30_f32);     atan_x30_f32     := math.atan(tan_x30_f32)     // without converting to radians


This is going to look horrible in the text editor with wrapping on documentation snippets, and would require some scrolling on the website. Maybe you should wrap these manually

flysand7 · 2025-03-28T22:40:53Z

core/math/math.odin

+            invers_asin_x60:     f64le = math.to_degrees(asin_x60_f64le)
+            invers_asin_x60_rad: f64le = math.to_degrees(asin_x60_f64le_rad)
+
+        // special cases. (see Float_Class and math.classify)


Got indentation problems here. Should be tabs

flysand7 · 2025-03-28T22:43:13Z

core/math/math.odin

+    and x is set to 1. See math.atan2 for detail.
+
+Beware of special cases i.e. `-0.0`, `+0.0`, `-Inf`, `+Inf`, and `Nan` (see examples).
+For special cases related math.atan2(x, 1)


Should change that to just listing special cases for atan without referring to atan2.

kelreeeeey added 6 commits March 23, 2025 22:07

initial doc for math. Add doc for Float_class enum and sqrt proce…

78669f4

…dure group

add example for math.sqrt

ba51224

[doc-core:math] added input output in math.sqrt procedure group

d15d6b5

[doc-core:math] added doc for math.sin, math.cos, and math.tan …

17ffcbd

…procedure groups

Merge branch 'odin-lang:master' into master

449e8bf

[doc-core:math] added doc for math.to_radians and math.to_degrees…

ab4270e

… procedure groups

flysand7 reviewed Mar 23, 2025

View reviewed changes

gingerBill reviewed Mar 24, 2025

View reviewed changes

kelreeeeey added 3 commits March 24, 2025 20:13

[doc-core:math] fix typo in Float_Class

9d4ee04

[doc-core:math] added more example to math.sqrt and change their st…

4a21de5

…yle to standard style convention

Merge branch 'odin-lang:master' into master

0c50e4d

kelreeeeey added 16 commits March 24, 2025 21:15

[doc-core:math] update doc.odin explained procedure groups accepted…

c4e93f0

… types. added doc for `RAD_PER_DEG` and `DEG_PER_RAD` constant

Merge branch 'master' of https://github.com/kelreeeeey/Odin

7ed7800

[doc-core:math] update math.to_degrees, added more examples for spe…

70a37c5

…cial cases

[doc-core:math] update math.to_radians, added more examples for spe…

177ad62

…cial cases

[doc-core:math] update math.tan, added more examples for special cases

4af9e1e

[doc-core:math] update math.cos, added more examples for special cases

ea4fe8c

[doc-core:math] update math.sin, added more examples for special cases

cf3b50a

[doc-core:math] fixed multiline comment

b7ad99c

[doc-core:math] fixed multiline comment

1edeace

Merge branch 'odin-lang:master' into master

fc453bf

[doc-core:math] added doc for math.asin proc and update doc.math

e54a541

[doc-core:math] fix typo in doc math.asin

b9ce613

[doc-core:math] remove unnecesary lines in doc math.asin

293e89a

[doc-core:math] added doc for math.acos

884cef0

[doc-core:math] added doc for math.atan

c6bf715

Merge branch 'odin-lang:master' into master

dac5931

flysand7 reviewed Mar 28, 2025

View reviewed changes

	math.sin assumes input in radians.
	This procedure assumes the input angle in radians.

	Return sine of given input in radian.
	Calculates the sine of a value.

	Convert given input to degrees.
	Converts a given angle, in radians, to degrees.

	Return inverse of tangent (arctan) of given input.
	Computes the inverse of tangent (arctan) of given input.

Uh oh!

[doc-core:math] Documentation for core:math package. (partials) #4961

Are you sure you want to change the base?

[doc-core:math] Documentation for core:math package. (partials) #4961

Conversation

kelreeeeey commented Mar 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flysand7 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

[doc-core:math] Documentation for `core:math` package. (partials) #4961

[doc-core:math] Documentation for `core:math` package. (partials) #4961

kelreeeeey commented Mar 23, 2025 •

edited

Loading