fix(files_external): suppress Psalm ImpureStaticProperty and tidy docblocks

Assisted-by: ClaudeCode:claude-opus-4-7
Signed-off-by: Tobias Harnickell <tobias.harnickell@bedag.ch>

Author: TobyTheHutt

apps/files_external/lib/Lib/Storage/AmazonS3.php

@@ -54,7 +54,11 @@ class AmazonS3 extends Common {
 
 	private bool $serverSideCopyEnabled;
 
-	/** Failure counter keyed by endpoint fingerprint. Static so sibling mounts share state within a request. */
+	/**
+	 * Keyed by endpoint fingerprint. Static because sibling mounts share state within a request.
+	 *
+	 * @psalm-suppress ImpureStaticProperty MUST persist across per-mount instances within a request.
+	 */
 	private static array $serverSideCopyFailureCounter = [];
 
 	/** Fast path MUST stay disabled for the remainder of the request after this many consecutive S3Exceptions per endpoint. */
@@ -813,7 +817,7 @@ public function writeStream(string $path, $stream, ?int $size = null): int {
 		return $size;
 	}
 
-	#[Override]
+	#[\Override]
 	public function getDirectDownload(string $path): array|false {
 		if (!$this->isUsePresignedUrl()) {
 			return false;
@@ -843,7 +847,7 @@ public function getDirectDownload(string $path): array|false {
 		];
 	}
 
-	#[Override]
+	#[\Override]
 	public function getDirectDownloadById(string $fileId): array|false {
 		if (!$this->isUsePresignedUrl()) {
 			return false;
@@ -853,7 +857,7 @@ public function getDirectDownloadById(string $fileId): array|false {
 		return $this->getDirectDownload($entry->getPath());
 	}
 
-	#[Override]
+	#[\Override]
 	public function copyFromStorage(IStorage $sourceStorage, string $sourceInternalPath, string $targetInternalPath, bool $preserveMtime = false): bool {
 		if ($preserveMtime === true) {
 			return parent::copyFromStorage($sourceStorage, $sourceInternalPath, $targetInternalPath, $preserveMtime);
@@ -882,7 +886,7 @@ public function copyFromStorage(IStorage $sourceStorage, string $sourceInternalP
 		}
 	}
 
-	#[Override]
+	#[\Override]
 	public function moveFromStorage(IStorage $sourceStorage, string $sourceInternalPath, string $targetInternalPath): bool {
 		$eligibility = $this->evaluateFastPathEligibility($sourceStorage, $sourceInternalPath);
 		if ($eligibility === null) {
@@ -959,10 +963,7 @@ private function handleFastPathFailure(S3Exception $exception, string $targetKey
 	}
 
 	/**
-	 * Returns null when the terminal storage is not an AmazonS3. Otherwise returns the
-	 * unwrapped storage plus the Jail-translated path.
-	 *
-	 * @return array{0: self, 1: string}|null
+	 * @return array{0: self, 1: string}|null Unwrapped storage and Jail-translated path, or null when the terminal storage is not AmazonS3.
 	 */
 	private function unwrapSource(IStorage $sourceStorage, string $sourceInternalPath): ?array {
 		$current = $sourceStorage;
@@ -986,10 +987,7 @@ private function isSameS3Endpoint(self $other): bool {
 	}
 
 	/**
-	 * Normalised endpoint identity tuple. Two AmazonS3 instances with identical fingerprints
-	 * target the same S3 endpoint under the same access-key ID.
-	 *
-	 * @return list<string>
+	 * @return list<string> Endpoint identity tuple including access-key ID so distinct credentials against the same host do not collide.
 	 */
 	private function endpointFingerprint(): array {
 		return [
@@ -1086,8 +1084,7 @@ private function copyObjectFromForeignBucket(
 	}
 
 	/**
-	 * Delete the source after a successful server-side copy. Roll back the destination on
-	 * cleanup failure to mirror AmazonS3::rename() semantics and to let the caller retry.
+	 * Roll back the destination on cleanup failure to mirror AmazonS3::rename() semantics and let the caller retry.
 	 */
 	private function deleteSourceAfterMove(self $source, string $sourcePath, string $targetPath): bool {
 		$deleted = $source->is_dir($sourcePath) ? $source->rmdir($sourcePath) : $source->unlink($sourcePath);