fixing JSDOCS for some files in Math folder that missing it

Author: mohmmadAyesh

Diff for: Maths/ArmstrongNumber.js

@@ -5,7 +5,8 @@
  * An Armstrong number is equal to the sum of its own digits each raised to the power of the number of digits.
  * For example, 370 is an Armstrong number because 3*3*3 + 7*7*7 + 0*0*0 = 370.
  * An Armstrong number is often called Narcissistic number.
- *
+ * @param {number} num - The number to check if it is an Armstrong number.
+ * @returns {boolean} - True if the number is an Armstrong number, false otherwise.
  */
 
 const armstrongNumber = (num) => {

Diff for: Maths/AverageMedian.js

@@ -7,7 +7,11 @@
  * if the length of the array is even number, the median value will be the average of the two middle numbers
  * else if the length of the array is odd number, the median value will be the middle number in the array
  */
-
+/**
+ * Function to find the median value of an array of numbers.
+ * @param {number[]}
+ * @returns {number} - The median value of the array.
+ */
 const averageMedian = (sourceArrayOfNumbers) => {
   const numbers = [...sourceArrayOfNumbers].sort(sortNumbers)
   const numLength = numbers.length
@@ -16,7 +20,12 @@ const averageMedian = (sourceArrayOfNumbers) => {
     ? (numbers[numLength / 2 - 1] + numbers[numLength / 2]) / 2
     : numbers[Math.floor(numLength / 2)]
 }
-
+/**
+ * Comparator function to sort numbers in ascending order.
+ * @param {number} num1
+ * @param {number} num2
+ * @returns {number}
+ */
 const sortNumbers = (num1, num2) => num1 - num2
 
 export { averageMedian }

Diff for: Maths/CheckKishnamurthyNumber.js

@@ -6,6 +6,10 @@
 */
 
 // factorial utility method.
+/**
+ * @param {Number} n
+ * @returns {Number} the factiorial of n
+ */
 const factorial = (n) => {
   let fact = 1
   while (n !== 0) {

Diff for: Maths/Coordinate.js

@@ -4,12 +4,25 @@
  Example: coorDistance(2,2,14,11) will return 15
  Wikipedia reference: https://en.wikipedia.org/wiki/Geographical_distance#Flat-surface_formulae
 */
+/**
+* @param {number} longitude1 - The longitude of the first point.
+ * @param {number} latitude1 - The latitude of the first point.
+ * @param {number} longitude2 - The longitude of the second point.
+ * @param {number} latitude2 - The latitude of the second point.
+ * @returns {number} - The Euclidean distance between the two points.
+ */
 const euclideanDistance = (longitude1, latitude1, longitude2, latitude2) => {
   const width = longitude2 - longitude1
   const height = latitude2 - latitude1
   return Math.sqrt(width * width + height * height)
 }
-
+/*
+* @param {number} longitude1 - The longitude of the first point.
+ * @param {number} latitude1 - The latitude of the first point.
+ * @param {number} longitude2 - The longitude of the second point.
+ * @param {number} latitude2 - The latitude of the second point.
+ * @returns {number} - The Manhattan distance between the two points.
+ */
 const manhattanDistance = (longitude1, latitude1, longitude2, latitude2) => {
   const width = Math.abs(longitude2 - longitude1)
   const height = Math.abs(latitude2 - latitude1)

Diff for: Maths/EulersTotient.js

@@ -7,10 +7,12 @@
   Complexity:
     O(sqrt(n))
 */
-
+/**
+ *
+ * @param {Number} n
+ * @returns {Number} count of numbers b/w 1 and n that are coprime to n
+ */
 export const EulersTotient = (n) => {
-  // input: n: int
-  // output: phi(n): count of numbers b/w 1 and n that are coprime to n
   let res = n
   for (let i = 2; i * i <= n; i++) {
     if (n % i === 0) {

Diff for: Maths/EulersTotientFunction.js

@@ -7,7 +7,12 @@
     so EulersTotientFunction(n) (or phi(n)) is the count of numbers in {1,2,3,....,n} that are relatively
     prime to n, i.e., the numbers whose GCD (Greatest Common Divisor) with n is 1.
 */
-
+/**
+ *
+ * @param {Number} x
+ * @param {Number} y
+ * @returns {Number} compute greatest common divisor for x and y
+ */
 const gcdOfTwoNumbers = (x, y) => {
   // x is smaller than y
   // let gcd of x and y is gcdXY

Diff for: Maths/Factors.js

@@ -6,7 +6,9 @@
  *      https://www.mathsisfun.com/definitions/factor.html
  *
  */
-
+/**
+ * @param {Number} [number=0]
+ */
 const factorsOfANumber = (number = 0) => {
   return Array.from(Array(number + 1).keys()).filter(
     (num) => number % num === 0

Diff for: Maths/FindHcf.js

@@ -3,7 +3,12 @@
     More about HCF:
         https://en.wikipedia.org/wiki/Greatest_common_divisor
  */
-
+/**
+ *
+ * @param {Number} x
+ * @param {Number} y
+ * @returns {(string|number)}
+ */
 const findHCF = (x, y) => {
   // If the input numbers are less than 1 return an error message.
   if (x < 1 || y < 1) {

Diff for: Maths/FindLcm.js

@@ -14,6 +14,12 @@
 import { findHCF } from './FindHcf'
 
 // Find the LCM of two numbers.
+/**
+ *
+ * @param {Number} num1
+ * @param {Number} num2
+ * @returns
+ */
 const findLcm = (num1, num2) => {
   // If the input numbers are less than 1 return an error message.
   if (num1 < 1 || num2 < 1) {

Diff for: Maths/FriendlyNumbers.js

@@ -4,7 +4,10 @@
   Source: https://en.wikipedia.org/wiki/Friendly_number
   See also: https://mathworld.wolfram.com/FriendlyNumber.html#:~:text=The%20numbers%20known%20to%20be,numbers%20have%20a%20positive%20density.
 */
-
+/**
+ * @param {Number} firstNumber,
+ * @param {Number} secondNumber
+ */
 export const FriendlyNumbers = (firstNumber, secondNumber) => {
   // input: two integers
   // output: true if the two integers are friendly numbers, false if they are not friendly numbers
@@ -22,11 +25,17 @@ export const FriendlyNumbers = (firstNumber, secondNumber) => {
 
   return abundancyIndex(firstNumber) === abundancyIndex(secondNumber)
 }
-
+/**
+ * @param {Number} number
+ */
 function abundancyIndex(number) {
   return sumDivisors(number) / number
 }
-
+/**
+ *
+ * @param {Number} number
+ * @returns
+ */
 function sumDivisors(number) {
   let runningSumDivisors = number
   for (let i = 0; i < number / 2; i++) {

Diff for: Maths/IsDivisible.js

@@ -1,5 +1,11 @@
 // Checks if a number is divisible by another number.
-
+/**
+ *
+ * @param {Number} num1
+ * @param {Number} num2
+ * @throws {TypeError}
+ * @returns {boolean}
+ */
 export const isDivisible = (num1, num2) => {
   if (!Number.isFinite(num1) || !Number.isFinite(num2)) {
     throw new TypeError('Expected a valid real number')

Diff for: Maths/LinearSieve.js

@@ -1,3 +1,8 @@
+/**
+ *
+ * @param {Number} n
+ * @returns {Number[]} array of prime numbers untill number n
+ */
 const LinearSieve = (n) => {
   /*
    * Calculates prime numbers till a number n

Diff for: Maths/MatrixExponentiationRecursive.js

@@ -7,7 +7,11 @@
     where: d is the dimension of the square matrix
            n is the power the matrix is raised to
 */
-
+/**
+ *
+ * @param {Number} n
+ * @returns {Number[][]}
+ */
 const Identity = (n) => {
   // Input: n: int
   // Output: res: Identity matrix of size n x n

Diff for: Maths/ModularBinaryExponentiationRecursive.js

@@ -5,7 +5,6 @@
   Explanation:
     https://en.wikipedia.org/wiki/Exponentiation_by_squaring
 */
-
 const modularBinaryExponentiation = (a, n, m) => {
   // input: a: int, n: int, m: int
   // returns: (a^n) % m: int

Diff for: Maths/PerfectCube.js

@@ -3,6 +3,7 @@
  * License: GPL-3.0 or later
  *
  * This uses `round` instead of `floor` or `trunc`, to guard against potential `cbrt` accuracy errors
+ * @param {Number} num
  */
 
 const perfectCube = (num) =>