Merge pull request #153 from Lomkit/coderabbitai/docstrings/3541bef

📝 Add docstrings to `feature/laravel-12`

Author: GautierDele

src/Actions/DispatchAction.php

@@ -109,11 +109,16 @@ public function dispatch($chunkCount)
     }
 
     /**
-     * Dispatch the given action.
+     * Processes models in chunks using classic mode and dispatches an action for each set.
      *
-     * @param int $chunkCount
+     * The method builds a search query for the resource associated with the current request, applying
+     * search criteria from the request input and removing any default result limits. It then processes
+     * the query results in chunks (of size $chunkCount) by invoking the forModels method on each chunk.
+     * Finally, it returns the query limit if one is set; otherwise, it returns the total count of models.
      *
-     * @return int
+     * @param int $chunkCount The number of models to process per chunk.
+     *
+     * @return int The effective result limit if set, or the total count of models.
      */
     public function handleClassic(int $chunkCount)
     {

src/Http/Response.php

@@ -41,6 +41,18 @@ protected function buildGatesForModel(Model $model, Resource $resource, array $g
         );
     }
 
+    /**
+     * Convert an Eloquent model into an array representation for the HTTP response.
+     *
+     * This method transforms the given model by selecting only the specified attributes and aggregates as defined in the request parameters or resource. If authorization gating is enabled and gate parameters are provided, it appends the corresponding authorization data. Additionally, it recursively processes any loaded relations—returning pivot data when applicable and mapping related models (or collections of models) using the resource’s configuration.
+     *
+     * @param Model         $model        The Eloquent model instance to be converted.
+     * @param resource      $resource     The resource defining the fields and structure of the response.
+     * @param array         $requestArray Request parameters that control field selection, aggregates, and authorization gates.
+     * @param Relation|null $relation     Optional relation context for processing nested relationships.
+     *
+     * @return array The structured array representation of the model, including attributes and recursively processed relations.
+     */
     public function modelToResponse(Model $model, Resource $resource, array $requestArray, Relation $relation = null)
     {
         $currentRequestArray = $relation === null ? $requestArray : collect($requestArray['includes'] ?? [])

src/Query/Builder.php

@@ -63,13 +63,32 @@ public function newQueryBuilder($parameters)
         return app()->make(QueryBuilder::class, $parameters);
     }
 
+    /**
+     * Sets the security flag for the query builder.
+     *
+     * Toggling this flag disables or enables security checks during query building.
+     *
+     * @param bool $disable Set to true to disable security checks (default), or false to enable them.
+     *
+     * @return $this The current instance for method chaining.
+     */
     public function disableSecurity($disable = true)
     {
         $this->disableSecurity = $disable;
 
         return $this;
     }
 
+    /**
+     * Set whether to disable applying the default query limit.
+     *
+     * When disabled, the query will not enforce any default limit on the number of results,
+     * allowing retrieval of all matching records unless a custom limit is specified.
+     *
+     * @param bool $disable True to disable the default limit, false to enable it.
+     *
+     * @return self Returns the current instance for chaining.
+     */
     public function disableDefaultLimit($disable = true)
     {
         $this->disableDefaultLimit = $disable;

src/Query/ScoutBuilder.php

@@ -13,11 +13,23 @@ class ScoutBuilder implements QueryBuilder
     use Conditionable;
 
     /**
-     * Perform a search operation on the query builder.
+     * Executes a search query using Laravel Scout with customizable criteria.
      *
-     * @param array $parameters An array of search parameters.
+     * This method configures the underlying search builder by setting the query text,
+     * and conditionally applying filters, sort orders, and additional instructions based
+     * on the provided parameters. It also enforces a limit on the number of results,
+     * defaulting to 50 if no limit is specified. Any extra parameters, after excluding
+     * reserved keys (filters, instructions, sorts, text, and limit), are forwarded to the
+     * underlying search operation.
      *
-     * @return \Laravel\Scout\Builder The modified query builder.
+     * @param array $parameters An associative array of search criteria, which may include:
+     *                          - 'text': The search query string.
+     *                          - 'filters': An array of filter conditions.
+     *                          - 'sorts': An array of sorting directives.
+     *                          - 'instructions': Additional query instructions.
+     *                          - 'limit': Maximum number of results to return (defaults to 50 if not provided).
+     *
+     * @return \Laravel\Scout\Builder The configured Scout query builder.
      */
     public function search(array $parameters = [])
     {

src/Query/Traits/PerformSearch.php

@@ -10,11 +10,25 @@
 trait PerformSearch
 {
     /**
-     * Perform a search operation on the query builder.
+     * Executes a modular search on the query builder based on provided parameters.
      *
-     * @param array $parameters An array of search parameters.
+     * This method first authorizes the view operation on the model and then, unless security is disabled,
+     * applies a security-aware search query. It conditionally processes various search parameters to:
+     * - Filter results via a nested subquery to prevent conflicts.
+     * - Sort results using custom definitions if provided, or default ordering from the resource.
+     * - Apply named scopes, instructions, includes, and aggregate functions.
+     * - Limit the result set according to a specified limit or a default value of 50.
      *
-     * @return Builder The modified query builder.
+     * @param array $parameters An associative array of search parameters that may include:
+     *                          - 'filters': Criteria for filtering the results.
+     *                          - 'sorts': Definitions for ordering the results.
+     *                          - 'scopes': Named scopes to refine the query.
+     *                          - 'instructions': Additional instructions for query customization.
+     *                          - 'includes': Related resources to include in the query.
+     *                          - 'aggregates': Aggregate functions to apply on related data.
+     *                          - 'limit': Maximum number of records to return.
+     *
+     * @return Builder The modified query builder with the applied search parameters.
      */
     public function search(array $parameters = [])
     {

tests/Support/Rest/Resources/BelongsToManyResource.php

@@ -23,6 +23,13 @@ public function relations(RestRequest $request): array
         ];
     }
 
+    /**
+     * Returns the list of field names for the resource.
+     *
+     * This method defines the fields that are part of the resource representation.
+     *
+     * @return array Array of field names.
+     */
     public function fields(RestRequest $request): array
     {
         return [
@@ -32,6 +39,14 @@ public function fields(RestRequest $request): array
         ];
     }
 
+    /**
+     * Returns an array of predefined pagination limit values.
+     *
+     * This method provides a fixed set of integer values that can be used to control the number
+     * of items returned in paginated responses.
+     *
+     * @return int[] Array of allowed limit values.
+     */
     public function limits(RestRequest $request): array
     {
         return [