From f1b85a55da572eccd09e3b96c216dd28e93e4d75 Mon Sep 17 00:00:00 2001
From: Florian Wendelborn <1133858+FlorianWendelborn@users.noreply.github.com>
Date: Sun, 24 Nov 2024 07:28:31 +0100
Subject: [PATCH] version(0.3.1): Improve JSDoc

---
 package.json    |  2 +-
 readme.md       |  2 --
 source/index.ts | 42 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index fce26b8..313115c 100644
--- a/package.json
+++ b/package.json
@@ -34,5 +34,5 @@
 		"test": "bun test"
 	},
 	"types": "dist/index.d.ts",
-	"version": "0.3.0"
+	"version": "0.3.1"
 }
diff --git a/readme.md b/readme.md
index 1c5689c..2c5aa45 100644
--- a/readme.md
+++ b/readme.md
@@ -119,8 +119,6 @@ Calculates the maximum of the provided numbers. Ignores `null` and `undefined`.
 
 Calculates the minimum of the provided numbers. Ignores `null` and `undefined`. Returns `null` if no proper number was provided
 
-Returns `null` on division by zero unless `treatNullishAsZero` is set (in which case it returns `0`).
-
 ### `NullishMath.unwrap(NullishMath | number | null | undefined): number | null`
 
 Converts the input to either `number | null`. General-purpose equivalent of `nm.end()`
diff --git a/source/index.ts b/source/index.ts
index 10d16e8..0589ef7 100644
--- a/source/index.ts
+++ b/source/index.ts
@@ -7,6 +7,9 @@ export class NullishMath {
 		this.#value = NullishMath.unwrap(value)
 	}
 
+	/**
+	 * Calculates the average of the provided numbers. By default, `null`s are excluded from the average. This can be changed by setting the `treatNullishAsZero` option. With this flag, nullish numbers get counted as a `0` and thus impact the average.
+	 */
 	static average = (
 		numbers: NullishNumber[],
 		options: {
@@ -36,6 +39,9 @@ export class NullishMath {
 		return nm(sumValid).divide(countValid)
 	}
 
+	/**
+	 * Calculates the maximum of the provided numbers. Ignores `null` and `undefined`. Returns `null` if no proper number was provided
+	 */
 	static max = (numbers: NullishNumber[]): NullishMath => {
 		let max: number | null = null
 
@@ -50,6 +56,9 @@ export class NullishMath {
 		return nm(max)
 	}
 
+	/**
+	 * Calculates the minimum of the provided numbers. Ignores `null` and `undefined`. Returns `null` if no proper number was provided
+	 */
 	static min = (numbers: NullishNumber[]): NullishMath => {
 		let min: number | null = null
 
@@ -64,6 +73,9 @@ export class NullishMath {
 		return nm(min)
 	}
 
+	/**
+	 * Converts the input to either `number | null`. General-purpose equivalent of `nm.end()`
+	 */
 	static unwrap(value: NullishNumber) {
 		if (value === null) return null
 		if (value === undefined) return null
@@ -71,6 +83,9 @@ export class NullishMath {
 		return value.end()
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the sum of the current value and the given number.
+	 */
 	add(number: NullishNumber): NullishMath {
 		const n = NullishMath.unwrap(number)
 
@@ -79,6 +94,9 @@ export class NullishMath {
 		return new NullishMath(this.#value + n)
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the sum of the current value and the given numbers.
+	 */
 	addMany(...numbers: NullishNumber[]) {
 		let result = this.#value
 
@@ -151,6 +169,9 @@ export class NullishMath {
 		return this.#value !== n
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the difference of the current value and the given number.
+	 */
 	subtract(number: NullishNumber): NullishMath {
 		const n = NullishMath.unwrap(number)
 
@@ -159,6 +180,9 @@ export class NullishMath {
 		return new NullishMath(this.#value - n)
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the difference of the current value and the given numbers.
+	 */
 	subtractMany(...numbers: NullishNumber[]) {
 		let result = this.#value
 
@@ -175,6 +199,9 @@ export class NullishMath {
 		return new NullishMath(result)
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the product of the current value and the given number.
+	 */
 	multiply(number: NullishNumber): NullishMath {
 		const n = NullishMath.unwrap(number)
 
@@ -183,6 +210,9 @@ export class NullishMath {
 		return new NullishMath(this.#value * n)
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the product of the current value and the given numbers.
+	 */
 	multiplyMany(...numbers: NullishNumber[]) {
 		let result = this.#value
 
@@ -199,6 +229,9 @@ export class NullishMath {
 		return new NullishMath(result)
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the quotient of the current value and the given number.
+	 */
 	divide(number: NullishNumber): NullishMath {
 		const n = NullishMath.unwrap(number)
 
@@ -207,6 +240,9 @@ export class NullishMath {
 		return new NullishMath(this.#value / n)
 	}
 
+	/**
+	 * Returns a new instance of `NullishMath` with the quotient of the current value and the given numbers.
+	 */
 	divideMany(...numbers: NullishNumber[]) {
 		let result = this.#value
 
@@ -223,11 +259,17 @@ export class NullishMath {
 		return new NullishMath(result)
 	}
 
+	/**
+	 * Returns the final value of the `NullishMath` instance. If any of the values passed to the math operation methods are `null` or `undefined`, the final value will be `null`.
+	 */
 	end() {
 		return this.#value
 	}
 }
 
+/**
+ * Creates a new `NullishMath` object with an initial value.
+ */
 export function nm(value: NullishNumber) {
 	return new NullishMath(value)
 }