fix(ban): Improve documentation of types

Signed-off-by: Joas Schilling <coding@schilljs.com>

3 files changed, 15 insertions, 9 deletions

diff --git a/lib/Controller/BanController.php b/lib/Controller/BanController.php
index f035ad460..43cf0bca1 100644
--- a/lib/Controller/BanController.php
+++ b/lib/Controller/BanController.php
@@ -11,6 +11,7 @@ namespace OCA\Talk\Controller;
 
 use OCA\Talk\Middleware\Attribute\RequireModeratorParticipant;
 use OCA\Talk\Model\Attendee;
+use OCA\Talk\Model\Ban;
 use OCA\Talk\ResponseDefinitions;
 use OCA\Talk\Service\BanService;
 use OCP\AppFramework\Http;
@@ -79,7 +80,7 @@ class BanController extends AEnvironmentAwareController {
 	 *
 	 * Required capability: `ban-v1`
 	 *
-	 * @return DataResponse<Http::STATUS_OK, list<TalkBan>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, TalkBan[], array{}>
 	 *
 	 * 200: List all bans
 	 */
@@ -87,11 +88,7 @@ class BanController extends AEnvironmentAwareController {
 	#[RequireModeratorParticipant]
 	public function listBans(): DataResponse {
 		$bans = $this->banService->getBansForRoom($this->room->getId());
-		$result = array_map(function ($ban) {
-			return $ban->jsonSerialize();
-		}, $bans);
-
-		/** @psalm-var list<array{actorId: string, actorType: string, bannedId: string, bannedTime: int, bannedType: string, id: int, internalNote: string}> $result */
+		$result = array_map(static fn (Ban $ban): array => $ban->jsonSerialize(), $bans);
 		return new DataResponse($result, Http::STATUS_OK);
 	}
 
diff --git a/lib/Model/Ban.php b/lib/Model/Ban.php
index 455aee353..8f1e4d69b 100644
--- a/lib/Model/Ban.php
+++ b/lib/Model/Ban.php
@@ -8,9 +8,12 @@ declare(strict_types=1);
 
 namespace OCA\Talk\Model;
 
+use OCA\Talk\ResponseDefinitions;
 use OCP\AppFramework\Db\Entity;
 
 /**
+ * @psalm-import-type TalkBan from ResponseDefinitions
+ *
  * @method void setId(int $id)
  * @method int getId()
  * @method void setActorType(string $actorType)
@@ -48,15 +51,17 @@ class Ban extends Entity implements \JsonSerializable {
 		$this->addType('internalNote', 'string');
 	}
 
+	/**
+	 * @return TalkBan
+	 */
 	public function jsonSerialize(): array {
 		return [
 			'id' => $this->getId(),
 			'actorType' => $this->getActorType(),
 			'actorId' => $this->getActorId(),
-			'roomId' => $this->getRoomId(),
 			'bannedType' => $this->getBannedType(),
 			'bannedId' => $this->getBannedId(),
-			'bannedTime' => $this->getBannedTime() ? $this->getBannedTime()->getTimestamp() : null,
+			'bannedTime' => $this->getBannedTime()->getTimestamp(),
 			'internalNote' => $this->getInternalNote(),
 		];
 	}
diff --git a/lib/Service/BanService.php b/lib/Service/BanService.php
index 900b5f5da..f36f9013e 100644
--- a/lib/Service/BanService.php
+++ b/lib/Service/BanService.php
@@ -48,6 +48,8 @@ class BanService {
 
 	/**
 	 * Retrieve a ban for a specific actor and room.
+	 *
+	 * @throws DoesNotExistException
 	 */
 	public function getBanForActorAndRoom(string $actorId, string $actorType, int $roomId): Ban {
 		return $this->banMapper->findForActorAndRoom($actorId, $actorType, $roomId);
@@ -55,6 +57,8 @@ class BanService {
 
 	/**
 	 * Retrieve all bans for a specific room.
+	 *
+	 * @return Ban[]
 	 */
 	public function getBansForRoom(int $roomId): array {
 		return $this->banMapper->findByRoomId($roomId);
@@ -67,7 +71,7 @@ class BanService {
 		try {
 			$ban = $this->banMapper->findByBanIdAndRoom($banId, $roomId);
 			$this->banMapper->delete($ban);
-		} catch (DoesNotExistException $e) {
+		} catch (DoesNotExistException) {
 			// Ban does not exist
 		}
 	}