Merge pull request #56032 from nextcloud/carl/share-manager-correct-return-type

refactor(share-manager): Make return type more precise

Author: kesselb

lib/private/Share20/Manager.php

@@ -1600,54 +1600,7 @@ public function userDeletedFromGroup($uid, $gid) {
 		}
 	}
 
-	/**
-	 * Get access list to a path. This means
-	 * all the users that can access a given path.
-	 *
-	 * Consider:
-	 * -root
-	 * |-folder1 (23)
-	 *  |-folder2 (32)
-	 *   |-fileA (42)
-	 *
-	 * fileA is shared with user1 and user1@server1 and email1@maildomain1
-	 * folder2 is shared with group2 (user4 is a member of group2)
-	 * folder1 is shared with user2 (renamed to "folder (1)") and user2@server2
-	 *                        and email2@maildomain2
-	 *
-	 * Then the access list to '/folder1/folder2/fileA' with $currentAccess is:
-	 * [
-	 *  users  => [
-	 *      'user1' => ['node_id' => 42, 'node_path' => '/fileA'],
-	 *      'user4' => ['node_id' => 32, 'node_path' => '/folder2'],
-	 *      'user2' => ['node_id' => 23, 'node_path' => '/folder (1)'],
-	 *  ],
-	 *  remote => [
-	 *      'user1@server1' => ['node_id' => 42, 'token' => 'SeCr3t'],
-	 *      'user2@server2' => ['node_id' => 23, 'token' => 'FooBaR'],
-	 *  ],
-	 *  public => bool
-	 *  mail => [
-	 *      'email1@maildomain1' => ['node_id' => 42, 'token' => 'aBcDeFg'],
-	 *      'email2@maildomain2' => ['node_id' => 23, 'token' => 'hIjKlMn'],
-	 *  ]
-	 * ]
-	 *
-	 * The access list to '/folder1/folder2/fileA' **without** $currentAccess is:
-	 * [
-	 *  users  => ['user1', 'user2', 'user4'],
-	 *  remote => bool,
-	 *  public => bool
-	 *  mail => ['email1@maildomain1', 'email2@maildomain2']
-	 * ]
-	 *
-	 * This is required for encryption/activity
-	 *
-	 * @param \OCP\Files\Node $path
-	 * @param bool $recursive Should we check all parent folders as well
-	 * @param bool $currentAccess Ensure the recipient has access to the file (e.g. did not unshare it)
-	 * @return array
-	 */
+	#[\Override]
 	public function getAccessList(\OCP\Files\Node $path, $recursive = true, $currentAccess = false) {
 		$owner = $path->getOwner();
 

lib/public/Share/IManager.php

@@ -273,8 +273,15 @@ public function userDeletedFromGroup($uid, $gid);
 	 * @param \OCP\Files\Node $path
 	 * @param bool $recursive Should we check all parent folders as well
 	 * @param bool $currentAccess Should the user have currently access to the file
-	 * @return array
-	 * @since 12
+	 * @return ($currentAccess is true
+	 * 		? array{
+	 *     		users?: array<string, array{node_id: int, node_path: string}>,
+	 *     		remote?: array<string, array{node_id: int, node_path: string}>,
+	 *     		public?: bool,
+	 *     		mail?: array<string, array{node_id: int, node_path: string}>
+	 *     	}
+	 *      : array{users?: list<string>, remote?: bool, public?: bool, mail?: list<string>})
+	 * @since 12.0.0
 	 */
 	public function getAccessList(\OCP\Files\Node $path, $recursive = true, $currentAccess = false);
 
@@ -545,9 +552,9 @@ public function registerShareProvider(string $shareProviderClass): void;
 	 *
 	 * Get all the shares as iterable to reduce memory overhead
 	 * Note, since this opens up database cursors the iterable should
-	 * be fully itterated.
+	 * be fully iterated.
 	 *
-	 * @return iterable
+	 * @return iterable<IShare>
 	 * @since 18.0.0
 	 */
 	public function getAllShares(): iterable;