From fc25141498eee576bf1ab497bf7c3121bf269bbb Mon Sep 17 00:00:00 2001 From: ildyria Date: Mon, 16 Dec 2024 13:59:22 +0100 Subject: [PATCH] more docs --- app/Http/Controllers/Admin/JobsController.php | 2 + .../Controllers/Admin/Maintenance/FixTree.php | 13 +----- .../Admin/Maintenance/FullTree.php | 6 +-- .../Admin/Maintenance/RegisterController.php | 2 + .../Controllers/Admin/SettingsController.php | 14 ++++++ .../Controllers/Admin/UpdateController.php | 8 ++++ .../Controllers/Gallery/AlbumController.php | 43 +++++++++++++++++++ .../Controllers/Gallery/AlbumsController.php | 2 + .../Controllers/Gallery/ConfigController.php | 2 +- .../Controllers/Gallery/MapController.php | 7 ++- .../Controllers/Gallery/PhotoController.php | 22 ++++++++++ .../Controllers/Gallery/SharingController.php | 2 + app/Http/Controllers/RSSController.php | 2 + app/Http/Controllers/StatisticsController.php | 7 +++ app/Http/Controllers/UsersController.php | 7 +++ .../WebAuthn/WebAuthnManageController.php | 2 + 16 files changed, 124 insertions(+), 17 deletions(-) diff --git a/app/Http/Controllers/Admin/JobsController.php b/app/Http/Controllers/Admin/JobsController.php index 4ebad0b547b..f8bc34a8762 100644 --- a/app/Http/Controllers/Admin/JobsController.php +++ b/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> diff --git a/app/Http/Controllers/Admin/Maintenance/FixTree.php b/app/Http/Controllers/Admin/Maintenance/FixTree.php index b706302540e..8759394551b 100644 --- a/app/Http/Controllers/Admin/Maintenance/FixTree.php +++ b/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 */ diff --git a/app/Http/Controllers/Admin/Maintenance/FullTree.php b/app/Http/Controllers/Admin/Maintenance/FullTree.php index 2d3b444662f..75e38aaa2a3 100644 --- a/app/Http/Controllers/Admin/Maintenance/FullTree.php +++ b/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 */ diff --git a/app/Http/Controllers/Admin/Maintenance/RegisterController.php b/app/Http/Controllers/Admin/Maintenance/RegisterController.php index 386d6da1e5f..7bfefd1df64 100644 --- a/app/Http/Controllers/Admin/Maintenance/RegisterController.php +++ b/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 diff --git a/app/Http/Controllers/Admin/SettingsController.php b/app/Http/Controllers/Admin/SettingsController.php index 2fc962aec9f..03491bf0402 100644 --- a/app/Http/Controllers/Admin/SettingsController.php +++ b/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(); diff --git a/app/Http/Controllers/Admin/UpdateController.php b/app/Http/Controllers/Admin/UpdateController.php index 59d893beb97..b0ac235e56e 100644 --- a/app/Http/Controllers/Admin/UpdateController.php +++ b/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 */ diff --git a/app/Http/Controllers/Gallery/AlbumController.php b/app/Http/Controllers/Gallery/AlbumController.php index e9a83a0146e..ab5a4892cdf 100644 --- a/app/Http/Controllers/Gallery/AlbumController.php +++ b/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 AddAlbumRequest $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 AddAlbumRequest $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 diff --git a/app/Http/Controllers/Gallery/AlbumsController.php b/app/Http/Controllers/Gallery/AlbumsController.php index 3120124848b..7b0552a7cca 100644 --- a/app/Http/Controllers/Gallery/AlbumsController.php +++ b/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 diff --git a/app/Http/Controllers/Gallery/ConfigController.php b/app/Http/Controllers/Gallery/ConfigController.php index e875a2a1e35..0eaefb4c827 100644 --- a/app/Http/Controllers/Gallery/ConfigController.php +++ b/app/Http/Controllers/Gallery/ConfigController.php @@ -42,7 +42,7 @@ public function getUploadCOnfig(): UploadConfig } /** - * Return global gallery config. + * Return the Footer data. * * @return FooterConfig */ diff --git a/app/Http/Controllers/Gallery/MapController.php b/app/Http/Controllers/Gallery/MapController.php index 4602e32eb82..0253dcb0e10 100644 --- a/app/Http/Controllers/Gallery/MapController.php +++ b/app/Http/Controllers/Gallery/MapController.php @@ -20,13 +20,18 @@ public function __construct() $this->albumPositionData = resolve(AlbumPositionData::class); } + /** + * 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 * diff --git a/app/Http/Controllers/Gallery/PhotoController.php b/app/Http/Controllers/Gallery/PhotoController.php index e3c71fea53a..60887055c64 100644 --- a/app/Http/Controllers/Gallery/PhotoController.php +++ b/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(); diff --git a/app/Http/Controllers/Gallery/SharingController.php b/app/Http/Controllers/Gallery/SharingController.php index b3d90b68f17..a780bd9e8f3 100644 --- a/app/Http/Controllers/Gallery/SharingController.php +++ b/app/Http/Controllers/Gallery/SharingController.php @@ -22,6 +22,8 @@ class SharingController extends Controller { /** + * Create a new Sharing link between a user and an album. + * * @param AddSharingRequest $request * @param Share $share * diff --git a/app/Http/Controllers/RSSController.php b/app/Http/Controllers/RSSController.php index 482073df6b1..9c784373d4e 100644 --- a/app/Http/Controllers/RSSController.php +++ b/app/Http/Controllers/RSSController.php @@ -13,6 +13,8 @@ class RSSController extends Controller { /** + * Get the RSS Feed. + * * @param Generate $generate * * @return Collection diff --git a/app/Http/Controllers/StatisticsController.php b/app/Http/Controllers/StatisticsController.php index be3f257cbb7..1e50d07615f 100644 --- a/app/Http/Controllers/StatisticsController.php +++ b/app/Http/Controllers/StatisticsController.php @@ -15,6 +15,8 @@ class StatisticsController extends Controller { /** + * Fetch the used space per user. + * * @param SpacePerUserRequest $request * @param Spaces $spaces * @@ -30,6 +32,8 @@ public function getSpacePerUser(SpacePerUserRequest $request, Spaces $spaces): C } /** + * Fetch the used space per SizeVariant type. + * * @param SpaceSizeVariantRequest $request * @param Spaces $spaces * @@ -48,6 +52,8 @@ public function getSpacePerSizeVariantType(SpaceSizeVariantRequest $request, Spa } /** + * Fetch the used space and number of photos per Album (without descendants). + * * @param SpacePerAlbumRequest $request * @param Spaces $spaces * @@ -72,6 +78,7 @@ public function getSpacePerAlbum(SpacePerAlbumRequest $request, Spaces $spaces): } /** + * Fetch the used space and number of photos per Album with descendants * ! Slow query. * * @param SpacePerAlbumRequest $request diff --git a/app/Http/Controllers/UsersController.php b/app/Http/Controllers/UsersController.php index 22d7a6b3f8f..4254ac9c153 100644 --- a/app/Http/Controllers/UsersController.php +++ b/app/Http/Controllers/UsersController.php @@ -15,6 +15,13 @@ */ class UsersController extends Controller { + /** + * Count the number of registered users. + * + * @param UsersRequest $_request + * + * @return int + */ public function count(UsersRequest $_request): int { return User::count(); diff --git a/app/Http/Controllers/WebAuthn/WebAuthnManageController.php b/app/Http/Controllers/WebAuthn/WebAuthnManageController.php index ce2941dbf3f..e71a8902076 100644 --- a/app/Http/Controllers/WebAuthn/WebAuthnManageController.php +++ b/app/Http/Controllers/WebAuthn/WebAuthnManageController.php @@ -30,6 +30,8 @@ public function list(ListCredentialsRequest $request): Collection } /** + * Delete a WebAuthn credential. + * * @throws UnauthenticatedException */ public function delete(DeleteCredentialRequest $request): void