fix(comments): Add return types to interface

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

lib/private/Comments/Manager.php

@@ -356,38 +356,6 @@ class Manager implements ICommentsManager {
 		return $comments;
 	}
 
-	/**
-	 * @param string $objectType the object type, e.g. 'files'
-	 * @param string $objectId the id of the object
-	 * @param int $lastKnownCommentId the last known comment (will be used as offset)
-	 * @param string $sortDirection direction of the comments (`asc` or `desc`)
-	 * @param int $limit optional, number of maximum comments to be returned. if
-	 *                   set to 0, all comments are returned.
-	 * @param bool $includeLastKnown
-	 * @param string $topmostParentId Limit the comments to a list of replies and its original root comment
-	 * @return list<IComment>
-	 */
-	public function getForObjectSince(
-		string $objectType,
-		string $objectId,
-		int $lastKnownCommentId,
-		string $sortDirection = 'asc',
-		int $limit = 30,
-		bool $includeLastKnown = false,
-		string $topmostParentId = '',
-	): array {
-		return $this->getCommentsWithVerbForObjectSinceComment(
-			$objectType,
-			$objectId,
-			[],
-			$lastKnownCommentId,
-			$sortDirection,
-			$limit,
-			$includeLastKnown,
-			$topmostParentId,
-		);
-	}
-
 	/**
 	 * @param string $objectType the object type, e.g. 'files'
 	 * @param string $objectId the id of the object
@@ -695,22 +663,6 @@ class Manager implements ICommentsManager {
 		return $unreadComments;
 	}
 
-	/**
-	 * @param string $objectType
-	 * @param string $objectId
-	 * @param int $lastRead
-	 * @param string $verb
-	 * @return int
-	 * @since 21.0.0
-	 */
-	public function getNumberOfCommentsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, string $verb = ''): int {
-		if ($verb !== '') {
-			return $this->getNumberOfCommentsWithVerbsForObjectSinceComment($objectType, $objectId, $lastRead, [$verb]);
-		}
-
-		return $this->getNumberOfCommentsWithVerbsForObjectSinceComment($objectType, $objectId, $lastRead, []);
-	}
-
 	/**
 	 * @param string $objectType
 	 * @param string $objectId
@@ -805,30 +757,6 @@ class Manager implements ICommentsManager {
 		return $lastComments;
 	}
 
-	/**
-	 * Get the number of unread comments for all files in a folder
-	 *
-	 * This is unused since 8bd39fccf411195839f2dadee085fad18ec52c23
-	 *
-	 * @param int $folderId
-	 * @param IUser $user
-	 * @return array [$fileId => $unreadCount]
-	 */
-	public function getNumberOfUnreadCommentsForFolder($folderId, IUser $user) {
-		$directory = $this->rootFolder->getFirstNodeById($folderId);
-		if (!$directory instanceof Folder) {
-			return [];
-		}
-		$children = $directory->getDirectoryListing();
-		$ids = array_map(fn (FileInfo $child) => (string)$child->getId(), $children);
-
-		$ids[] = (string)$directory->getId();
-		$counts = $this->getNumberOfUnreadCommentsForObjects('files', $ids, $user);
-		return array_filter($counts, function (int $count) {
-			return $count > 0;
-		});
-	}
-
 	/**
 	 * creates a new comment and returns it. At this point of time, it is not
 	 * saved in the used data storage. Use save() after setting other fields

lib/public/Comments/CommentsEntityEvent.php

@@ -7,6 +7,7 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Listenable;
 use OCP\EventDispatcher\Event;
 
 /**
@@ -15,6 +16,7 @@ use OCP\EventDispatcher\Event;
  * @since 9.1.0
  * @since 28.0.0 Dispatched as a typed event
  */
+#[Listenable('28.0.0')]
 class CommentsEntityEvent extends Event {
 	/**
 	 * @since 9.1.0

lib/public/Comments/CommentsEvent.php

@@ -7,6 +7,7 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Listenable;
 use OCP\EventDispatcher\Event;
 
 /**
@@ -14,6 +15,7 @@ use OCP\EventDispatcher\Event;
  *
  * @since 9.0.0
  */
+#[Listenable('28.0.0')]
 class CommentsEvent extends Event {
 	/**
 	 * @since 11.0.0

lib/public/Comments/IComment.php

@@ -7,6 +7,8 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Consumable;
+
 /**
  * Interface IComment
  *
@@ -14,6 +16,7 @@ namespace OCP\Comments;
  *
  * @since 9.0.0
  */
+#[Consumable('9.0.0')]
 interface IComment {
 	/**
 	 * @since 9.0.0

lib/public/Comments/ICommentsManager.php

@@ -7,6 +7,8 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Consumable;
+use OCP\AppFramework\Attribute\ExceptionalImplementable;
 use OCP\IUser;
 use OCP\PreConditionNotMetException;
 
@@ -17,6 +19,8 @@ use OCP\PreConditionNotMetException;
  *
  * @since 9.0.0
  */
+#[Consumable('9.0.0')]
+#[ExceptionalImplementable('spreed', \OCA\Talk\Chat\CommentsManager::class)]
 interface ICommentsManager {
 	/**
 	 * @const DELETED_USER type and id for a user that has been deleted
@@ -37,7 +41,7 @@ interface ICommentsManager {
 	 * @throws NotFoundException
 	 * @since 9.0.0
 	 */
-	public function get($id);
+	public function get($id): IComment;
 
 	/**
 	 * Returns the comment specified by the id and all it's child comments
@@ -75,7 +79,7 @@ interface ICommentsManager {
 	 *   ]
 	 * ]
 	 */
-	public function getTree($id, $limit = 0, $offset = 0);
+	public function getTree($id, $limit = 0, $offset = 0): array;
 
 	/**
 	 * returns comments for a specific object (e.g. a file).
@@ -98,29 +102,6 @@ interface ICommentsManager {
 		$limit = 0,
 		$offset = 0,
 		?\DateTime $notOlderThan = null,
-	);
-
-	/**
-	 * @param string $objectType the object type, e.g. 'files'
-	 * @param string $objectId the id of the object
-	 * @param int $lastKnownCommentId the last known comment (will be used as offset)
-	 * @param string $sortDirection direction of the comments (`asc` or `desc`)
-	 * @param int $limit optional, number of maximum comments to be returned. if
-	 *                   set to 0, all comments are returned.
-	 * @param bool $includeLastKnown
-	 * @param string $topmostParentId Limit the comments to a list of replies and its original root comment
-	 * @return list<IComment>
-	 * @since 14.0.0
-	 * @deprecated 24.0.0 - Use getCommentsWithVerbForObjectSinceComment instead
-	 */
-	public function getForObjectSince(
-		string $objectType,
-		string $objectId,
-		int $lastKnownCommentId,
-		string $sortDirection = 'asc',
-		int $limit = 30,
-		bool $includeLastKnown = false,
-		string $topmostParentId = '',
 	): array;
 
 	/**
@@ -181,10 +162,10 @@ interface ICommentsManager {
 	 * @param \DateTime|null $notOlderThan optional, timestamp of the oldest comments
 	 *                                     that may be returned
 	 * @param string $verb Limit the verb of the comment - Added in 14.0.0
-	 * @return Int
+	 * @return int
 	 * @since 9.0.0
 	 */
-	public function getNumberOfCommentsForObject($objectType, $objectId, ?\DateTime $notOlderThan = null, $verb = '');
+	public function getNumberOfCommentsForObject($objectType, $objectId, ?\DateTime $notOlderThan = null, $verb = ''): int;
 
 	/**
 	 * @param string $objectType the object type, e.g. 'files'
@@ -197,18 +178,6 @@ interface ICommentsManager {
 	 */
 	public function getNumberOfUnreadCommentsForObjects(string $objectType, array $objectIds, IUser $user, $verb = ''): array;
 
-	/**
-	 * @param string $objectType
-	 * @param string $objectId
-	 * @param int $lastRead
-	 * @param string $verb
-	 * @return int
-	 * @since 21.0.0
-	 * @deprecated 24.0.0 - Use getNumberOfCommentsWithVerbsForObjectSinceComment instead
-	 */
-	public function getNumberOfCommentsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, string $verb = ''): int;
-
-
 	/**
 	 * @param string $objectType
 	 * @param string $objectId
@@ -247,17 +216,6 @@ interface ICommentsManager {
 		array $actors,
 	): array;
 
-	/**
-	 * Get the number of unread comments for all files in a folder
-	 *
-	 * @param int $folderId
-	 * @param IUser $user
-	 * @return array [$fileId => $unreadCount]
-	 * @since 12.0.0
-	 * @deprecated 29.0.0 use getNumberOfUnreadCommentsForObjects instead
-	 */
-	public function getNumberOfUnreadCommentsForFolder($folderId, IUser $user);
-
 	/**
 	 * creates a new comment and returns it. At this point of time, it is not
 	 * saved in the used data storage. Use save() after setting other fields
@@ -270,7 +228,7 @@ interface ICommentsManager {
 	 * @return IComment
 	 * @since 9.0.0
 	 */
-	public function create($actorType, $actorId, $objectType, $objectId);
+	public function create($actorType, $actorId, $objectType, $objectId): IComment;
 
 	/**
 	 * permanently deletes the comment specified by the ID
@@ -282,7 +240,7 @@ interface ICommentsManager {
 	 * @return bool
 	 * @since 9.0.0
 	 */
-	public function delete($id);
+	public function delete($id): bool;
 
 	/**
 	 * Get comment related with user reaction
@@ -345,14 +303,14 @@ interface ICommentsManager {
 	 * Otherwise, an existing comment will be updated.
 	 *
 	 * Throws NotFoundException when a comment that is to be updated does not
-	 * exist anymore at this point of time.
+	 * exist any more at this point of time.
 	 *
 	 * @param IComment $comment
 	 * @return bool
 	 * @throws NotFoundException
 	 * @since 9.0.0
 	 */
-	public function save(IComment $comment);
+	public function save(IComment $comment): bool;
 
 	/**
 	 * removes references to specific actor (e.g. on user delete) of a comment.
@@ -366,7 +324,7 @@ interface ICommentsManager {
 	 * @return boolean
 	 * @since 9.0.0
 	 */
-	public function deleteReferencesOfActor($actorType, $actorId);
+	public function deleteReferencesOfActor($actorType, $actorId): bool;
 
 	/**
 	 * deletes all comments made of a specific object (e.g. on file delete)
@@ -376,7 +334,7 @@ interface ICommentsManager {
 	 * @return boolean
 	 * @since 9.0.0
 	 */
-	public function deleteCommentsAtObject($objectType, $objectId);
+	public function deleteCommentsAtObject($objectType, $objectId): bool;
 
 	/**
 	 * sets the read marker for a given file to the specified date for the
@@ -388,7 +346,7 @@ interface ICommentsManager {
 	 * @param \OCP\IUser $user
 	 * @since 9.0.0
 	 */
-	public function setReadMark($objectType, $objectId, \DateTime $dateTime, \OCP\IUser $user);
+	public function setReadMark($objectType, $objectId, \DateTime $dateTime, \OCP\IUser $user): void;
 
 	/**
 	 * returns the read marker for a given file to the specified date for the
@@ -401,7 +359,7 @@ interface ICommentsManager {
 	 * @return \DateTime|null
 	 * @since 9.0.0
 	 */
-	public function getReadMark($objectType, $objectId, \OCP\IUser $user);
+	public function getReadMark($objectType, $objectId, \OCP\IUser $user): ?\DateTime;
 
 	/**
 	 * deletes the read markers for the specified user
@@ -410,7 +368,7 @@ interface ICommentsManager {
 	 * @return bool
 	 * @since 9.0.0
 	 */
-	public function deleteReadMarksFromUser(\OCP\IUser $user);
+	public function deleteReadMarksFromUser(\OCP\IUser $user): bool;
 
 	/**
 	 * deletes the read markers on the specified object
@@ -420,16 +378,16 @@ interface ICommentsManager {
 	 * @return bool
 	 * @since 9.0.0
 	 */
-	public function deleteReadMarksOnObject($objectType, $objectId);
+	public function deleteReadMarksOnObject($objectType, $objectId): bool;
 
 	/**
-	 * registers an Entity to the manager, so event notifications can be send
+	 * registers an Entity to the manager, so event notifications can be sent
 	 * to consumers of the comments infrastructure
 	 *
 	 * @param \Closure $closure
 	 * @since 11.0.0
 	 */
-	public function registerEventHandler(\Closure $closure);
+	public function registerEventHandler(\Closure $closure): void;
 
 	/**
 	 * registers a method that resolves an ID to a display name for a given type
@@ -439,10 +397,10 @@ interface ICommentsManager {
 	 * @throws \OutOfBoundsException
 	 * @since 11.0.0
 	 *
-	 * Only one resolver shall be registered per type. Otherwise a
-	 * \OutOfBoundsException has to thrown.
+	 * Only one resolver shall be registered per type. Otherwise, a
+	 * \OutOfBoundsException has to be thrown.
 	 */
-	public function registerDisplayNameResolver($type, \Closure $closure);
+	public function registerDisplayNameResolver($type, \Closure $closure): void;
 
 	/**
 	 * resolves a given ID of a given Type to a display name.
@@ -457,7 +415,7 @@ interface ICommentsManager {
 	 * be thrown. It is upon the resolver discretion what to return of the
 	 * provided ID is unknown. It must be ensured that a string is returned.
 	 */
-	public function resolveDisplayName($type, $id);
+	public function resolveDisplayName($type, $id): string;
 
 	/**
 	 * Load the Comments app into the page

lib/public/Comments/ICommentsManagerFactory.php

@@ -16,7 +16,9 @@ use OCP\IServerContainer;
  * instance.
  *
  * @since 9.0.0
+ * @deprecated 32.0.0 It is no longer supported to store the comments in another location
  */
+#[\Deprecated('It is no longer supported to store the comments in another location', '32.0.0')]
 interface ICommentsManagerFactory {
 	/**
 	 * Constructor for the comments manager factory

lib/public/Comments/IllegalIDChangeException.php

@@ -7,9 +7,13 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Catchable;
+
 /**
  * Exception for illegal attempts to modify a comment ID
+ *
  * @since 9.0.0
  */
+#[Catchable('9.0.0')]
 class IllegalIDChangeException extends \Exception {
 }

lib/public/Comments/MessageTooLongException.php

@@ -7,9 +7,13 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Catchable;
+
 /**
  * Exception thrown when a comment message exceeds the allowed character limit
+ *
  * @since 9.0.0
  */
+#[Catchable('9.0.0')]
 class MessageTooLongException extends \OverflowException {
 }

lib/public/Comments/NotFoundException.php

@@ -7,9 +7,13 @@
  */
 namespace OCP\Comments;
 
+use OCP\AppFramework\Attribute\Catchable;
+
 /**
  * Exception for not found entity
+ *
  * @since 9.0.0
  */
+#[Catchable('9.0.0')]
 class NotFoundException extends \Exception {
 }

tests/lib/Comments/FakeManager.php

@@ -31,18 +31,6 @@ class FakeManager implements ICommentsManager {
 	) {
 	}
 
-	public function getForObjectSince(
-		string $objectType,
-		string $objectId,
-		int $lastKnownCommentId,
-		string $sortDirection = 'asc',
-		int $limit = 30,
-		bool $includeLastKnown = false,
-		string $topmostParentId = '',
-	): array {
-		return [];
-	}
-
 	public function getCommentsWithVerbForObjectSinceComment(
 		string $objectType,
 		string $objectId,
@@ -115,9 +103,6 @@ class FakeManager implements ICommentsManager {
 	public function resolveDisplayName($type, $id) {
 	}
 
-	public function getNumberOfUnreadCommentsForFolder($folderId, IUser $user) {
-	}
-
 	public function getNumberOfUnreadCommentsForObjects(string $objectType, array $objectIds, IUser $user, $verb = ''): array {
 		return [];
 	}
@@ -133,10 +118,6 @@ class FakeManager implements ICommentsManager {
 		return [];
 	}
 
-	public function getNumberOfCommentsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, string $verb = ''): int {
-		return 0;
-	}
-
 	public function getNumberOfCommentsWithVerbsForObjectSinceComment(string $objectType, string $objectId, int $lastRead, array $verbs): int {
 		return 0;
 	}