API documentation improved and auto generated. (#2812)

* WIP API documentation

* improved with more models

* more docs

* fix phpstan

* remove dead code

* fix comment

app/Http/Controllers/Admin/JobsController.php

@@ -13,6 +13,8 @@
 class JobsController extends Controller
 {
 	/**
+	 * List jobs executed on the server and the pending ones.
+	 *
 	 * @param ShowJobsRequest $request
 	 *
 	 * @return PaginatedDataCollection<(int|string),JobHistoryResource>

app/Http/Controllers/Admin/Maintenance/FixTree.php

@@ -14,18 +14,7 @@
 class FixTree extends Controller
 {
 	/**
-	 * Clean the path from all files excluding $this->skip.
-	 *
-	 * @return int
-	 */
-	public function do(MaintenanceRequest $request): int
-	{
-		return Album::query()->fixTree();
-	}
-
-	/**
-	 * Check whether there are files to be removed.
-	 * If not, we will not display the module to reduce complexity.
+	 * Check whether the Album tree is correct.
 	 *
 	 * @return TreeState
 	 */

app/Http/Controllers/Admin/Maintenance/FullTree.php

@@ -16,7 +16,8 @@
 class FullTree extends Controller
 {
 	/**
-	 * Clean the path from all files excluding $this->skip.
+	 * Apply the fix suggested.
+	 * ! This may break the installation. Not our problem.
 	 *
 	 * @return void
 	 */
@@ -28,8 +29,7 @@ public function do(FullTreeUpdateRequest $request): void
 	}
 
 	/**
-	 * Check whether there are files to be removed.
-	 * If not, we will not display the module to reduce complexity.
+	 * Display the current full tree of albums.
 	 *
 	 * @return Collection<int,AlbumTree>
 	 */

app/Http/Controllers/Admin/Maintenance/RegisterController.php

@@ -11,6 +11,8 @@
 class RegisterController extends Controller
 {
 	/**
+	 * Register the Lychee Supporter Edition license key.
+	 *
 	 * @param RegisterRequest $request
 	 *
 	 * @return RegisterData

app/Http/Controllers/Admin/SettingsController.php

@@ -17,6 +17,13 @@
  */
 class SettingsController extends Controller
 {
+	/**
+	 * Fetch all the settings available in Lychee.
+	 *
+	 * @param GetAllConfigsRequest $request
+	 *
+	 * @return ConfigCollectionResource
+	 */
 	public function getAll(GetAllConfigsRequest $request): ConfigCollectionResource
 	{
 		$editable_configs = Configs::query()
@@ -27,6 +34,13 @@ public function getAll(GetAllConfigsRequest $request): ConfigCollectionResource
 		return new ConfigCollectionResource($editable_configs);
 	}
 
+	/**
+	 * Set a limited number of configurations with the new values.
+	 *
+	 * @param SetConfigsRequest $request
+	 *
+	 * @return ConfigCollectionResource
+	 */
 	public function setConfigs(SetConfigsRequest $request): ConfigCollectionResource
 	{
 		$configs = $request->configs();

app/Http/Controllers/Admin/UpdateController.php

@@ -29,6 +29,14 @@ public function __construct(ApplyUpdate $applyUpdate)
 		$this->applyUpdate = $applyUpdate;
 	}
 
+	/**
+	 * Retrieve Update data from the server.
+	 *
+	 * @param UpdateRequest $request
+	 * @param VersionInfo   $versionInfo
+	 *
+	 * @return UpdateInfo
+	 */
 	public function get(UpdateRequest $request, VersionInfo $versionInfo): UpdateInfo
 	{
 		/** @var VersionChannelType $channelName */

app/Http/Controllers/AuthController.php

@@ -13,7 +13,6 @@
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Facades\Session;
-use Spatie\LaravelData\Data;
 
 /**
  * Controller responsible for the authentication of the user.
@@ -59,17 +58,17 @@ public function logout(): void
 	/**
 	 * Get the global rights of the current user.
 	 */
-	public function getGlobalRights(): Data
+	public function getGlobalRights(): GlobalRightsResource
 	{
 		return new GlobalRightsResource();
 	}
 
 	/**
 	 * First function being called via AJAX.
 	 *
-	 * @return Data
+	 * @return UserResource
 	 */
-	public function getCurrentUser(): Data
+	public function getCurrentUser(): UserResource
 	{
 		/** @var User|null $user */
 		$user = Auth::user();
@@ -80,9 +79,9 @@ public function getCurrentUser(): Data
 	/**
 	 * Return the configuration for the authentication.
 	 *
-	 * @return Data
+	 * @return AuthConfig
 	 */
-	public function getConfig(): Data
+	public function getConfig(): AuthConfig
 	{
 		return new AuthConfig();
 	}

app/Http/Controllers/Gallery/AlbumController.php

@@ -83,6 +83,13 @@ public function get(GetAlbumRequest $request): AbstractAlbumResource
 		return new AbstractAlbumResource($config, $albumResource);
 	}
 
+	/**
+	 * Create an album.
+	 *
+	 * @param AddAlbumRequest $request
+	 *
+	 * @return string
+	 */
 	public function createAlbum(AddAlbumRequest $request): string
 	{
 		/** @var int $ownerId */
@@ -92,11 +99,25 @@ public function createAlbum(AddAlbumRequest $request): string
 		return $create->create($request->title(), $request->parent_album())->id;
 	}
 
+	/**
+	 * Create a tag album.
+	 *
+	 * @param AddTagAlbumRequest $request
+	 *
+	 * @return string
+	 */
 	public function createTagAlbum(AddTagAlbumRequest $request, CreateTagAlbum $create): string
 	{
 		return $create->create($request->title(), $request->tags())->id;
 	}
 
+	/**
+	 * Update the info of an Album.
+	 *
+	 * @param UpdateAlbumRequest $request
+	 *
+	 * @return EditableBaseAlbumResource
+	 */
 	public function updateAlbum(UpdateAlbumRequest $request, SetHeader $setHeader): EditableBaseAlbumResource
 	{
 		$album = $request->album();
@@ -124,6 +145,13 @@ public function updateAlbum(UpdateAlbumRequest $request, SetHeader $setHeader):
 		return EditableBaseAlbumResource::fromModel($album);
 	}
 
+	/**
+	 * Update the info of a Tag Album.
+	 *
+	 * @param UpdateTagAlbumRequest $request
+	 *
+	 * @return EditableBaseAlbumResource
+	 */
 	public function updateTagAlbum(UpdateTagAlbumRequest $request): EditableBaseAlbumResource
 	{
 		$album = $request->album();
@@ -142,6 +170,15 @@ public function updateTagAlbum(UpdateTagAlbumRequest $request): EditableBaseAlbu
 		return EditableBaseAlbumResource::fromModel($album);
 	}
 
+	/**
+	 * Update the protection policy of an Abstract Album.
+	 *
+	 * @param SetAlbumProtectionPolicyRequest $request
+	 * @param SetProtectionPolicy             $setProtectionPolicy
+	 * @param SetSmartProtectionPolicy        $setSmartProtectionPolicy
+	 *
+	 * @return AlbumProtectionPolicy
+	 */
 	public function updateProtectionPolicy(SetAlbumProtectionPolicyRequest $request,
 		SetProtectionPolicy $setProtectionPolicy,
 		SetSmartProtectionPolicy $setSmartProtectionPolicy): AlbumProtectionPolicy
@@ -224,6 +261,8 @@ public function move(MoveAlbumsRequest $request, Move $move): void
 	}
 
 	/**
+	 * Transfer the ownership of the album to another user.
+	 *
 	 * @param TransferAlbumRequest $request
 	 * @param Transfer             $transfer
 	 *
@@ -235,6 +274,8 @@ public function transfer(TransferAlbumRequest $request, Transfer $transfer): voi
 	}
 
 	/**
+	 * Set the album cover (the square thumb).
+	 *
 	 * @param SetAsCoverRequest $request
 	 *
 	 * @return void
@@ -247,6 +288,8 @@ public function cover(SetAsCoverRequest $request): void
 	}
 
 	/**
+	 * Set the album header (the hero banner).
+	 *
 	 * @param $request
 	 *
 	 * @return void

app/Http/Controllers/Gallery/AlbumsController.php

@@ -13,6 +13,8 @@
 class AlbumsController extends Controller
 {
 	/**
+	 * Retrieve all the albums at the root.
+	 *
 	 * @return RootAlbumResource returns the top albums
 	 */
 	public function get(Top $top): RootAlbumResource

app/Http/Controllers/Gallery/ConfigController.php

@@ -7,7 +7,6 @@
 use App\Http\Resources\GalleryConfigs\PhotoLayoutConfig;
 use App\Http\Resources\GalleryConfigs\UploadConfig;
 use Illuminate\Routing\Controller;
-use Spatie\LaravelData\Data;
 
 /**
  * Controller responsible for the config.
@@ -17,37 +16,37 @@ class ConfigController extends Controller
 	/**
 	 * Return global gallery config.
 	 *
-	 * @return Data
+	 * @return InitConfig
 	 */
-	public function getInit(): Data
+	public function getInit(): InitConfig
 	{
 		return new InitConfig();
 	}
 
 	/**
 	 * Return gallery layout info.
 	 */
-	public function getGalleryLayout(): Data
+	public function getGalleryLayout(): PhotoLayoutConfig
 	{
 		return new PhotoLayoutConfig();
 	}
 
 	/**
 	 * Return the configuration of the uploader.
 	 *
-	 * @return Data
+	 * @return UploadConfig
 	 */
-	public function getUploadCOnfig(): Data
+	public function getUploadCOnfig(): UploadConfig
 	{
 		return new UploadConfig();
 	}
 
 	/**
-	 * Return global gallery config.
+	 * Return the Footer data.
 	 *
-	 * @return Data
+	 * @return FooterConfig
 	 */
-	public function getFooter(): Data
+	public function getFooter(): FooterConfig
 	{
 		return new FooterConfig();
 	}

app/Http/Controllers/Gallery/MapController.php

@@ -8,7 +8,6 @@
 use App\Http\Resources\Collections\PositionDataResource;
 use App\Http\Resources\GalleryConfigs\MapProviderData;
 use App\Models\Configs;
-use Spatie\LaravelData\Data;
 
 class MapController
 {
@@ -21,19 +20,24 @@ public function __construct()
 		$this->albumPositionData = resolve(AlbumPositionData::class);
 	}
 
-	public function getProvider(): Data
+	/**
+	 * Return the configuration data for the Map.
+	 *
+	 * @return MapProviderData
+	 */
+	public function getProvider(): MapProviderData
 	{
 		return new MapProviderData();
 	}
 
 	/**
-	 * Return an image and the timeout if the frame is supported..
+	 * Return the Map data for an album or root.
 	 *
 	 * @param MapDataRequest $request
 	 *
 	 * @return PositionDataResource
 	 */
-	public function getData(MapDataRequest $request): Data
+	public function getData(MapDataRequest $request): PositionDataResource
 	{
 		$album = $request->album();
 

app/Http/Controllers/Gallery/PhotoController.php

@@ -41,6 +41,13 @@ class PhotoController extends Controller
 {
 	public const DISK_NAME = 'image-upload';
 
+	/**
+	 * Upload a picture.
+	 *
+	 * @param UploadPhotoRequest $request
+	 *
+	 * @return UploadMetaResource
+	 */
 	public function upload(UploadPhotoRequest $request): UploadMetaResource
 	{
 		$meta = $request->meta();
@@ -95,6 +102,14 @@ private function process(
 		return $meta;
 	}
 
+	/**
+	 * Upload a picture from a URL.
+	 *
+	 * @param FromUrlRequest $request
+	 * @param FromUrl        $fromUrl
+	 *
+	 * @return string
+	 */
 	public function fromUrl(FromUrlRequest $request, FromUrl $fromUrl): string
 	{
 		/** @var int $userId */
@@ -104,6 +119,13 @@ public function fromUrl(FromUrlRequest $request, FromUrl $fromUrl): string
 		return 'success';
 	}
 
+	/**
+	 * Update the info of a picture.
+	 *
+	 * @param EditPhotoRequest $request
+	 *
+	 * @return PhotoResource
+	 */
 	public function update(EditPhotoRequest $request): PhotoResource
 	{
 		$photo = $request->photo();

app/Http/Controllers/Gallery/SearchController.php

@@ -15,7 +15,6 @@
 use App\Models\Photo;
 use Illuminate\Contracts\Pagination\LengthAwarePaginator;
 use Illuminate\Routing\Controller;
-use Spatie\LaravelData\Data;
 
 /**
  * Controller responsible for the config.
@@ -29,7 +28,7 @@ class SearchController extends Controller
 	 *
 	 * @return InitResource
 	 */
-	public function init(InitSearchRequest $request): Data
+	public function init(InitSearchRequest $request): InitResource
 	{
 		return new InitResource();
 	}