Merge pull request #102

Added doc-blocks

Author: andrey-helldar

src/Benchmark.php

@@ -36,13 +36,22 @@ public function __construct(
         protected DeviationService $deviation = new DeviationService,
     ) {}
 
+    /**
+     * Creates a new benchmark instance.
+     *
+     * @return static
+     */
     public static function make(): static
     {
         return new static;
     }
 
     /**
+     * Sets a callback to be executed before all iterations for each comparison.
+     *
      * @param  Closure(int|string $name): mixed  $callback
+     *
+     * @return $this
      */
     public function before(Closure $callback): static
     {
@@ -52,7 +61,11 @@ public function before(Closure $callback): static
     }
 
     /**
+     * Sets a callback to be executed before each iteration.
+     *
      * @param  Closure(int|string $name, int<1, max> $iteration): mixed  $callback
+     *
+     * @return $this
      */
     public function beforeEach(Closure $callback): static
     {
@@ -62,7 +75,11 @@ public function beforeEach(Closure $callback): static
     }
 
     /**
+     * Sets a callback to be executed after all iterations for each comparison.
+     *
      * @param  Closure(int|string $name): mixed  $callback
+     *
+     * @return $this
      */
     public function after(Closure $callback): static
     {
@@ -72,7 +89,11 @@ public function after(Closure $callback): static
     }
 
     /**
+     * Sets a callback to be executed after each iteration.
+     *
      * @param  Closure(int|string $name, int<1, max> $iteration, float $time, float $memory): mixed  $callback
+     *
+     * @return $this
      */
     public function afterEach(Closure $callback): static
     {
@@ -82,7 +103,11 @@ public function afterEach(Closure $callback): static
     }
 
     /**
+     * Sets the number of iterations for each comparison.
+     *
      * @param  int<1, max>  $count
+     *
+     * @return $this
      */
     public function iterations(int $count): static
     {
@@ -92,7 +117,11 @@ public function iterations(int $count): static
     }
 
     /**
+     * Enables deviation calculation and sets the number of runs.
+     *
      * @param  int<2, max>  $count
+     *
+     * @return $this
      */
     public function deviations(int $count = 2): static
     {
@@ -104,7 +133,11 @@ public function deviations(int $count = 2): static
     }
 
     /**
-     * @param  int<0, max>|null  $precision
+     * Sets the rounding precision for time values.
+     *
+     * @param  int<0, max>|null  $precision  The number of decimal places. Null means no rounding.
+     *
+     * @return $this
      */
     public function round(?int $precision): static
     {
@@ -113,13 +146,25 @@ public function round(?int $precision): static
         return $this;
     }
 
+    /**
+     * Disables the progress bar display.
+     *
+     * @return $this
+     */
     public function disableProgressBar(): static
     {
         $this->view->progressBar()->disable();
 
         return $this;
     }
 
+    /**
+     * Registers callback functions for comparison.
+     *
+     * @param  array|Closure  ...$callbacks  Callback functions or an array of callback functions for comparison.
+     *
+     * @return $this
+     */
     public function compare(array|Closure ...$callbacks): static
     {
         $this->clear();
@@ -130,6 +175,8 @@ public function compare(array|Closure ...$callbacks): static
     }
 
     /**
+     * Returns benchmark results as an array of data.
+     *
      * @return Data\ResultData[]
      */
     public function toData(): array
@@ -141,6 +188,9 @@ public function toData(): array
         return $this->mapResult();
     }
 
+    /**
+     * Outputs benchmark results to the console as a table.
+     */
     public function toConsole(): void
     {
         if (! $data = $this->toData()) {
@@ -154,6 +204,11 @@ public function toConsole(): void
         );
     }
 
+    /**
+     * Returns the assertion service for performing result checks.
+     *
+     * @return AssertService
+     */
     public function toAssert(): AssertService
     {
         if (! $data = $this->toData()) {
@@ -163,20 +218,31 @@ public function toAssert(): AssertService
         return new AssertService($data);
     }
 
+    /**
+     * Performs the benchmark: simple comparison or with deviation calculation.
+     */
     protected function perform(): void
     {
         $this->deviations === 1
             ? $this->performCompare()
             : $this->performDeviation();
     }
 
+    /**
+     * Transforms collected data into an array of results.
+     *
+     * @return array
+     */
     protected function mapResult(): array
     {
         return $this->result->get(
             $this->collector->all()
         );
     }
 
+    /**
+     * Performs a simple comparison of callback functions.
+     */
     protected function performCompare(): void
     {
         $callbacks = $this->callbacks->compare;
@@ -187,6 +253,9 @@ protected function performCompare(): void
         );
     }
 
+    /**
+     * Performs a comparison with deviation calculation through multiple runs.
+     */
     protected function performDeviation(): void
     {
         $results = [];
@@ -210,6 +279,12 @@ protected function performDeviation(): void
         );
     }
 
+    /**
+     * Wraps execution in a progress bar.
+     *
+     * @param  Closure  $callback  The callback function to execute.
+     * @param  int  $total  The total number of progress bar steps.
+     */
     protected function withProgress(Closure $callback, int $total): void
     {
         $this->view->emptyLine();
@@ -222,11 +297,25 @@ protected function withProgress(Closure $callback, int $total): void
         $this->view->emptyLine(2);
     }
 
+    /**
+     * Calculates the total number of steps for the progress bar.
+     *
+     * @param  array  $callbacks  An array of callback functions.
+     * @param  int  $multiplier  The multiplier (number of runs).
+     *
+     * @return int
+     */
     protected function steps(array $callbacks, int $multiplier = 1): int
     {
         return count($callbacks) * $this->iterations * $multiplier;
     }
 
+    /**
+     * Executes all callback functions with before/after hooks.
+     *
+     * @param  array  $callbacks  An array of callback functions.
+     * @param  ProgressBarView  $progressBar  The progress bar.
+     */
     protected function chunks(array $callbacks, ProgressBarView $progressBar): void
     {
         foreach ($callbacks as $name => $callback) {
@@ -238,6 +327,13 @@ protected function chunks(array $callbacks, ProgressBarView $progressBar): void
         }
     }
 
+    /**
+     * Executes all iterations for a single callback function.
+     *
+     * @param  mixed  $name  The callback name.
+     * @param  Closure  $callback  The callback function to execute.
+     * @param  ProgressBarView  $progressBar  The progress bar.
+     */
     protected function run(mixed $name, Closure $callback, ProgressBarView $progressBar): void
     {
         for ($i = 1; $i <= $this->iterations; $i++) {
@@ -253,16 +349,34 @@ protected function run(mixed $name, Closure $callback, ProgressBarView $progress
         }
     }
 
+    /**
+     * Calls a callback function and returns the measurement results.
+     *
+     * @param  Closure  $callback  The callback function to execute.
+     * @param  array  $parameters  Parameters to pass to the callback.
+     *
+     * @return array  An array [time in milliseconds, memory in bytes].
+     */
     protected function call(Closure $callback, array $parameters = []): array
     {
         return $this->runner->call($callback, $parameters);
     }
 
+    /**
+     * Stores measurement results in the collector.
+     *
+     * @param  mixed  $name  The callback name.
+     * @param  float  $time  Execution time is specified in milliseconds.
+     * @param  float  $memory  Memory usage is specified in bytes.
+     */
     protected function push(mixed $name, float $time, float $memory): void
     {
         $this->collector->push($name, [$time, $memory]);
     }
 
+    /**
+     * Clears results and collected data.
+     */
     protected function clear(): void
     {
         $this->result->clear();

src/Data/DeviationData.php

@@ -6,6 +6,11 @@
 
 readonly class DeviationData
 {
+    /**
+     * Creates an object with deviation data.
+     *
+     * @param  MetricData  $percent  Deviation metrics are specified in percentages.
+     */
     public function __construct(
         public MetricData $percent,
     ) {}

src/Data/MetricData.php

@@ -6,6 +6,14 @@
 
 readonly class MetricData
 {
+    /**
+     * Creates an object with time and memory metrics.
+     *
+     * When the metric is used to store deviations, the deviations are specified in percentages.
+     *
+     * @param  float  $time  Time value is specified in milliseconds.
+     * @param  float  $memory  Memory value is specified in bytes.
+     */
     public function __construct(
         public float $time,
         public float $memory,

src/Data/ResultData.php

@@ -6,6 +6,15 @@
 
 readonly class ResultData
 {
+    /**
+     * Creates an object with benchmark results.
+     *
+     * @param  MetricData  $min  Minimum metric values.
+     * @param  MetricData  $max  Maximum metric values.
+     * @param  MetricData  $avg  Average metric values.
+     * @param  MetricData  $total  Total metric values.
+     * @param  DeviationData|null  $deviation  Deviation data.
+     */
     public function __construct(
         public MetricData $min,
         public MetricData $max,

src/Exceptions/DeviationsNotCalculatedException.php

@@ -10,6 +10,11 @@
 
 class DeviationsNotCalculatedException extends ValueError
 {
+    /**
+     * Creates an exception indicating that deviations were not calculated for the specified callback name.
+     *
+     * @param  int|string  $name  The name of the callback for which deviation data is missing.
+     */
     public function __construct(int|string $name)
     {
         parent::__construct(

src/Exceptions/NoComparisonsException.php

@@ -8,6 +8,9 @@
 
 class NoComparisonsException extends RuntimeException
 {
+    /**
+     * Creates an exception indicating that the "compare" method was not called.
+     */
     public function __construct()
     {
         parent::__construct('Method "compare" was not called. No comparisons were made.');

src/Exceptions/ValueIsNotCallableException.php

@@ -10,8 +10,13 @@
 
 class ValueIsNotCallableException extends TypeError
 {
+    /**
+     * Creates an exception indicating that the provided value does not match the Closure type.
+     *
+     * @param  mixed  $value  The value that does not match the Closure type.
+     */
     public function __construct(mixed $value)
     {
-        parent::__construct(sprintf('The property value must be of type Closure, %s given.', gettype($value)), 500);
+        parent::__construct(sprintf('The property value must be of type Closure, %s given.', gettype($value)));
     }
 }