Fix PHPDoc in files_external, add missing tag

Fix various PHPDoc issues in external storage app.

Added missing NoAdminRequired tag

apps/files_external/appinfo/routes.php

@@ -23,9 +23,8 @@
 namespace OCA\Files_External\Appinfo;
 
 /**
- * @var $this OC\Route\Router
+ * @var $this \OC\Route\Router
  **/
-
 $application = new Application();
 $application->registerRoutes(
 	$this,

apps/files_external/controller/globalstoragescontroller.php

@@ -23,6 +23,9 @@ use \OCA\Files_external\Service\GlobalStoragesService;
 use \OCA\Files_external\NotFoundException;
 use \OCA\Files_external\Lib\StorageConfig;
 
+/**
+ * Global storages controller
+ */
 class GlobalStoragesController extends StoragesController {
 	/**
 	 * Creates a new global storages controller.
@@ -37,7 +40,7 @@ class GlobalStoragesController extends StoragesController {
 		IRequest $request,
 		IL10N $l10n,
 		GlobalStoragesService $globalStoragesService
-	){
+	) {
 		parent::__construct(
 			$AppName,
 			$request,
@@ -151,4 +154,3 @@ class GlobalStoragesController extends StoragesController {
 	}
 
 }
-

apps/files_external/controller/storagescontroller.php

@@ -23,14 +23,21 @@ use \OCA\Files_external\Service\StoragesService;
 use \OCA\Files_external\NotFoundException;
 use \OCA\Files_external\Lib\StorageConfig;
 
+/**
+ * Base class for storages controllers
+ */
 abstract class StoragesController extends Controller {
 
 	/**
+	 * L10N service
+	 *
 	 * @var IL10N
 	 */
 	protected $l10n;
 
 	/**
+	 * Storages service
+	 *
 	 * @var StoragesService
 	 */
 	protected $service;
@@ -48,7 +55,7 @@ abstract class StoragesController extends Controller {
 		IRequest $request,
 		IL10N $l10n,
 		StoragesService $storagesService
-	){
+	) {
 		parent::__construct($AppName, $request);
 		$this->l10n = $l10n;
 		$this->service = $storagesService;
@@ -94,7 +101,7 @@ abstract class StoragesController extends Controller {
 	 * Note that this operation can be time consuming depending
 	 * on whether the remote storage is available or not.
 	 *
-	 * @param StorageConfig $storage
+	 * @param StorageConfig $storage storage configuration
 	 */
 	protected function updateStorageStatus(StorageConfig &$storage) {
 		// update status (can be time-consuming)

apps/files_external/controller/userstoragescontroller.php

@@ -23,6 +23,9 @@ use \OCA\Files_external\Service\UserStoragesService;
 use \OCA\Files_external\NotFoundException;
 use \OCA\Files_external\Lib\StorageConfig;
 
+/**
+ * User storages controller
+ */
 class UserStoragesController extends StoragesController {
 	/**
 	 * Creates a new user storages controller.
@@ -37,7 +40,7 @@ class UserStoragesController extends StoragesController {
 		IRequest $request,
 		IL10N $l10n,
 		UserStoragesService $userStoragesService
-	){
+	) {
 		parent::__construct(
 			$AppName,
 			$request,
@@ -76,8 +79,11 @@ class UserStoragesController extends StoragesController {
 	}
 
 	/**
+	 * Return storage
+	 *
 	 * @NoAdminRequired
-	 * @{inheritdoc}
+	 *
+	 * {@inheritdoc}
 	 */
 	public function show($id) {
 		return parent::show($id);
@@ -131,6 +137,8 @@ class UserStoragesController extends StoragesController {
 	 * @param array $mountOptions backend-specific mount options
 	 *
 	 * @return DataResponse
+	 *
+	 * @NoAdminRequired
 	 */
 	public function update(
 		$id,
@@ -171,11 +179,13 @@ class UserStoragesController extends StoragesController {
 	}
 
 	/**
-	 * {@inheritdoc}
+	 * Delete storage
+	 *
 	 * @NoAdminRequired
+	 *
+	 * {@inheritdoc}
 	 */
 	public function destroy($id) {
 		return parent::destroy($id);
 	}
 }
-

apps/files_external/lib/storageconfig.php

@@ -14,51 +14,71 @@ namespace OCA\Files_external\Lib;
 class StorageConfig implements \JsonSerializable {
 
 	/**
+	 * Storage config id
+	 *
 	 * @var int
 	 */
 	private $id;
 
 	/**
+	 * Backend class name
+	 *
 	 * @var string
 	 */
 	private $backendClass;
 
 	/**
+	 * Backend options
+	 *
 	 * @var array
 	 */
 	private $backendOptions = [];
 
 	/**
+	 * Mount point path, relative to the user's "files" folder
+	 *
 	 * @var string
 	 */
 	private $mountPoint;
 
 	/**
+	 * Storage status
+	 *
 	 * @var int
 	 */
 	private $status;
 
 	/**
+	 * Priority
+	 *
 	 * @var int
 	 */
 	private $priority;
 
 	/**
+	 * List of users who have access to this storage
+	 *
 	 * @var array
 	 */
 	private $applicableUsers = [];
 
 	/**
+	 * List of groups that have access to this storage
+	 *
 	 * @var array
 	 */
 	private $applicableGroups = [];
 
 	/**
+	 * Mount-specific options
+	 *
 	 * @var array
 	 */
 	private $mountOptions = [];
 
 	/**
+	 * Creates a storage config
+	 *
 	 * @param int|null $id config id or null for a new config
 	 */
 	public function __construct($id = null) {
@@ -77,7 +97,7 @@ class StorageConfig implements \JsonSerializable {
 	/**
 	 * Sets the configuration id
 	 *
-	 * @param int configuration id
+	 * @param int $id configuration id
 	 */
 	public function setId($id) {
 		$this->id = $id;
@@ -98,7 +118,7 @@ class StorageConfig implements \JsonSerializable {
 	 * "files" folder.
 	 * The path will be normalized.
 	 *
-	 * @param string path
+	 * @param string $mountPoint path
 	 */
 	public function setMountPoint($mountPoint) {
 		$this->mountPoint = \OC\Files\Filesystem::normalizePath($mountPoint);
@@ -134,7 +154,7 @@ class StorageConfig implements \JsonSerializable {
 	/**
 	 * Sets the external storage backend-specific options
 	 *
-	 * @param array backend options
+	 * @param array $backendOptions backend options
 	 */
 	public function setBackendOptions($backendOptions) {
 		$this->backendOptions = $backendOptions;
@@ -152,7 +172,7 @@ class StorageConfig implements \JsonSerializable {
 	/**
 	 * Sets the mount priotity
 	 *
-	 * @param int priority
+	 * @param int $priority priority
 	 */
 	public function setPriority($priority) {
 		$this->priority = $priority;
@@ -170,7 +190,7 @@ class StorageConfig implements \JsonSerializable {
 	/**
 	 * Sets the users for which to mount this storage
 	 *
-	 * @param array applicable users
+	 * @param array|null $applicableUsers applicable users
 	 */
 	public function setApplicableUsers($applicableUsers) {
 		if (is_null($applicableUsers)) {
@@ -191,7 +211,7 @@ class StorageConfig implements \JsonSerializable {
 	/**
 	 * Sets the groups for which to mount this storage
 	 *
-	 * @param array applicable groups
+	 * @param array|null $applicableGroups applicable groups
 	 */
 	public function setApplicableGroups($applicableGroups) {
 		if (is_null($applicableGroups)) {
@@ -212,7 +232,7 @@ class StorageConfig implements \JsonSerializable {
 	/**
 	 * Sets the mount-specific options
 	 *
-	 * @param array applicable groups
+	 * @param array $mountOptions applicable groups
 	 */
 	public function setMountOptions($mountOptions) {
 		if (is_null($mountOptions)) {

apps/files_external/service/globalstoragesservice.php

@@ -22,7 +22,6 @@ class GlobalStoragesService extends StoragesService {
 	/**
 	 * Write the storages to the configuration.
 	 *
-	 * @param string $user user or null for global config
 	 * @param array $storages map of storage id to storage config
 	 */
 	public function writeConfig($storages) {
@@ -121,8 +120,8 @@ class GlobalStoragesService extends StoragesService {
 	 * accomodate for additions/deletions in applicableUsers
 	 * and applicableGroups fields.
 	 *
-	 * @param StorageConfig $oldStorage old storage data
+	 * @param StorageConfig $oldStorage old storage config
-	 * @param StorageConfig $newStorage new storage data
+	 * @param StorageConfig $newStorage new storage config
 	 */
 	protected function triggerChangeHooks(StorageConfig $oldStorage, StorageConfig $newStorage) {
 		// if mount point changed, it's like a deletion + creation

apps/files_external/service/storagesservice.php

@@ -36,9 +36,15 @@ abstract class StoragesService {
 	 * @param string $mountType mount type
 	 * @param string $applicable applicable user or group
 	 * @param array $storageOptions legacy storage options
+	 *
 	 * @return StorageConfig populated storage config
 	 */
-	protected function populateStorageConfigWithLegacyOptions(&$storageConfig, $mountType, $applicable, $storageOptions) {
+	protected function populateStorageConfigWithLegacyOptions(
+		&$storageConfig,
+		$mountType,
+		$applicable,
+		$storageOptions
+	) {
 		$storageConfig->setBackendClass($storageOptions['class']);
 		$storageConfig->setBackendOptions($storageOptions['options']);
 		if (isset($storageOptions['mountOptions'])) {
@@ -225,9 +231,10 @@ abstract class StoragesService {
 	/**
 	 * Get a storage with status
 	 *
-	 * @param int $id
+	 * @param int $id storage id
 	 *
 	 * @return StorageConfig
+	 * @throws NotFoundException if the storage with the given id was not found
 	 */
 	public function getStorage($id) {
 		$allStorages = $this->readConfig();
@@ -319,7 +326,7 @@ abstract class StoragesService {
 	 * @param StorageConfig $updatedStorage storage attributes
 	 *
 	 * @return StorageConfig storage config
-	 * @throws NotFoundException
+	 * @throws NotFoundException if the given storage does not exist in the config
 	 */
 	public function updateStorage(StorageConfig $updatedStorage) {
 		$allStorages = $this->readConfig();
@@ -344,7 +351,7 @@ abstract class StoragesService {
 	 *
 	 * @param int $id storage id
 	 *
-	 * @throws NotFoundException
+	 * @throws NotFoundException if no storage was found with the given id
 	 */
 	public function removeStorage($id) {
 		$allStorages = $this->readConfig();
@@ -376,7 +383,7 @@ abstract class StoragesService {
 		// but so did the mount.json. This horribly hack
 		// will disappear once we move to DB tables to
 		// store the config
-		return max(array_keys($allStorages)) + 1;
+		return (max(array_keys($allStorages)) + 1);
 	}
 
 }

apps/files_external/service/userstoragesservice.php

@@ -19,11 +19,19 @@ use \OCA\Files_external\NotFoundException;
  * (aka personal storages)
  */
 class UserStoragesService extends StoragesService {
+
 	/**
+	 * User session
+	 *
 	 * @var IUserSession
 	 */
 	private $userSession;
 
+	/**
+	 * Create a user storages service
+	 *
+	 * @param IUserSession $userSession user session
+	 */
 	public function __construct(
 		IUserSession $userSession
 	) {