docs: Elevate sin() docs with refined examples & well-defined constraints

.devcontainer/devcontainer.json

@@ -10,9 +10,7 @@
   "postCreateCommand": "./.devcontainer/post-create",
   "customizations": {
     "codespaces": {
-      "openFiles": [
-        "README.md"
-      ]
+      "openFiles": ["README.md"]
     },
     "vscode": {
       "settings": {

lib/node_modules/@stdlib/math/base/special/sin/docs/repl.txt

@@ -1,28 +1,103 @@
-
-{{alias}}( x )
+sin( x )
     Computes the sine of a number.
 
     Parameters
     ----------
     x: number
-        Input value (in radians).
+        Input value (in radians). Can be any number, including `NaN` or `Infinity`.
 
     Returns
     -------
     y: number
-        Sine.
+        Sine of the input value, a number between -1 and 1. Returns `NaN` for invalid inputs like `NaN` or `Infinity`.
+
+    Notes
+    -----
+    - The sine function is periodic with a period of 2π (approximately 6.28 radians), so `sin(x) = sin(x % 6.28)`.
+    - The function satisfies the identity `sin(-x) = -sin(x)`.
+    - Useful for smooth game movements, sound wave adjustments, and geometric calculations.
+    - To convert degrees to radians, multiply by π/180 (e.g., `sin(60 * 3.14 / 180) ≈ 0.8660` for 60 degrees).
+    - For repeated calculations, store the result to avoid recomputing (e.g., `let h = sin(1.5)`).
 
     Examples
     --------
-    > var y = {{alias}}( 0.0 )
-    ~0.0
-    > y = {{alias}}( {{alias:@stdlib/constants/float64/pi}}/2.0 )
-    ~1.0
-    > y = {{alias}}( -{{alias:@stdlib/constants/float64/pi}}/6.0 )
-    ~-0.5
-    > y = {{alias}}( NaN )
+    > var y = sin( 0.0 )
+    0.0
+
+    > y = sin( {{alias:@stdlib/constants/float64/pi}} / 2.0 )
+    1.0
+
+    > y = sin( -{{alias:@stdlib/constants/float64/pi}} / 6.0 )
+    -0.5
+
+    > y = sin( 0.7853981633974483 )
+    ~0.7071
+
+    > y = sin( {{alias:@stdlib/constants/float64/pi}} )
+    0.0
+
+    > y = sin( 2 * {{alias:@stdlib/constants/float64/pi}} )
+    0.0
+
+    > y = sin( {{alias:@stdlib/constants/float64/pi}} / 3.0 )
+    ~0.8660
+
+    > y = sin( -{{alias:@stdlib/constants/float64/pi}} )
+    0.0
+
+    > y = sin( Infinity )
+    NaN
+
+    > y = sin( NaN )
     NaN
 
+    > y = sin( 1e308 )
+    NaN
+
+    > y = sin( -1e308 )
+    NaN
+
+    > y = sin( 1e-308 )
+    ~1e-308
+
+    > y = sin( -0.0 )
+    -0.0
+
+    > y = sin( 3 * {{alias:@stdlib/constants/float64/pi}} / 2.0 )
+    -1.0
+
+    > // Simulate a fading light effect:
+    > for (let time = 0; time < 5; time += 0.5) {
+    >     let glow = (sin(time) + 1) / 2;
+    >     console.log(`Glow ${time}: ${glow.toFixed(2)}`);
+    > }
+    Glow 0: 0.50
+    Glow 0.5: 0.73
+    Glow 1: 0.91
+    ...
+
+    > // Mix two sine waves:
+    > let mix = sin(1.5) + sin(2.5);
+    > mix
+    ~-0.589
+
+    > // C example to simulate a bouncing ball:
+    > // Save as `bounce.c` and compile with `gcc bounce.c -lm`
+    > #include <math.h>
+    > #include <stdio.h>
+    > int main() {
+    >     for (int step = 0; step < 5; step++) {
+    >         printf("Height %d: %.2f\n", step, sin(step * 0.5));
+    >     }
+    >     return 0;
+    > }
+    Height 0: 0.00
+    Height 1: 0.48
+    Height 2: 0.91
+    ...
+
     See Also
     --------
-
+    cos( x ): Computes the cosine, a related trigonometric function.
+    tan( x ): Computes the tangent, useful for slopes.
+    {{alias:@stdlib/constants/float64/pi}}: The constant π (approximately 3.14159).

lib/node_modules/@stdlib/math/base/special/sin/docs/types/index.d.ts

@@ -21,28 +21,130 @@
 /**
 * Computes the sine of a number.
 *
+* ## Notes
+* - The input value `x` must be in radians. To convert degrees to radians, multiply by `π/180` (e.g., `sin(45 * Math.PI / 180)`).
+* - The input `x` should be a finite number for meaningful results. Non-finite inputs like `Infinity`, `-Infinity`, or `NaN` return `NaN`.
+* - For very large finite inputs (e.g., `|x| > 1e308`), the result may lose precision due to the periodic nature of sine and floating-point limitations.
+* - The function returns a value between -1 and 1.
+* - The sine function is periodic with a period of 2π (approximately 6.28 radians), so `sin(x) = sin(x % (2 * Math.PI))`.
+* - The function satisfies the symmetry property `sin(-x) = -sin(x)`.
+* - For very small inputs (`|x| < 1e-308`), `sin(x) ≈ x` due to the small-angle approximation.
+* - The function preserves the sign of zero: `sin(-0.0)` returns `-0.0`.
+*
 * @param x - input value (in radians)
 * @returns sine
 *
 * @example
+* // Basic example: sine of 0 radians (0 degrees)
 * var v = sin( 0.0 );
-* // returns ~0.0
+* // returns 0.0
+*
+* @example
+* // Sine of π/2 radians (90 degrees), where sine reaches its maximum
+* var v = sin( 3.141592653589793 / 2.0 );
+* // returns 1.0
+*
+* @example
+* // Sine of -π/6 radians (-30 degrees), a negative angle
+* var v = sin( -3.141592653589793 / 6.0 );
+* // returns -0.5
+*
+* @example
+* // Sine of π radians (180 degrees), a full half-circle
+* var v = sin( 3.141592653589793 );
+* // returns 0.0
+*
+* @example
+* // Sine of π/4 radians (45 degrees), a common angle where sin(π/4) = √2/2
+* var v = sin( 3.141592653589793 / 4.0 );
+* // returns ~0.7071 (approximately √2/2)
+*
+* @example
+* // Sine of π/3 radians (60 degrees), another common angle where sin(π/3) = √3/2
+* var v = sin( 3.141592653589793 / 3.0 );
+* // returns ~0.8660 (approximately √3/2)
+*
+* @example
+* // Sine of 3π/2 radians (270 degrees), where sine reaches its minimum
+* var v = sin( 3 * 3.141592653589793 / 2.0 );
+* // returns -1.0
 *
 * @example
-* var v = sin( 3.141592653589793/2.0 );
-* // returns ~1.0
+* // Edge case: sine of negative zero, should preserve the sign
+* var v = sin( -0.0 );
+* // returns -0.0
 *
 * @example
-* var v = sin( -3.141592653589793/6.0 );
-* // returns ~-0.5
+* // Edge case: sine of a very small number, where sin(x) ≈ x
+* var v = sin( 1e-308 );
+* // returns ~1e-308
 *
 * @example
+* // Edge case: sine of a very large number, exceeds safe computation range
+* var v = sin( 1e308 );
+* // returns NaN
+*
+* @example
+* // Edge case: sine of negative infinity, non-finite input
+* var v = sin( -Infinity );
+* // returns NaN
+*
+* @example
+* // Edge case: sine of NaN, invalid input
 * var v = sin( NaN );
 * // returns NaN
+*
+* @example
+* // Practical use: animate a pulsating effect (e.g., for a UI element)
+* function pulsate(time: number): number {
+*     return 0.5 + 0.5 * sin(time); // Oscillates between 0 and 1
+* }
+* for (let t = 0; t < 5; t += 0.5) {
+*     console.log(`Time: ${t.toFixed(1)}, Pulse: ${pulsate(t).toFixed(3)}`);
+* }
+* // Outputs: Time: 0.0, Pulse: 0.500; Time: 0.5, Pulse: 0.739; etc.
+*
+* @example
+* // Practical use: generate a wave pattern with multiple frequencies (e.g., for audio synthesis)
+* function generateWave(time: number, freq1: number, freq2: number): number {
+*     // Combine two sine waves with different frequencies
+*     const wave1 = sin(freq1 * time); // First frequency component
+*     const wave2 = sin(freq2 * time); // Second frequency component
+*     return (wave1 + wave2) / 2; // Average the waves to keep amplitude between -1 and 1
+* }
+* for (let t = 0; t < 5; t += 0.5) {
+*     console.log(`Time: ${t.toFixed(1)}, Wave: ${generateWave(t, 1.0, 2.0).toFixed(3)}`);
+* }
+* // Outputs: Time: 0.0, Wave: 0.000; Time: 0.5, Wave: 0.609; etc.
+*
+* @example
+* // Test cases to verify behavior
+* function testSin(): void {
+*     // Test basic values
+*     if (sin(0.0) !== 0.0) {
+*         throw new Error('Expected sin(0.0) to be 0.0');
+*     }
+*     if (sin(3.141592653589793 / 2.0) !== 1.0) {
+*         throw new Error('Expected sin(π/2) to be 1.0');
+*     }
+*     if (sin(3.141592653589793) !== 0.0) {
+*         throw new Error('Expected sin(π) to be 0.0');
+*     }
+*     // Test common angle
+*     if (Math.abs(sin(3.141592653589793 / 4.0) - 0.7071067811865476) > 1e-10) {
+*         throw new Error('Expected sin(π/4) to be approximately 0.7071067811865476');
+*     }
+*     // Test edge cases
+*     if (sin(-0.0) !== -0.0) {
+*         throw new Error('Expected sin(-0.0) to be -0.0');
+*     }
+*     if (isNaN(sin(1e308)) === false) {
+*         throw new Error('Expected sin(1e308) to be NaN');
+*     }
+* }
 */
 declare function sin( x: number ): number;
 
-
 // EXPORTS //
 
-export = sin;
+export = sin;