From d6ce08473f59d13b0a3086c9267377efe851b25d Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Mon, 11 Aug 2025 20:20:46 +0000
Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`fea?=
 =?UTF-8?q?ture/scout-trashed`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @GautierDele.

* https://github.com/Lomkit/laravel-rest-api/pull/186#issuecomment-3176728203

The following files were modified:

* `src/Query/ScoutBuilder.php`
* `src/Rules/Search/SearchText.php`
---
 src/Query/ScoutBuilder.php      | 16 ++++++++++++++--
 src/Rules/Search/SearchText.php | 13 +++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/Query/ScoutBuilder.php b/src/Query/ScoutBuilder.php
index 0621a3f..d264e79 100644
--- a/src/Query/ScoutBuilder.php
+++ b/src/Query/ScoutBuilder.php
@@ -118,9 +118,12 @@ public function sort($field, $direction = 'asc')
     }
 
     /**
-     * Apply multiple sorts to the query builder.
+     * Apply multiple sort directives to the underlying query builder.
      *
-     * @param array $sorts An array of sorts to apply.
+     * Each element must be an array with a 'field' key and an optional 'direction' key
+     * (defaults to 'asc'); each directive is forwarded to sort().
+     *
+     * @param array $sorts Array of sort directives.
      */
     public function applySorts($sorts)
     {
@@ -129,6 +132,15 @@ public function applySorts($sorts)
         }
     }
 
+    /**
+     * Apply soft-delete visibility to the underlying Scout query builder.
+     *
+     * Sets the query to include only soft-deleted records when `$trashed` is `"only"`,
+     * or to include both deleted and non-deleted records when `$trashed` is `"with"`.
+     * Any other value is ignored (no change).
+     *
+     * @param string $trashed One of: "only" (only trashed), "with" (include trashed), or other (no-op).
+     */
     public function applyTrashed(string $trashed): void
     {
         if ($trashed === 'only') {
diff --git a/src/Rules/Search/SearchText.php b/src/Rules/Search/SearchText.php
index f913a41..b386e5d 100644
--- a/src/Rules/Search/SearchText.php
+++ b/src/Rules/Search/SearchText.php
@@ -7,6 +7,19 @@
 
 class SearchText extends RestRule
 {
+    /**
+     * Build Laravel validation rules for a search input attribute.
+     *
+     * Returns rules that either prohibit the attribute when the resource is not model-searchable,
+     * or validate a nested search payload structure when searchable:
+     * - `<attribute>`: optionally present and must be an array.
+     * - `<attribute>.value`: nullable string (the search text).
+     * - `<attribute>.trashed`: must be one of `'with'` or `'only'`.
+     *
+     * @param string $attribute The root attribute name to validate (e.g. "search").
+     * @param mixed $value Unused by this rule builder; present to match the rule interface.
+     * @return array<string, array<int, mixed>> Laravel validation rules keyed by attribute path.
+     */
     public function buildValidationRules(string $attribute, mixed $value): array
     {
         if (!$this->resource->isModelSearchable()) {

From d9240cd974876e0a5003a5d4b2ef36177e2e44c1 Mon Sep 17 00:00:00 2001
From: StyleCI Bot <bot@styleci.io>
Date: Mon, 11 Aug 2025 20:20:54 +0000
Subject: [PATCH 2/2] Apply fixes from StyleCI

---
 src/Rules/Search/SearchText.php | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Rules/Search/SearchText.php b/src/Rules/Search/SearchText.php
index b386e5d..765ee60 100644
--- a/src/Rules/Search/SearchText.php
+++ b/src/Rules/Search/SearchText.php
@@ -17,7 +17,8 @@ class SearchText extends RestRule
      * - `<attribute>.trashed`: must be one of `'with'` or `'only'`.
      *
      * @param string $attribute The root attribute name to validate (e.g. "search").
-     * @param mixed $value Unused by this rule builder; present to match the rule interface.
+     * @param mixed  $value     Unused by this rule builder; present to match the rule interface.
+     *
      * @return array<string, array<int, mixed>> Laravel validation rules keyed by attribute path.
      */
     public function buildValidationRules(string $attribute, mixed $value): array