more docs

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/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

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

@@ -42,7 +42,7 @@ public function getUploadCOnfig(): UploadConfig
 	}
 
 	/**
-	 * Return global gallery config.
+	 * Return the Footer data.
 	 *
 	 * @return FooterConfig
 	 */

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
 	 *

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/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
 	 *

app/Http/Controllers/RSSController.php

@@ -13,6 +13,8 @@
 class RSSController extends Controller
 {
 	/**
+	 * Get the RSS Feed.
+	 *
 	 * @param Generate $generate
 	 *
 	 * @return Collection<int,FeedItem>

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

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();

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