Add comments and update readme

Author: mrtolouei

README.md

@@ -7,6 +7,8 @@ Built for developers who care about observability and application resilience.
 [![Tests](https://github.com/mrtolouei/laravel-health-monitor/actions/workflows/tests.yml/badge.svg)](https://github.com/mrtolouei/laravel-health-monitor/actions/workflows/tests.yml)
 [![Latest Stable Version](https://poser.pugx.org/mrtolouei/laravel-health-monitor/v/stable)](https://packagist.org/packages/mrtolouei/laravel-health-monitor)
 
+![Screen shot](screenshot.png)
+
 ## Installation
 Install the package via Composer:
 ```

config/health-monitor.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Health Monitor Configuration File
+ *
+ * This file contains all the configuration options for monitoring various
+ * services in your Laravel application including internal services and
+ * third-party APIs.
+ *
+ * Each monitor has an 'enabled' flag to toggle monitoring and an 'inspector'
+ * class that implements the actual health check logic.
+ */
 
 return [
     'app-services' => [

routes/web.php

@@ -3,6 +3,14 @@
 use HealthMonitor\Http\Controllers\HealthMonitorController;
 use Illuminate\Support\Facades\Route;
 
+/**
+ * Health Monitor Routes
+ *
+ * Defines all web routes for the health monitoring package.
+ * All routes are protected by the 'viewHealthMonitor' gate/policy
+ * to ensure only authorized users can access them.
+ */
+
 Route::middleware(['can:viewHealthMonitor'])->group(function () {
     Route::get('/api-service-health', [HealthMonitorController::class, 'status']);
     Route::get('/service-health', function () {

screenshot.png

@@ -4,9 +4,22 @@
 
 use HealthMonitor\Dto\HealthResult;
 
+/**
+ * Interface for health check monitoring implementations
+ */
 interface HealthCheckerInterface
 {
+    /**
+     * Execute the health check monitoring
+     *
+     * @return HealthResult The health check result
+     */
     public function monitor(): HealthResult;
 
+    /**
+     * Get the connection driver name for the monitored service
+     *
+     * @return string|null The driver name or null if not applicable
+     */
     public function getConnectionDriver(): string|null;
 }

src/Contracts/HealthCheckerInterface.php

@@ -2,8 +2,21 @@
 
 namespace HealthMonitor\Dto;
 
+/**
+ * Data Transfer Object for health check execution results
+ *
+ * Contains all metrics and status information from a health check execution
+ */
 class ExecutorResult
 {
+    /**
+     * @param string $name The name/identifier of the monitored service
+     * @param string $category The category of the service
+     * @param bool $status The health status (true = healthy, false = unhealthy)
+     * @param float $responseTime The response time in seconds
+     * @param string $driver The underlying driver/connection type
+     * @param string|null $exception Exception message if check failed, null otherwise
+     */
     public function __construct(
         public string      $name,
         public string      $category,
@@ -16,6 +29,11 @@ public function __construct(
         //
     }
 
+    /**
+     * Convert the result to an array representation
+     *
+     * @return array The result data as associative array
+     */
     public function toArray(): array
     {
         return [
@@ -28,31 +46,55 @@ public function toArray(): array
         ];
     }
 
+    /**
+     * Get the service name
+     * @return string
+     */
     public function getName(): string
     {
         return $this->name;
     }
 
+    /**
+     * Get the service category
+     * @return string
+     */
     public function getCategory(): string
     {
         return $this->category;
     }
 
+    /**
+     * Get the health status
+     * @return bool
+     */
     public function getStatus(): bool
     {
         return $this->status;
     }
 
+    /**
+     * Get the rounded response time
+     * @return float
+     */
     public function getResponseTime(): float
     {
         return round($this->responseTime, 2);
     }
 
+    /**
+     * Get the connection driver
+     * @return string
+     */
     public function getDriver(): string
     {
         return $this->driver;
     }
 
+    /**
+     * Get the exception message if available
+     * @return string|null
+     */
     public function getException(): ?string
     {
         return $this->exception;

src/Dto/ExecutorResult.php

@@ -2,8 +2,18 @@
 
 namespace HealthMonitor\Dto;
 
+/**
+ * Represents the result of a health check operation
+ * Contains the health status and related information for a monitored service
+ */
 class HealthResult
 {
+    /**
+     * @param string $name The name/identifier of the monitored service
+     * @param string $category The category/type of the service being checked
+     * @param bool $isHealthy Whether the service is healthy (true) or not (false)
+     * @param string|null $exception The exception message if health check failed
+     */
     public function __construct(
         protected string  $name,
         protected string  $category,
@@ -14,31 +24,56 @@ public function __construct(
         //
     }
 
+    /**
+     * Gets the name of the monitored service
+     * @return string The service name
+     */
     public function getName(): string
     {
         return $this->name;
     }
 
+    /**
+     * Gets the category of the monitored service
+     * @return string The service category
+     */
     public function getCategory(): string
     {
         return $this->category;
     }
 
+    /**
+     * Checks if the service is healthy
+     * @return bool True if healthy, false otherwise
+     */
     public function isHealthy(): bool
     {
         return $this->isHealthy;
     }
 
+    /**
+     * Gets the cleaned exception message (if any)
+     * @return string|null The sanitized exception message or null if no exception
+     */
     public function getException(): string|null
     {
         return $this->clean($this->exception);
     }
 
+    /**
+     * Sanitizes exception messages by:
+     * - Removing newlines and tabs
+     * - Collapsing multiple spaces
+     * - Trimming quotes and whitespace
+     * - Removing slashes
+     * @param string|null $message The raw exception message
+     * @return string|null The cleaned message
+     */
     private function clean(string|null $message): string|null
     {
         $message = str_replace(["\n", "\r", "\t"], ' ', $message);
         $message = preg_replace('/\s+/', ' ', $message);
         $message = trim($message, "\"' ");
         return stripslashes($message);
     }
-}
+}

src/Dto/HealthResult.php

@@ -6,12 +6,17 @@
 use Illuminate\Support\Facades\Facade;
 
 /**
+ * Health Monitor Facade
+ *
+ * Provides static access to the HealthMonitorManager service
  * @method static string runCheckers()
  */
 class HealthMonitor extends Facade
 {
     /**
-     * @return string
+     * Get the registered name of the component
+     *
+     * @return string The service container binding key
      */
     protected static function getFacadeAccessor(): string
     {

src/Facades/HealthMonitor.php

@@ -6,10 +6,19 @@
 use HealthMonitor\Monitors\ThirdPartyHealthChecker;
 use InvalidArgumentException;
 
+/**
+ * Factory class for creating health checker instances
+ *
+ * Responsible for instantiating all configured health checkers
+ * based on the package configuration
+ */
 class HealthCheckerFactory
 {
     /**
-     * @return HealthCheckerInterface[]
+     * Creates all enabled health checker instances
+     *
+     * @return HealthCheckerInterface[] Array of instantiated health checkers
+     * @throws InvalidArgumentException If a checker class doesn't exist
      */
     public static function create(): array
     {

src/Factories/HealthCheckerFactory.php

@@ -5,18 +5,28 @@
 use HealthMonitor\Contracts\HealthCheckerInterface;
 use HealthMonitor\Dto\ExecutorResult;
 
+/**
+ * Health Monitor Executor
+ *
+ * Coordinates the execution of multiple health checkers
+ * and measures their performance metrics
+ */
 class HealthMonitorExecutor
 {
     /**
-     * @param HealthCheckerInterface[] $checkers
+     * @param HealthCheckerInterface[] $checkers Array of health checkers to execute
      */
     public function __construct(protected array $checkers)
     {
         //
     }
 
     /**
-     * @return ExecutorResult[]
+     * Execute all registered health checkers
+     *
+     * Runs each checker while measuring execution time and collecting results
+     *
+     * @return ExecutorResult[] Array of health check results with performance metrics
      */
     public function run(): array
     {