Improve api documentation for file sharing external storage

Signed-off-by: Carl Schwan <carl@carlschwan.eu>

diff --git a/apps/files_sharing/lib/External/Storage.php b/apps/files_sharing/lib/External/Storage.php
index 67df60cb55f659c6ae5614157b13326376739a24..23e5ac3ea267c477daaff54e37b894039ee9a795 100644 (file)
--- a/apps/files_sharing/lib/External/Storage.php
+++ b/apps/files_sharing/lib/External/Storage.php
@@ -37,6 +37,7 @@ use GuzzleHttp\Exception\RequestException;
 use OC\Files\Storage\DAV;
 use OC\ForbiddenException;
 use OCA\Files_Sharing\ISharedStorage;
+use OCA\Files_Sharing\External\Manager as ExternalShareManager;
 use OCP\AppFramework\Http;
 use OCP\Constants;
 use OCP\Federation\ICloudId;
@@ -45,6 +46,7 @@ use OCP\Files\Storage\IDisableEncryptionStorage;
 use OCP\Files\StorageInvalidException;
 use OCP\Files\StorageNotAvailableException;
 use OCP\Http\Client\LocalServerException;
+use OCP\Http\Client\IClientService;
 
 class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        /** @var ICloudId */
@@ -60,11 +62,12 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        /** @var bool */
        private $updateChecked = false;
 
-       /**
-        * @var \OCA\Files_Sharing\External\Manager
-        */
+       /** @var ExternalShareManager */
        private $manager;
 
+       /**
+        * @param array{HttpClientService: IClientService, manager: ExternalShareManager, cloudId: ICloudId, mountpoint: string, token: string, password: ?string}|array $options
+        */
        public function __construct($options) {
                $this->memcacheFactory = \OC::$server->getMemCacheFactory();
                $this->httpClient = $options['HttpClientService'];
@@ -107,28 +110,28 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
                return $this->watcher;
        }
 
-       public function getRemoteUser() {
+       public function getRemoteUser(): string {
                return $this->cloudId->getUser();
        }
 
-       public function getRemote() {
+       public function getRemote(): string {
                return $this->cloudId->getRemote();
        }
 
-       public function getMountPoint() {
+       public function getMountPoint(): string {
                return $this->mountPoint;
        }
 
-       public function getToken() {
+       public function getToken(): string {
                return $this->token;
        }
 
-       public function getPassword() {
+       public function getPassword(): ?string {
                return $this->password;
        }
 
        /**
-        * @brief get id of the mount point
+        * Get id of the mount point.
         * @return string
         */
        public function getId() {
@@ -158,7 +161,7 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        }
 
        /**
-        * check if a file or folder has been updated since $time
+        * Check if a file or folder has been updated since $time
         *
         * @param string $path
         * @param int $time
@@ -247,11 +250,11 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        }
 
        /**
-        * check if the configured remote is a valid federated share provider
+        * Check if the configured remote is a valid federated share provider
         *
         * @return bool
         */
-       protected function testRemote() {
+       protected function testRemote(): bool {
                try {
                        return $this->testRemoteUrl($this->getRemote() . '/ocs-provider/index.php')
                                || $this->testRemoteUrl($this->getRemote() . '/ocs-provider/')
@@ -261,11 +264,7 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
                }
        }
 
-       /**
-        * @param string $url
-        * @return bool
-        */
-       private function testRemoteUrl($url) {
+       private function testRemoteUrl(string $url): bool {
                $cache = $this->memcacheFactory->createDistributed('files_sharing_remote_url');
                if ($cache->hasKey($url)) {
                        return (bool)$cache->get($url);
@@ -292,12 +291,12 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        }
 
        /**
-        * Whether the remote is an ownCloud/Nextcloud, used since some sharing features are not
-        * standardized. Let's use this to detect whether to use it.
+        * Check whether the remote is an ownCloud/Nextcloud. This is needed since some sharing
+        * features are not standardized.
         *
-        * @return bool
+        * @throws LocalServerException
         */
-       public function remoteIsOwnCloud() {
+       public function remoteIsOwnCloud(): bool {
                if (defined('PHPUNIT_RUN') || !$this->testRemoteUrl($this->getRemote() . '/status.php')) {
                        return false;
                }
@@ -385,13 +384,13 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        }
 
        /**
-        * translate OCM Permissions to Nextcloud permissions
+        * Translate OCM Permissions to Nextcloud permissions
         *
         * @param string $ocmPermissions json encoded OCM permissions
         * @param string $path path to file
         * @return int
         */
-       protected function ocmPermissions2ncPermissions($ocmPermissions, $path) {
+       protected function ocmPermissions2ncPermissions(string $ocmPermissions, string $path): int {
                try {
                        $ocmPermissions = json_decode($ocmPermissions);
                        $ncPermissions = 0;
@@ -418,12 +417,9 @@ class Storage extends DAV implements ISharedStorage, IDisableEncryptionStorage {
        }
 
        /**
-        * calculate default permissions in case no permissions are provided
-        *
-        * @param $path
-        * @return int
+        * Calculate the default permissions in case no permissions are provided
         */
-       protected function getDefaultPermissions($path) {
+       protected function getDefaultPermissions(string $path): int {
                if ($this->is_dir($path)) {
                        $permissions = Constants::PERMISSION_ALL;
                } else {

diff --git a/build/psalm-baseline.xml b/build/psalm-baseline.xml
index 409d35a9aad1ed7d296f51c6a18a60c24b5dc200..8235488b74680db8dffe87813986695184c3e1b6 100644 (file)
--- a/build/psalm-baseline.xml
+++ b/build/psalm-baseline.xml
@@ -2200,9 +2200,6 @@
       <code>registerProvider</code>
     </UndefinedInterfaceMethod>
   </file>
-  <file src="apps/user_status/lib/Db/UserStatusMapper.php">
-    <MoreSpecificImplementedParamType occurrences="1"/>
-  </file>
   <file src="apps/workflowengine/lib/Check/AbstractStringCheck.php">
     <NullArgument occurrences="1">
       <code>null</code>