Add annotations for controllers

Signed-off-by: jld3103 <jld3103yt@gmail.com>

lib/Controller/APIController.php

@@ -60,10 +60,16 @@ public function __construct(
 	}
 
 	/**
-	 * @param string $userId
-	 * @param string $shortMessage
-	 * @param string $longMessage
-	 * @return DataResponse
+	 * Generate a notification for a user
+	 *
+	 * @param string $userId ID of the user
+	 * @param string $shortMessage Subject of the notification
+	 * @param string $longMessage Message of the notification
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, null, array{}>
+	 *
+	 * 200: Notification generated successfully
+	 * 400: Generating notification is not possible
+	 * 404: User not found
 	 */
 	public function generateNotification(string $userId, string $shortMessage, string $longMessage = ''): DataResponse {
 		$user = $this->userManager->get($userId);

lib/Controller/EndpointController.php

@@ -29,6 +29,7 @@
 use OCA\Notifications\Exceptions\NotificationNotFoundException;
 use OCA\Notifications\Handler;
 use OCA\Notifications\Push;
+use OCA\Notifications\ResponseDefinitions;
 use OCA\Notifications\Service\ClientService;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
@@ -44,6 +45,10 @@
 use OCP\UserStatus\IManager as IUserStatusManager;
 use OCP\UserStatus\IUserStatus;
 
+/**
+ * @psalm-import-type NotificationsNotification from ResponseDefinitions
+ * @psalm-import-type NotificationsNotificationAction from ResponseDefinitions
+ */
 class EndpointController extends OCSController {
 	public function __construct(
 		string $appName,
@@ -64,8 +69,13 @@ public function __construct(
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
-	 * @param string $apiVersion
-	 * @return DataResponse
+	 * Get all notifications
+	 *
+	 * @param string $apiVersion Version of the API to use
+	 * @return DataResponse<Http::STATUS_OK, NotificationsNotification[], array{'X-Nextcloud-User-Status': string}>|DataResponse<Http::STATUS_NO_CONTENT, null, array{X-Nextcloud-User-Status: string}>
+	 *
+	 * 200: Notifications returned
+	 * 204: No app uses notifications
 	 */
 	public function listNotifications(string $apiVersion): DataResponse {
 		$userStatus = $this->userStatusManager->getUserStatuses([
@@ -131,9 +141,14 @@ public function listNotifications(string $apiVersion): DataResponse {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
-	 * @param string $apiVersion
-	 * @param int $id
-	 * @return DataResponse
+	 * Get a notification
+	 *
+	 * @param string $apiVersion Version of the API to use
+	 * @param int $id ID of the notification
+	 * @return DataResponse<Http::STATUS_OK, NotificationsNotification, array{}>|DataResponse<Http::STATUS_NOT_FOUND, null, array{}>
+	 *
+	 * 200: Notification returned
+	 * 404: Notification not found
 	 */
 	public function getNotification(string $apiVersion, int $id): DataResponse {
 		if (!$this->manager->hasNotifiers()) {
@@ -174,9 +189,14 @@ public function getNotification(string $apiVersion, int $id): DataResponse {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $apiVersion
-	 * @param int[] $ids
-	 * @return DataResponse
+	 * Check if notification IDs exist
+	 *
+	 * @param string $apiVersion Version of the API to use
+	 * @param int[] $ids IDs of the notifications to check
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST, int[], array{}>
+	 *
+	 * 200: Existing nsotification IDs returned
+	 * 400: Too many notification IDs requested
 	 */
 	public function confirmIdsForUser(string $apiVersion, array $ids): DataResponse {
 		if (!$this->manager->hasNotifiers()) {
@@ -203,8 +223,14 @@ public function confirmIdsForUser(string $apiVersion, array $ids): DataResponse
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param int $id
-	 * @return DataResponse
+	 * Delete a notification
+	 *
+	 * @param int $id ID of the notification
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, null, array{}>
+	 *
+	 * 200: Notification deleted successfully
+	 * 403: Deleting notification for impersonated user is not allowed
+	 * 404: Notification not found
 	 */
 	public function deleteNotification(int $id): DataResponse {
 		if ($id === 0) {
@@ -231,7 +257,12 @@ public function deleteNotification(int $id): DataResponse {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * Delete all notifications
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_FORBIDDEN, null, array{}>
+	 *
+	 * 200: All notifications deleted successfully
+	 * 403: Deleting notification for impersonated user is not allowed
 	 */
 	public function deleteAllNotifications(): DataResponse {
 		if ($this->session->getImpersonatingUserID() !== null) {
@@ -267,7 +298,7 @@ protected function generateETag(array $notifications): string {
 	 * @param INotification $notification
 	 * @param string $apiVersion
 	 * @param bool $hasActiveTalkDesktop
-	 * @return array
+	 * @return NotificationsNotification
 	 */
 	protected function notificationToArray(int $notificationId, INotification $notification, string $apiVersion, bool $hasActiveTalkDesktop = false): array {
 		$data = [
@@ -309,7 +340,7 @@ protected function notificationToArray(int $notificationId, INotification $notif
 
 	/**
 	 * @param IAction $action
-	 * @return array
+	 * @return NotificationsNotificationAction
 	 */
 	protected function actionToArray(IAction $action): array {
 		return [

lib/Controller/PushController.php

@@ -30,6 +30,7 @@
 use OC\Authentication\Token\IProvider;
 use OC\Authentication\Token\IToken;
 use OC\Security\IdentityProof\Manager;
+use OCA\Notifications\ResponseDefinitions;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -40,6 +41,9 @@
 use OCP\IUser;
 use OCP\IUserSession;
 
+/**
+ * @psalm-import-type NotificationsPushDevice from ResponseDefinitions
+ */
 class PushController extends OCSController {
 	/** @var IDBConnection */
 	private $db;
@@ -75,10 +79,17 @@ public function __construct(string $appName,
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $pushTokenHash
-	 * @param string $devicePublicKey
-	 * @param string $proxyServer
-	 * @return DataResponse
+	 * Register device for push notifications
+	 *
+	 * @param string $pushTokenHash Hash of the push token
+	 * @param string $devicePublicKey Public key of the device
+	 * @param string $proxyServer Proxy server to be used
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_CREATED, NotificationsPushDevice, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{message: string}, array{}>|DataResponse<Http::STATUS_UNAUTHORIZED, array<empty>, array{}>
+	 *
+	 * 200: Device was already registered
+	 * 201: Device registered successfully
+	 * 400: Registering device is not possible
+	 * 401: Missing permissions to register device
 	 */
 	public function registerDevice(string $pushTokenHash, string $devicePublicKey, string $proxyServer): DataResponse {
 		$user = $this->userSession->getUser();
@@ -152,7 +163,14 @@ public function registerDevice(string $pushTokenHash, string $devicePublicKey, s
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * Remove a device from push notifications
+	 *
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_ACCEPTED|Http::STATUS_UNAUTHORIZED, array<empty>, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{message: string}, array{}>
+	 *
+	 * 200: No device registered
+	 * 202: Device removed successfully
+	 * 400: Removing device is not possible
+	 * 401: Missing permissions to remove device
 	 */
 	public function removeDevice(): DataResponse {
 		$user = $this->userSession->getUser();

lib/Controller/SettingsController.php

@@ -28,6 +28,7 @@
 
 use OCA\Notifications\AppInfo\Application;
 use OCA\Notifications\Model\SettingsMapper;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IConfig;
@@ -51,6 +52,13 @@ public function __construct(string $appName,
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Update personal notification settings
+	 *
+	 * @param int $batchSetting How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)
+	 * @param string $soundNotification Enable sound for notifications ('yes' or 'no')
+	 * @param string $soundTalk Enable sound for Talk notifications ('yes' or 'no')
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 */
 	public function personal(int $batchSetting, string $soundNotification, string $soundTalk): DataResponse {
 		$this->settingsMapper->setBatchSettingForUser($this->userId, $batchSetting);
@@ -63,6 +71,13 @@ public function personal(int $batchSetting, string $soundNotification, string $s
 
 	/**
 	 * @AuthorizedAdminSetting(settings=OCA\Notifications\Settings\Admin)
+	 *
+	 * Update default notification settings for new users
+	 *
+	 * @param int $batchSetting How often E-mails about missed notifications should be sent (hourly: 1; every three hours: 2; daily: 3; weekly: 4)
+	 * @param string $soundNotification Enable sound for notifications ('yes' or 'no')
+	 * @param string $soundTalk Enable sound for Talk notifications ('yes' or 'no')
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 */
 	public function admin(int $batchSetting, string $soundNotification, string $soundTalk): DataResponse {
 		$this->config->setAppValue(Application::APP_ID, 'setting_batchtime', (string) $batchSetting);

lib/ResponseDefinitions.php

@@ -0,0 +1,62 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\Notifications;
+
+/**
+ * @psalm-type NotificationsNotificationAction = array{
+ *     label: string,
+ *     link: string,
+ *     type: string,
+ *     primary: bool,
+ * }
+ *
+ * @psalm-type NotificationsNotification = array{
+ *     notification_id: int,
+ *     app: string,
+ *     user: string,
+ *     datetime: string,
+ *     object_type: string,
+ *     object_id: string,
+ *     subject: string,
+ *     message: string,
+ *     link: string,
+ *     actions: NotificationsNotificationAction[],
+ *     subjectRich?: string,
+ *     subjectRichParameters?: array<string, mixed>,
+ *     messageRich?: string,
+ *     messageRichParameters?: array<string, mixed>,
+ *     icon?: string,
+ *     shouldNotify?: bool,
+ * }
+ *
+ * @psalm-type NotificationsPushDevice = array{
+ *     publicKey: string,
+ *     deviceIdentifier: string,
+ *     signature: string,
+ * }
+ */
+class ResponseDefinitions {
+}