Improve JSDoc documentation

Author: oskarlh

README.md

@@ -1,5 +1,5 @@
 # cmath-js
-Implementation of parts of C's & C++'s numerics libraries in TypeScript/JavaScript.
+Implementation of parts of C++'s numerics libraries in TypeScript/JavaScript, including functions C++ inherits from C.
 
 ## Floating-point functions
 - [`copysign`](https://en.cppreference.com/w/c/numeric/math/copysign)
@@ -50,6 +50,6 @@ These functions accept either a `bigint` or an integer `number`:
 The test coverage is a perfect 100% and enforced by the publishing and pull request verification workflows.
 
 ## Contributing
-Contributions are welcomed! Feel free to make a pull request. Please add your name to `contributors` in `package.json` and run `npm run build-and-verify` before submitting your PR. By making a pull request you agree to license your contribution under [the CC0 license](https://creativecommons.org/publicdomain/zero/1.0/legalcode.en#legal-code-title) unless otherwise specified.
+Contributions are welcomed! Feel free to make a pull request. Please add your name to `contributors` in `package.json` and run `npm run build-and-verify` before submitting your PR. By opening a pull request you agree to license your contribution under [the CC0 license](https://creativecommons.org/publicdomain/zero/1.0/legalcode.en#legal-code-title) unless you specify otherwise.
 
-ESLint is used to enforce code quality and consistent formatting (with the help of Prettier). If ESLint complains when you run `npm run build-and-verify`, you can run `npm run lint-fix` to apply automatic fixes and then fix the rest of the errors manually. I recommend configuring your IDE for ESLint and Prettier. If you are using Visual Studio Code, simply installing [Microsoft's ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [the official Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) takes care of that.
+ESLint is used to enforce code quality and consistent formatting (with the help of Prettier). If ESLint complains when you run `npm run build-and-verify`, you can run `npm run lint-fix` to apply automatic fixes, and then fix the rest of the errors manually. It is recommend to configure your IDE for ESLint and Prettier. If you are using Visual Studio Code, simply installing [Microsoft's ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [the official Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) takes care of that.

package-lock.json

@@ -1,10 +1,10 @@
 // Constructing these can take a little bit of time so let's reuse them
 const floatArray = new Float64Array(1);
-const octets = new Uint8Array(floatArray.buffer);
+const octets: Uint8Array = new Uint8Array(floatArray.buffer);
 
 // DO NOT STORE THE Uint8Array RETURN VALUE FROM THIS CALL!
 // It will be mutated on the next call to this function
-export function floatOctets(num: number): Readonly<Uint8Array> {
+export function floatOctets(num: number): Readonly<Uint8Array & { length: 8 }> {
 	floatArray[0] = num;
 	return octets;
 }

src/internal/floatOctets.ts

@@ -1,16 +1,16 @@
 // Mathematical constants defined in the namespace std::numbers
 // cppreference: https://en.cppreference.com/w/cpp/numeric/constants
 
-export const e = Math.E;
+export const e: number = Math.E;
 export const egamma = 0.5772156649015329; // The Euler-Mascheroni constant
 export const inv_pi = 0.3183098861837907; // 1 / pi
 export const inv_sqrt3 = 0.5773502691896257; // 1 / sqrt(3)
 export const inv_sqrtpi = 0.5641895835477563; // 1 / sqrt(pi)
-export const ln10 = Math.LN10;
-export const ln2 = Math.LN2;
-export const log10 = Math.LOG10E;
-export const log2e = Math.LOG2E;
+export const ln10: number = Math.LN10;
+export const ln2: number = Math.LN2;
+export const log10: number = Math.LOG10E;
+export const log2e: number = Math.LOG2E;
 export const phi = 1.618033988749895; // The golden ratio
-export const pi = Math.PI;
-export const sqrt2 = Math.SQRT2;
+export const pi: number = Math.PI;
+export const sqrt2: number = Math.SQRT2;
 export const sqrt3 = 1.7320508075688772; // sqrt(3)

src/namespace-std-numbers/index.ts

@@ -1,6 +1,9 @@
-// Fills an array with sequentially increasing values
-// Cppreference: https://en.cppreference.com/w/c/numeric/math/iota
-
+/**
+ * Fills an array with sequentially increasing values
+ *
+ * Read more about the original function on
+ * - {@link https://en.cppreference.com/w/c/numeric/math/iota|Cppreference}
+ */
 export function iota(mut_arrayToFill: bigint[], startValue: bigint): void;
 export function iota(mut_arrayToFill: number[], startValue: number): void;
 export function iota(mut_arrayToFill: (bigint | number)[], startValue: bigint | number): void {

src/namespace-std/all-numbers/iota.ts

@@ -1,6 +1,13 @@
 import { floatOctets } from "../../internal/index.js";
-
-// Cppreference: https://en.cppreference.com/w/c/numeric/math/signbit
+/**
+ * Determines if a number is negative or NaN with the sign bit set.
+ * Note that the ECMAScript standard does not guarantee that +NaN and
+ * -NaN are different so this function may give unexpected results
+ * (such as always false or always true) in some JavaScript engines.
+ *
+ * Read more about the original function on
+ * - {@link https://en.cppreference.com/w/cpp/numeric/math/signbit|Cppreference}
+ */
 export function signbit(num: bigint | number): boolean {
 	return floatOctets(Number(num))[7] > 127;
 }

src/namespace-std/all-numbers/signbit.ts

@@ -1,10 +1,15 @@
 import { signbit } from "../index.js";
 
-// copysign produces a value with the magnitude of 'num' and the sign 'sign'
-// C spec: https://web.archive.org/web/20181230041359if_/http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf#subsection.7.12.11
-// Cppreference: https://en.cppreference.com/w/c/numeric/math/copysign
-// This implementation handles positive and negative zero  and positive and negative
-// NaNs (in JS engines where that difference is observable when writing NaNs to a Float64Array)
-export function copysign(/*double*/ num: number, /*double*/ sign: number): /*double*/ number {
+/**
+ * Produces a value with the magnitude of 'num' and the sign 'sign'.
+ * This implementation handles positive and negative zero and positive and negative
+ * NaNs (in JS engines where that difference is observable when writing NaNs to a Float64Array).
+ *
+ * Read more about the original function on
+ * - {@link https://en.cppreference.com/w/cpp/numeric/math/copysign|Cppreference}
+ * - {@link https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3096.pdf#subsection.7.12.11|The C23 final draft specification}
+ */
+
+export function copysign(num: number, sign: number): number {
 	return signbit(num) === signbit(sign) ? num : -num;
 }

src/namespace-std/doubles/copysign.ts

@@ -1,3 +1,8 @@
-// fabs is just like JavaScript's Math.abs
-// Cppreference: https://en.cppreference.com/w/c/numeric/math/fabs
-export const fabs = Math.abs;
+/**
+ * fabs is just like JavaScript's Math.abs.
+ *
+ * Read more about the original function on
+ * - {@link https://en.cppreference.com/w/cpp/numeric/math/fabs|Cppreference}
+ */
+
+export const fabs: (number: number) => number = Math.abs;

src/namespace-std/doubles/fabs.ts

@@ -2,14 +2,14 @@ import { frexp } from "./index.js";
 
 describe(frexp.name, () => {
 	it("decomposes a number into a normalized fraction and an integral power of two", () => {
-		expect(frexp(1)).toStrictEqual([0.5, 1]);
-		expect(frexp(1.5)).toStrictEqual([0.75, 1]);
-		expect(frexp(3 * 2 ** 500)).toStrictEqual([0.75, 502]);
-		expect(frexp(-4)).toStrictEqual([-0.5, 3]);
-		expect(frexp(Number.MAX_VALUE)).toStrictEqual([0.9999999999999999, 1024]);
-		expect(frexp(Number.MIN_VALUE)).toStrictEqual([0.5, -1073]);
-		expect(frexp(-Infinity)).toStrictEqual([-Infinity, 0]);
-		expect(frexp(-0)).toStrictEqual([-0, 0]);
-		expect(frexp(NaN)).toStrictEqual([NaN, 0]);
+		expect(frexp(1)).toStrictEqual({ exponent: 1, fraction: 0.5 });
+		expect(frexp(1.5)).toStrictEqual({ exponent: 1, fraction: 0.75 });
+		expect(frexp(3 * 2 ** 500)).toStrictEqual({ exponent: 502, fraction: 0.75 });
+		expect(frexp(-4)).toStrictEqual({ exponent: 3, fraction: -0.5 });
+		expect(frexp(Number.MAX_VALUE)).toStrictEqual({ exponent: 1024, fraction: 0.9999999999999999 });
+		expect(frexp(Number.MIN_VALUE)).toStrictEqual({ exponent: -1073, fraction: 0.5 });
+		expect(frexp(-Infinity)).toStrictEqual({ exponent: 0, fraction: -Infinity });
+		expect(frexp(-0)).toStrictEqual({ exponent: 0, fraction: -0 });
+		expect(frexp(NaN)).toStrictEqual({ exponent: 0, fraction: NaN });
 	});
 });

src/namespace-std/doubles/frexp.test.ts

@@ -1,39 +1,45 @@
-// Note: Instead of "double frexp(double arg, int* exp)" this is built as "[double, int] frexp(double arg)" due to ECMAScripts's lack of pointers
-// A hypothetical issue with this implementation is that the precision the ** operator is not defined in the ECMAScript standard,
-// however, sane ECMAScript implementations should give precise results for 2**<integer> expressions
-// Cppreference: https://en.cppreference.com/w/c/numeric/math/frexp for a more detailed description
+export interface frexp_result {
+	exponent: number;
+	fraction: number;
+}
+
+// Note: Instead of "double frexp(double arg, int* exp)" this is built as "{ exponent, fraction } frexp(double arg)" due to ECMAScripts's lack of pointers
+// A hypothetical issue with this implementation is that the precision of the ** operator is not defined in the ECMAScript standard,
+// however, it is hard to imagine a sane ECMAScript implementation would give imprecise results for 2**<integer> expressions.
+// Cppreference: https://en.cppreference.com/w/cpp/numeric/math/frexp
 // Object.is(n, frexp(n)[0] * 2 ** frexp(n)[1]) for all number values of n except when Math.isFinite(n) && Math.abs(n) > 2**1023
 // Object.is(n, (2 * frexp(n)[0]) * 2 ** (frexp(n)[1] - 1)) for all number values of n
 // Object.is(n, frexp(n)[0]) for these values of n: 0, -0, NaN, Infinity, -Infinity
 // Math.abs(frexp(n)[0]) is >= 0.5 and < 1.0 for any other number-type value of n
-export function frexp(
-	/*double*/ num: number,
-): [/*double*/ fraction: number, /*int*/ exponent: number] {
+export function frexp(num: number): frexp_result {
 	if (num === 0 || !Number.isFinite(num)) {
-		return [num, 0];
+		return { exponent: 0, fraction: num };
 	}
 
 	const absNum: number = Math.abs(num);
 
-	let exp: number = Math.max(-1023, Math.floor(Math.log2(absNum)) + 1);
-	let x: number = absNum * 2 ** -exp;
+	let exponent: number = Math.max(-1023, Math.floor(Math.log2(absNum)) + 1);
+	let fraction: number = absNum * 2 ** -exponent;
 
 	// These while loops compensate for rounding errors that may occur because of ECMAScript's Math.log2's undefined precision
 	// and the first one also helps work around the issue of 2 ** -exp === Infinity when exp <= -1024
-	while (x < 0.5) {
-		x *= 2;
-		--exp;
+	while (fraction < 0.5) {
+		fraction *= 2;
+		--exponent;
 	}
 
 	// istanbul ignore next - This might never run and that's okay. See the above comment
-	while (x >= 1) {
-		x *= 0.5;
-		++exp;
+	while (fraction >= 1) {
+		fraction *= 0.5;
+		++exponent;
 	}
 
 	if (num < 0) {
-		x = -x;
+		fraction = -fraction;
 	}
 
-	return [x, exp];
+	return {
+		exponent,
+		fraction,
+	};
 }