doc blocks for resources

src/Contracts/Resources/ResourceContract.php

@@ -4,36 +4,107 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Collection;
+use Leeto\MoonShine\Actions\Action;
 use Leeto\MoonShine\Contracts\RenderableContract;
+use Leeto\MoonShine\Decorations\Tab;
+use Leeto\MoonShine\Fields\Field;
 
 interface ResourceContract
 {
+    /**
+     * Get a resource title, will be displayed in admin panel menu
+     *
+     * @return string
+     */
     public function title(): string;
 
+    /**
+     * Define a field name, which will be used to display value in relation
+     *
+     * @return string
+     */
     public function titleField(): string;
 
+    /**
+     * Get a model class, related to resource
+     *
+     * @return Model
+     */
     public function getModel(): Model;
 
+    /**
+     * Get current eloquent instance
+     *
+     * @return Model
+     */
     public function getItem(): Model;
 
+    /**
+     * Get a collection of additional actions performed on resource page
+     *
+     * @return Action[]
+     */
     public function getActions(): Collection;
 
+    /**
+     * Define if the resources protected by authentication
+     *
+     * @return bool
+     */
     public function isWithPolicy(): bool;
 
+    /**
+     * Get a collection of fields of related model
+     *
+     * @return Field[]
+     */
     public function getFields(): Collection;
 
+    /**
+     * Get a collection of tabs, which will be displayed on create/update resource form
+     *
+     * @return Tab[]
+     */
     public function tabs(): Collection;
 
+    /**
+     * Get a collection of fields of related model, which will be displayed on resource index page
+     *
+     * @return Field[]
+     */
     public function indexFields(): Collection;
 
+    /**
+     * Get a collection of fields of related model, which will be exported
+     *
+     * @return Field[]
+     */
     public function exportFields(): Collection;
 
+    /**
+     * Get an array of fields, which will be displayed on create/edit resource page
+     *
+     * @return Field[]
+     */
     public function formFields(): Collection;
 
+    /**
+     * Get additional assets, which will be loaded on resource page
+     *
+     * @param string $type CSS or JS type
+     * @return array
+     */
     public function getAssets(string $type): array;
 
     public function extensions($name, Model $item): string;
 
+    /**
+     * Check whether user can perform action on model
+     *
+     * @param string $ability view, viewAny, restore, forceDelete
+     * @param Model|null $item Model on which the action is performed
+     * @return bool
+     */
     public function can(string $ability, Model $item = null): bool;
 
     public function renderDecoration(RenderableContract $decoration, Model $item);
@@ -42,5 +113,5 @@ public function renderField(RenderableContract $field, Model $item);
 
     public function renderFilter(RenderableContract $field, Model $item);
 
-    public function renderMetric(RenderableContract $field);
+    public function renderMetric(RenderableContract $metric);
 }

src/MoonShine.php

@@ -33,6 +33,12 @@ public static function namespace(string $path = ''): string
         return static::NAMESPACE . $path;
     }
 
+    /**
+     * Register resource classes in the system
+     *
+     * @param array $data Array of resource classes that is registering
+     * @return void
+     */
     public function registerResources(array $data): void
     {
         $this->resources = collect();
@@ -66,13 +72,20 @@ public function registerResources(array $data): void
     }
 
     /**
+     * Get collection of registered resources
+     *
      * @return Resource[]
      */
     public function getResources(): Collection
     {
         return $this->resources;
     }
 
+    /**
+     * Register moonshine routes and resources routes in the system
+     *
+     * @return void
+     */
     protected function addRoutes(): void
     {
         Route::prefix(config('moonshine.route.prefix'))

src/Resources/Resource.php

@@ -7,6 +7,7 @@
 use Illuminate\Contracts\View\Factory;
 use Illuminate\Contracts\View\View;
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Scope;
 use Illuminate\Support\Collection;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Facades\Gate;
@@ -25,6 +26,7 @@
 use Leeto\MoonShine\Fields\Field;
 
 use Leeto\MoonShine\Filters\Filter;
+use Leeto\MoonShine\Metrics\Metric;
 use Leeto\MoonShine\MoonShine;
 
 abstract class Resource implements ResourceContract
@@ -55,30 +57,61 @@ abstract class Resource implements ResourceContract
 
     protected Model $item;
 
+    /**
+     * Get an array of validation rules for resource related model
+     *
+     * @see https://laravel.com/docs/validation#available-validation-rules
+     *
+     * @param Model $item
+     * @return array
+     */
     abstract function rules(Model $item): array;
 
     /**
+     * Get an array of visible fields on resource page
+     *
      * @return Field[]
      */
     abstract function fields(): array;
 
     /**
+     * Get an array of filters displayed on resource index page
+     *
      * @return Filter[]
      */
     abstract function filters(): array;
 
     /**
+     * Get an array of additional actions performed on resource page
+     *
      * @return Action[]
      */
     abstract function actions(): array;
 
+    /**
+     * Get an array of fields which will be used for search on resource index page
+     *
+     * @return array
+     */
     abstract function search(): array;
 
+    /**
+     * Get an array of filter scopes, which will be applied on resource index page
+     *
+     * @see https://laravel.com/docs/eloquent#writing-global-scopes
+     *
+     * @return Scope[]
+     */
     public function scopes(): array
     {
         return [];
     }
 
+    /**
+     * Get an array of metrics which will be displayed on resource index page
+     *
+     * @return Metric[]
+     */
     public function metrics(): array
     {
         return [];
@@ -220,21 +253,25 @@ public function getFields(): Collection
     }
 
     /**
-     * @return BaseFilter\[]
+     * @return Filter[]
      */
     public function getFilters(): Collection
     {
         return collect($this->filters());
     }
 
-    /* @return Tab[] */
+    /**
+     * @return Tab[]
+     */
     public function tabs(): Collection
     {
         return collect($this->fields())
             ->filter(fn ($item) => $item instanceof Tab);
     }
 
-    /* @return Field[] */
+    /**
+     * @return Field[]
+     */
     public function whenFields(): Collection
     {
         return collect($this->getFields())
@@ -257,14 +294,18 @@ public function isWhenConditionField(string $name): bool
         return $this->whenFieldNames()->has($name);
     }
 
-    /* @return Field[] */
+    /**
+     * @return Field[]
+     */
     public function indexFields(): Collection
     {
         return $this->getFields()
             ->filter(fn (RenderableContract $field) => $field instanceof Field && $field->showOnIndex);
     }
 
-    /* @return Field[] */
+    /**
+     * @return Field[]
+     */
     public function formFields(): Collection
     {
         $fields = $this->extensionsFields();
@@ -273,7 +314,9 @@ public function formFields(): Collection
             ->filter(fn (RenderableContract $field) => $field instanceof Field && $field->showOnForm));
     }
 
-    /* @return Field[] */
+    /**
+     * @return Field[]
+     */
     public function extensionsFields(): Collection
     {
         $fields = collect();
@@ -288,7 +331,9 @@ public function extensionsFields(): Collection
         return $fields;
     }
 
-    /* @return Field[] */
+    /**
+     * @return Field[]
+     */
     public function exportFields(): Collection
     {
         return $this->getFields()

src/Traits/Fields/FormElementTrait.php

@@ -28,6 +28,14 @@ trait FormElementTrait
 
     protected static string $view = '';
 
+    /**
+     * Creates a form element class: Field,Filter
+     *
+     * @param ...$arguments $label Form element label, will be displayed in moonshine admin panel,
+     *                      $field Field name from database, which will be used for this form element
+     *                      $resource Instance of related resource class, if form element is a relation
+     * @return static
+     */
     public static function make(...$arguments): static
     {
         return new static(...$arguments);