docs: enhance TypeScript declaration for sin() with input constraints and more features

Author: ishikajais27

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;