fix comment indents and docs

Author: salehhashemi1992

Ciphers/MonoAlphabeticCipher.php

@@ -7,9 +7,11 @@ function monoAlphabeticCipher($key, $alphabet, $text)
 {
     $cipherText = ''; // the cipher text (can be decrypted and encrypted)
 
+    // check if the text length matches
     if (strlen($key) != strlen($alphabet)) {
         return false;
-    } // check if the text length matches
+    }
+
     $text = preg_replace('/[0-9]+/', '', $text); // remove all the numbers
 
     for ($i = 0; $i < strlen($text); $i++) {
@@ -20,6 +22,7 @@ function monoAlphabeticCipher($key, $alphabet, $text)
             $cipherText .= ( ctype_upper($text[$i]) ? strtoupper($key[$index]) : $key[$index] );
         }
     }
+
     return $cipherText;
 }
 

DataStructures/SinglyLinkedList.php

@@ -7,6 +7,7 @@ class SinglyLinkedList
 {
     public ?SinglyLinkedList $next = null;
     public $data;
+
     public function __construct($data)
     {
         $this->data = $data;

Maths/Factorial.php

@@ -12,23 +12,25 @@
  */
 function factorial(int $number)
 {
-    static $cache = [];
-//internal caching memory for speed
+    static $cache = []; //internal caching memory for speed
 
     if ($number < 0) {
         throw new \Exception("Negative numbers are not allowed for calculating Factorial");
     }
+
+    // Factorial of 0 is 1
     if ($number === 0) {
         return 1;
-// Factorial of 0 is 1
     }
 
     if (isset($cache[$number])) {
         return $cache[$number];
     }
 
+    // Recursion since x! = x * (x-1)!
     $fact = ($number * factorial($number - 1));
-// Recursion since x! = x * (x-1)!
+
     $cache[$number] = $fact;
+
     return $fact;
 }

Searches/ExponentialSearch.php

@@ -20,10 +20,12 @@ function binarySearch($arr, $value, $floor, $ceiling)
 {
     // Get $middle index
     $mid = floor(($floor + $ceiling) / 2);
-// Return position if $value is at the $mid position
+
+    // Return position if $value is at the $mid position
     if ($arr[$mid] === $value) {
         return (int) $mid;
     }
+
     //Return -1 is range is wrong
     if ($floor > $ceiling) {
         return -1;
@@ -58,6 +60,7 @@ function exponentialSearch($arr, $value)
     }
     $floor = $i / 2;
     $ceiling = min($i, $length);
-// Call binary search for the range found above
+
+    // Call binary search for the range found above
     return binarySearch($arr, $value, $floor, $ceiling);
 }

Searches/InterpolationSearch.php

@@ -18,36 +18,36 @@
  */
 function interpolationSearch($arr, $key)
 {
-
     $length = count($arr) - 1;
     $low = 0;
     $high = $length;
     $position = -1;
-//loop, between low & high
+    //loop, between low & high
     while ($low <= $high && $key >= $arr[$low] && $key <= $arr[$high]) {
-//GET INDEX
+        //GET INDEX
         $delta = ($key - $arr[$low]) / ($arr[$high] - $arr[$low]);
         $index = $low + floor(($high - $low) * $delta);
-//GET VALUE OF INDEX IN ARRAY...
+
+        //GET VALUE OF INDEX IN ARRAY...
         $indexValue = $arr[$index];
+
         if ($indexValue === $key) {
-        //index value equals key
-                //FOUND TARGET
-                //return index value
-                $position = $index;
+            //index value equals key
+            //FOUND TARGET
+            //return index value
+            $position = $index;
             return (int) $position;
-        }
-        if ($indexValue < $key) {
-  //index value lower than key
-          //increase low index
+        } elseif ($indexValue < $key) {
+            //index value lower than key
+            //increase low index
             $low = $index + 1;
-        }
-        if ($indexValue > $key) {
-  //index value higher than key
-          //decrease high index
+        } elseif ($indexValue > $key) {
+            //index value higher than key
+            //decrease high index
             $high = $index - 1;
         }
     }
-  //when key not found in array or array not sorted
+
+    //when key not found in array or array not sorted
     return null;
 }

Searches/JumpSearch.php

@@ -14,7 +14,8 @@ function jumpSearch($list, $key)
 {
     /*number of elements in the sorted array*/
     $num = count($list);
-/*block size to be jumped*/
+
+    /*block size to be jumped*/
     $step = (int)sqrt($num);
     $prev = 0;
 

Searches/TernarySearch.php

@@ -10,75 +10,72 @@
  */
 function ternarySearchByRecursion($arr, $key, $low, $high)
 {
-
-    //Return -1 if high lesser than low, we can't find item in the whole array
+    // Return null if high is less than low (base case: key not found).
     if ($high < $low) {
         return null;
     }
 
-    //get $mid1 and $mid2
+    // Calculate the indices of the first and second midpoints.
     $mid1 = floor($low + ($high - $low) / 3);
     $mid2 = floor($high - ($high - $low) / 3);
-// check if $key is found at any $mid
+
+    // Check if key is located at either midpoint.
     if ($arr[$mid1] === $key) {
-// return index of $key if found
         return $mid1;
     }
+
     if ($arr[$mid2] === $key) {
-// return index of $key if found
         return $mid2;
     }
 
-    // since the $key is not found at $mid,
-    // check in which region it is present
-    // and repeat the Search operation
-    // in that region
+    // Determine which section to continue searching in.
     if ($key < $arr[$mid1]) {
-// the $key lies in between $low and $mid1
+        // Key is in the left section, between $low and $mid1.
         return ternarySearchByRecursion($arr, $key, $low, $mid1 - 1);
     } elseif ($key > $arr[$mid2]) {
-    // the $key lies in between $mid2 and $high
+        // Key is in the right section, between $mid2 and $high.
         return ternarySearchByRecursion($arr, $key, $mid2 + 1, $high);
     } else {
-    // the $key lies in between $mid1 and $mid2
+        // Key is in the middle section, between $mid1 and $mid2.
         return ternarySearchByRecursion($arr, $key, $mid1 + 1, $mid2 - 1);
     }
 }
 
 function ternarySearchIterative($arr, $key)
 {
+    // Initialize low and high pointers.
     $low = 0;
     $high = count($arr) - 1;
+
+    // Continue searching while the high pointer is greater than or equal to the low pointer.
     while ($high >= $low) {
-    // find the $mid1 and $mid2
+        // Calculate the first and second midpoints.
         $mid1 = floor($low + ($high - $low) / 3);
         $mid2 = floor($high - ($high - $low) / 3);
-    // check if $key is found at any $mid
+
+        // Check if the key is found at either midpoint.
         if ($arr[$mid1] === $key) {
-// return index of $key if found
             return $mid1;
         }
+
         if ($arr[$mid2] === $key) {
-    // return index of $key if found
             return $mid2;
         }
 
-      // since the $key is not found at $mid,
-      // check in which region it is present
-      // and repeat the Search operation
-      // in that region
+        // Determine the section to continue the search in.
         if ($key < $arr[$mid1]) {
-    // the $key lies in between $low and $mid1
+            // Key is in the left section, update the high pointer.
             $high = $mid1 - 1;
         } elseif ($key > $arr[$mid2]) {
-        // the $key lies in between $mid2 and $high
+            // Key is in the right section, update the low pointer.
             $low = $mid2 + 1;
         } else {
-        // the $key lies in between $mid1 and $mid2
+            // Key is in the middle section, update both pointers.
             $low = $mid1 + 1;
             $high = $mid2 - 1;
         }
     }
-  // the $key was not found
+
+    // Key was not found.
     return null;
 }

Sorting/HeapSort.php

@@ -13,24 +13,29 @@
  */
 function heapSort(array $arr): array
 {
+    // Get the number of elements in the array.
     $n = count($arr);
+
+    // Throw an exception if the array has no elements.
     if ($n <= 0) {
         throw new \UnexpectedValueException('Input array must have at least one element.');
     }
 
-    // Build heap
-    for ($i = $n / 2 - 1; $i >= 0; $i--) {
+    // Build a max heap from the array.
+    for ($i = floor($n / 2) - 1; $i >= 0; $i--) {
         heapify($arr, $n, $i);
     }
 
-    // Extract elements from heap one by one
+    // Extract elements from the max heap and build the sorted array.
     for ($i = $n - 1; $i >= 0; $i--) {
-// Swap
+        // Swap the root(maximum value) of the heap with the last element of the heap.
         [$arr[0], $arr[$i]] = [$arr[$i], $arr[0]];
-// Heapify the reduced heap
+
+        // Heapify the reduced heap.
         heapify($arr, $i, 0);
     }
 
+    // Return the sorted array.
     return $arr;
 }
 

Strings/CountVowels.php

@@ -9,26 +9,31 @@
  * @return int   $numberOfVowels
  * @throws \Exception
  */
-function countVowelsSimple(string $string)
+function countVowelsSimple(string $string): int
 {
+    // Check for an empty string and throw an exception if so.
     if (empty($string)) {
-        throw new \Exception('Please pass a non-empty string value');
+        throw new \Exception('Please pass a non-empty string value.');
     }
 
+    // Initialize variables.
     $numberOfVowels = 0;
-    $vowels     = ['a', 'e', 'i', 'o', 'u'];
-// Vowels Set
-    $string     = strtolower($string);
-// For case-insensitive checking
+    $vowels = ['a', 'e', 'i', 'o', 'u']; // Set of vowels for comparison.
+
+    // Convert the string to lowercase for case-insensitive comparison.
+    $string = strtolower($string);
+
+    // Split the string into an array of characters.
     $characters = str_split($string);
-// Splitting the string to a Character Array.
 
+    // Loop through each character to count the vowels.
     foreach ($characters as $character) {
         if (in_array($character, $vowels)) {
             $numberOfVowels++;
         }
     }
 
+    // Return the total number of vowels found.
     return $numberOfVowels;
 }
 
@@ -45,8 +50,8 @@ function countVowelsRegex(string $string)
     if (empty($string)) {
         throw new \Exception('Please pass a non-empty string value');
     }
-    $string = strtolower($string);
-// For case-insensitive checking
+
+    $string = strtolower($string); // For case-insensitive checking
 
     return preg_match_all('/[a,e,i,o,u]/', $string);
 }

Strings/MaxCharacter.php

@@ -8,28 +8,34 @@
  * @return string
  * @throws \Exception
  */
-function maxCharacter(string $string)
+function maxCharacter(string $string): string
 {
+    // Throw an exception if the string is empty.
     if (empty($string)) {
-        throw new \Exception('Please pass a non-empty string value');
+        throw new \Exception('Please pass a non-empty string value.');
     }
 
+    // Initialize an associative array to hold character counts.
     $characterCountTable = [];
-// A variable to maintain the character counts
-    $string              = strtolower($string);
-// For case-insensitive checking
-    $characters          = str_split($string);
-// Splitting the string to a Character Array.
 
+    // Convert the string to lowercase for case-insensitive analysis.
+    $string = strtolower($string);
+
+    // Convert the string into an array of characters.
+    $characters = str_split($string);
+
+    // Loop through the characters to populate the count table.
     foreach ($characters as $character) {
-        $currentCharacterCount = 1;
-        if (isset($characterCountTable[$character])) {
-            $currentCharacterCount = $characterCountTable[$character] + 1;
-        }
+        // Initialize or update the count of the current character.
+        $currentCharacterCount = isset($characterCountTable[$character]) ? $characterCountTable[$character] + 1 : 1;
 
+        // Update the count in the table.
         $characterCountTable[$character] = $currentCharacterCount;
     }
 
+    // Sort the count table in descending order.
     arsort($characterCountTable);
+
+    // Return the character that appears most frequently.
     return array_keys($characterCountTable)[0];
 }