Added docs to Utils classes

Author: ddebowczyk

src-utils/Arrays.php

@@ -4,8 +4,17 @@
 
 use WeakMap;
 
+/**
+ * Utility functions for working with arrays.
+ */
 class Arrays
 {
+    /**
+     * Merges two arrays, handling null values.
+     * @param array|null $array1
+     * @param array|null $array2
+     * @return array|null
+     */
     public static function mergeNull(?array $array1, ?array $array2): ?array {
         return match(true) {
             is_null($array1) && is_null($array2) => null,
@@ -15,6 +24,12 @@ public static function mergeNull(?array $array1, ?array $array2): ?array {
         };
     }
 
+    /**
+     * Merges two arrays, handling null values.
+     * @param array|null $array1
+     * @param array|null $array2
+     * @return array|null
+     */
     public static function unset(array $array, array|string $fields) : array {
         if (!is_array($fields)) {
             $fields = [$fields];
@@ -25,6 +40,11 @@ public static function unset(array $array, array|string $fields) : array {
         return $array;
     }
 
+    /**
+     * Converts a value to an array.
+     * @param mixed $value
+     * @return array
+     */
     public static function asArray(mixed $value): array {
         if (is_array($value)) {
             return $value;
@@ -35,21 +55,45 @@ public static function asArray(mixed $value): array {
         return [$value];
     }
 
+    /**
+     * Checks if an array is a subset of another array.
+     * @param array $decodedKeys
+     * @param array $propertyNames
+     * @return bool
+     */
     static public function isSubset(array $decodedKeys, array $propertyNames) {
         return count(array_diff($decodedKeys, $propertyNames)) === 0;
     }
 
+    /**
+     * Removes the last N elements from an array.
+     * @param array $array
+     * @param int $count
+     * @return array
+     */
     static public function removeTail(array $array, int $count) : array {
         if ($count < 1) {
             return $array;
         }
         return array_slice($array, 0, -$count);
     }
 
+    /**
+     * Flattens an array of arrays into a single string.
+     * @param array $arrays
+     * @param string $separator
+     * @return string
+     */
     static public function flatten(array $arrays, string $separator = ''): string {
         return self::doFlatten($arrays, $separator);
     }
 
+    /**
+     * Maps an array using a callback.
+     * @param array $array
+     * @param callable $callback
+     * @return array
+     */
     static public function map(array $array, callable $callback): array {
         $target = [];
         foreach ($array as $key => $value) {
@@ -58,6 +102,12 @@ static public function map(array $array, callable $callback): array {
         return $target;
     }
 
+    /**
+     * Filters an array using a callback.
+     * @param array $array
+     * @param callable $callback
+     * @return array
+     */
     static public function fromAny(mixed $anyValue): array {
         $visited = new WeakMap();
         $toArray = function($x) use(&$toArray, &$visited) {
@@ -75,6 +125,12 @@ static public function fromAny(mixed $anyValue): array {
         return $toArray($anyValue);
     }
 
+    /**
+     * Filters an array using a callback.
+     * @param array $array
+     * @param callable $callback
+     * @return array
+     */
     static public function removeRecursively(array $array, array $keys): array {
         if (empty($array) || empty($keys)) {
             return $array;
@@ -92,12 +148,24 @@ static public function removeRecursively(array $array, array $keys): array {
         return $remove($array, $keys);
     }
 
+    /**
+     * Filters an array using a callback.
+     * @param array $array
+     * @param callable $callback
+     * @return array
+     */
     static public function toBullets(array $array): string {
         return implode("\n", array_map(fn($c) => " - {$c}\n", $array));
     }
 
     // INTERNAL ///////////////////////////////////////////////////////
 
+    /**
+     * Flattens an array of arrays into a single string.
+     * @param array $arrays
+     * @param string $separator
+     * @return string
+     */
     private static function doFlatten(array $arrays, string $separator): string {
         $flat = '';
         foreach ($arrays as $item) {

src-utils/DataMap.php

@@ -8,6 +8,7 @@
 use JsonSerializable;
 
 /**
+ * DataMap provides a simple way to work with nested data structures.
  * @template TKey of array-key
  * @template TValue
  */

src-utils/Files.php

@@ -9,6 +9,9 @@
 use RecursiveIteratorIterator;
 use RuntimeException;
 
+/**
+ * Utility class for working with files and directories.
+ */
 class Files
 {
     /**

src-utils/RawChain.php

@@ -37,7 +37,6 @@
  *
  * return $chain->process(5);
  */
-
 class RawChain {
     /**
      * @var callable[] The processors that the payload will be passed through.

src-utils/ResultChain.php

@@ -71,20 +71,43 @@ public function __construct(
 
     // CREATION ///////////////////////////////////////////////////////////////////////////////
 
+    /**
+     * Create a new ResultChain instance.
+     *
+     * @return ResultChain
+     */
     static public function make() : static {
         return new ResultChain();
     }
 
+    /**
+     * Create a new ResultChain instance with an initial value.
+     *
+     * @param mixed $value
+     * @return ResultChain
+     */
     static public function for(mixed $value): static {
         return new ResultChain(value: Result::with($value));
     }
 
+    /**
+     * Create a new ResultChain instance with a source of values.
+     *
+     * @param callable $source
+     * @return ResultChain
+     */
     static public function from(callable $source): static {
         return new ResultChain(source: $source);
     }
 
     // DEFINITION /////////////////////////////////////////////////////////////////////////////
 
+    /**
+     * Set the initial value of the chain.
+     *
+     * @param mixed $value
+     * @return ResultChain
+     */
     public function withContext(mixed $context): static {
         $this->context = $context;
         return $this;
@@ -248,6 +271,13 @@ private function getCarry() : mixed {
         };
     }
 
+    /**
+     * Process the value with the processor.
+     *
+     * @param callable $processor
+     * @param mixed $value
+     * @return mixed
+     */
     private function processValue(callable $processor, mixed $value): mixed {
         return match(true) {
             $value instanceof Result => $processor($value->unwrap()),
@@ -256,6 +286,13 @@ private function processValue(callable $processor, mixed $value): mixed {
         };
     }
 
+    /**
+     * Wrap the value into a Result object or unwrap it if it is already a Result.
+     *
+     * @param mixed $value
+     * @param string $onNull
+     * @return Result|null
+     */
     private function asResult(mixed $value, string $onNull = self::FAIL_ON_NULL) : ?Result {
         return match(true) {
             $value instanceof Result => $value,
@@ -268,13 +305,25 @@ private function asResult(mixed $value, string $onNull = self::FAIL_ON_NULL) : ?
         };
     }
 
+    /**
+     * Wrap or unwrap the value based on the flag.
+     * @param mixed $value
+     * @param bool $wrapped
+     * @return mixed
+     */
     private function wrapOrUnwrap(mixed $value, bool $wrapped = true): mixed {
         return match(true) {
             $wrapped => $this->asResult($value, self::CONTINUE_ON_NULL),
             default => $this->unwrapIfResult($value),
         };
     }
 
+    /**
+     * Unwrap the value if it is a Result object.
+     *
+     * @param mixed $value
+     * @return mixed
+     */
     private function unwrapIfResult(mixed $value): mixed {
         return match(true) {
             $value instanceof Success => $value->unwrap(),

src-utils/Settings.php

@@ -105,6 +105,11 @@ public static function set(string $group, string $key, mixed $value) : void {
         self::$settings[$group] = self::$settings[$group]->set($key, $value);
     }
 
+    /**
+     * Unsets a settings group.
+     *
+     * @param string $group The settings group.
+     */
     public static function unset(string $group) : void {
         if (self::isGroupLoaded($group)) {
             self::$settings[$group] = [];