📝 Add docstrings to feature/scout-queries

src/AccessServiceProvider.php

@@ -34,8 +34,6 @@ public function register()
 
     /**
      * Bootstrap any package services.
-     *
-     * @return void
      */
     public function boot()
     {
@@ -46,6 +44,9 @@ public function boot()
         $this->bootScoutBuilder();
     }
 
+    /**
+     * Registers a macro on Laravel Scout's Builder.
+     */
     protected function bootScoutBuilder(): void
     {
         if (class_exists(Builder::class)) {

src/Controls/Control.php

@@ -68,12 +68,12 @@ public function applies(Model $user, string $method, Model $model): bool
     }
 
     /**
-     * Modifies the query builder to enforce access control restrictions for a given user.
+     * Applies access control restrictions to an Eloquent query builder for the specified user.
      *
-     * @param Builder $query The query builder instance to modify.
-     * @param Model   $user  The user model used to determine applicable query control restrictions.
+     * @param Builder $query The Eloquent query builder to modify.
+     * @param Model   $user  The user for whom access control is enforced.
      *
-     * @return Builder The modified query builder with access controls applied.
+     * @return Builder The query builder with access control restrictions applied.
      */
     public function queried(Builder $query, Model $user): Builder
     {
@@ -91,25 +91,25 @@ public function queried(Builder $query, Model $user): Builder
     }
 
     /**
-     * Modifies the scout query builder to enforce access control restrictions for a given user.
+     * Applies access control restrictions to a Laravel Scout query builder for the specified user.
      *
-     * @param \Laravel\Scout\Builder $query The scout query builder instance to modify.
-     * @param Model                  $user  The user model used to determine applicable query control restrictions.
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @param Model                  $user  The user for whom access control is enforced.
      *
-     * @return Builder The modified query builder with access controls applied.
+     * @return \Laravel\Scout\Builder The query builder with access controls applied.
      */
     public function scoutQueried(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
     {
         return $this->applyScoutQueryControl($query, $user);
     }
 
     /**
-     * Applies query modifications based on access control perimeters for the given user.
+     * Modifies an Eloquent query builder to enforce access control rules for the specified user.
      *
-     * @param Builder $query The query builder instance to be modified.
-     * @param Model   $user  The user model used to evaluate access control conditions.
+     * @param Builder $query The Eloquent query builder to modify.
+     * @param Model   $user  The user for whom access control is evaluated.
      *
-     * @return Builder The query builder after applying access control modifications.
+     * @return Builder The modified query builder reflecting access control restrictions.
      */
     protected function applyQueryControl(Builder $query, Model $user): Builder
     {
@@ -132,6 +132,14 @@ protected function applyQueryControl(Builder $query, Model $user): Builder
         return $noResultCallback($query);
     }
 
+    /**
+     * Applies access control modifications to a Laravel Scout query builder based on defined perimeters.
+     *
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @param Model                  $user  The user for whom access control is being enforced.
+     *
+     * @return \Laravel\Scout\Builder The modified Scout query builder reflecting access control restrictions.
+     */
     protected function applyScoutQueryControl(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
     {
         $noResultCallback = function (\Laravel\Scout\Builder $query) {
@@ -154,17 +162,24 @@ protected function applyScoutQueryControl(\Laravel\Scout\Builder $query, Model $
     }
 
     /**
-     * Modifies the query builder to return no results.
+     * Alters the Eloquent query builder to ensure no records are returned.
      *
-     * @param Builder $query The query builder instance to modify.
+     * @param Builder $query The Eloquent query builder to modify.
      *
-     * @return Builder The modified query builder that yields an empty result set.
+     * @return Builder The query builder configured to yield no results.
      */
     protected function noResultQuery(Builder $query): Builder
     {
         return $query->whereRaw('0=1');
     }
 
+    /**
+     * Modifies the Scout query builder to ensure no records are returned.
+     *
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     *
+     * @return \Laravel\Scout\Builder The modified query builder that yields no results.
+     */
     protected function noResultScoutQuery(\Laravel\Scout\Builder $query): \Laravel\Scout\Builder
     {
         return $query->where('__NOT_A_VALID_FIELD__', 0);

src/Perimeters/Perimeter.php

@@ -14,6 +14,9 @@ class Perimeter
     protected Closure $shouldCallback;
     protected Closure $allowedCallback;
 
+    /**
+     * Initializes the Perimeter with default callbacks for access control and query customization.
+     */
     public function __construct()
     {
         // Default implementations that can be overridden
@@ -24,19 +27,27 @@ public function __construct()
     }
 
     /**
-     * Executes the should callback to determine if the access control condition is met.
+     * Determines if the access control condition should be applied for the given user, method, and model.
      *
-     * @param Model  $user   The user instance for which the check is performed.
-     * @param string $method The access control method or action being evaluated.
-     * @param Model  $model  The model instance related to the access check.
+     * @param Model  $user   The user being evaluated.
+     * @param string $method The access control action or method.
+     * @param Model  $model  The related model instance.
      *
-     * @return bool True if the callback validation passes; otherwise, false.
+     * @return bool True if the condition applies; false otherwise.
      */
     public function applyShouldCallback(Model $user, string $method, Model $model): bool
     {
         return ($this->shouldCallback)($user, $method, $model);
     }
 
+    /**
+     * Applies the configured Scout query callback to modify a Laravel Scout search query for a given user.
+     *
+     * @param \Laravel\Scout\Builder $query The Scout query builder to modify.
+     * @param Model                  $user  The user model for whom the query is being modified.
+     *
+     * @return \Laravel\Scout\Builder The modified Scout query builder.
+     */
     public function applyScoutQueryCallback(\Laravel\Scout\Builder $query, Model $user): \Laravel\Scout\Builder
     {
         return ($this->scoutQueryCallback)($query, $user);
@@ -96,11 +107,11 @@ public function should(Closure $shouldCallback): self
     }
 
     /**
-     * Sets the query modification callback.
+     * Sets a custom callback to modify Eloquent query builders for access control.
      *
-     * @param Closure $queryCallback A callback that customizes the query logic.
+     * @param Closure $queryCallback Callback that receives and returns a query builder.
      *
-     * @return self Returns the current instance for method chaining.
+     * @return self The current Perimeter instance.
      */
     public function query(Closure $queryCallback): self
     {
@@ -109,6 +120,13 @@ public function query(Closure $queryCallback): self
         return $this;
     }
 
+    /**
+     * Sets the callback used to modify Laravel Scout search queries for this perimeter.
+     *
+     * @param Closure $scoutQueryCallback Callback that receives a Scout query builder and user model, and returns a modified query builder.
+     *
+     * @return self
+     */
     public function scoutQuery(Closure $scoutQueryCallback): self
     {
         $this->scoutQueryCallback = $scoutQueryCallback;