From e5f8acf4c003bbdd839095475cffe8b175ea4c43 Mon Sep 17 00:00:00 2001 From: Robin Appelman Date: Thu, 21 Mar 2013 13:07:29 +0100 Subject: [PATCH] Add phpdoc documentation to the Storage interface --- lib/files/storage/storage.php | 269 ++++++++++++++++++++++++++++++++-- 1 file changed, 255 insertions(+), 14 deletions(-) diff --git a/lib/files/storage/storage.php b/lib/files/storage/storage.php index 2cc835236ba..543cfa8f79d 100644 --- a/lib/files/storage/storage.php +++ b/lib/files/storage/storage.php @@ -11,72 +11,313 @@ namespace OC\Files\Storage; /** * Provide a common interface to all different storage options */ -interface Storage{ +interface Storage { + /** + * $parameters is a free form array with the configuration options needed to construct the storage + * + * @param array $parameters + */ public function __construct($parameters); + + /** + * Get the identifier for the storage, + * the returned id should be the same for every storage object that is created with the same parameters + * and two storage objects with the same id should refer to two storages that display the same files. + * + * @return string + */ public function getId(); + + /** + * see http://php.net/manual/en/function.mkdir.php + * + * @param string $path + * @return bool + */ public function mkdir($path); + + /** + * see http://php.net/manual/en/function.rmdir.php + * + * @param string $path + * @return bool + */ public function rmdir($path); + + /** + * see http://php.net/manual/en/function.opendir.php + * + * @param string $path + * @return resource + */ public function opendir($path); + + /** + * see http://php.net/manual/en/function.is_dir.php + * + * @param string $path + * @return bool + */ public function is_dir($path); + + /** + * see http://php.net/manual/en/function.is_file.php + * + * @param string $path + * @return bool + */ public function is_file($path); + + /** + * see http://php.net/manual/en/function.stat.php + * only the following keys are required in the result: size and mtime + * + * @param string $path + * @return array + */ public function stat($path); + + /** + * see http://php.net/manual/en/function.filetype.php + * + * @param string $path + * @return bool + */ public function filetype($path); + + /** + * see http://php.net/manual/en/function.filesize.php + * The result for filesize when called on a folder is required to be 0 + * + * @param string $path + * @return int + */ public function filesize($path); + + /** + * check if a file can be created in $path + * + * @param string $path + * @return bool + */ public function isCreatable($path); + + /** + * check if a file can be read + * + * @param string $path + * @return bool + */ public function isReadable($path); + + /** + * check if a file can be written to + * + * @param string $path + * @return bool + */ public function isUpdatable($path); + + /** + * check if a file can be deleted + * + * @param string $path + * @return bool + */ public function isDeletable($path); + + /** + * check if a file can be shared + * + * @param string $path + * @return bool + */ public function isSharable($path); + + /** + * get the full permissions of a path. + * Should return a combination of the PERMISSION_ constants defined in lib/public/constants.php + * + * @param string $path + * @return int + */ public function getPermissions($path); + + /** + * see http://php.net/manual/en/function.file_exists.php + * + * @param string $path + * @return bool + */ public function file_exists($path); + + /** + * see http://php.net/manual/en/function.filemtime.php + * + * @param string $path + * @return int + */ public function filemtime($path); + + /** + * see http://php.net/manual/en/function.file_get_contents.php + * + * @param string $path + * @return string + */ public function file_get_contents($path); - public function file_put_contents($path,$data); + + /** + * see http://php.net/manual/en/function.file_put_contents.php + * + * @param string $path + * @param string $data + * @return bool + */ + public function file_put_contents($path, $data); + + /** + * see http://php.net/manual/en/function.unlink.php + * + * @param string $path + * @return bool + */ public function unlink($path); - public function rename($path1,$path2); - public function copy($path1,$path2); - public function fopen($path,$mode); + + /** + * see http://php.net/manual/en/function.rename.php + * + * @param string $path1 + * @param string $path2 + * @return bool + */ + public function rename($path1, $path2); + + /** + * see http://php.net/manual/en/function.copy.php + * + * @param string $path1 + * @param string $path2 + * @return bool + */ + public function copy($path1, $path2); + + /** + * see http://php.net/manual/en/function.fopen.php + * + * @param string $path + * @param string $mode + * @return resource + */ + public function fopen($path, $mode); + + /** + * get the mimetype for a file or folder + * The mimetype for a folder is required to be "httpd/unix-directory" + * + * @param string $path + * @return string + */ public function getMimeType($path); - public function hash($type,$path,$raw = false); + + /** + * see http://php.net/manual/en/function.hash.php + * + * @param string $type + * @param string $path + * @param bool $raw + * @return string + */ + public function hash($type, $path, $raw = false); + + /** + * see http://php.net/manual/en/function.free_space.php + * + * @param string $path + * @return int + */ public function free_space($path); + + /** + * search for occurrences of $query in file names + * + * @param string $query + * @return array + */ public function search($query); - public function touch($path, $mtime=null); - public function getLocalFile($path);// get a path to a local version of the file, whether the original file is local or remote - public function getLocalFolder($path);// get a path to a local version of the folder, whether the original file is local or remote + + /** + * see http://php.net/manual/en/function.touch.php + * If the backend does not support the operation, false should be returned + * + * @param string $path + * @param int $mtime + * @return bool + */ + public function touch($path, $mtime = null); + + /** + * get the path to a local version of the file. + * The local version of the file can be temporary and doesn't have to be persistent across requests + * + * @param string $path + * @return string + */ + public function getLocalFile($path); + + /** + * get the path to a local version of the folder. + * The local version of the folder can be temporary and doesn't have to be persistent across requests + * + * @param string $path + * @return string + */ + public function getLocalFolder($path); /** * check if a file or folder has been updated since $time + * + * @param string $path * @param int $time * @return bool * * hasUpdated for folders should return at least true if a file inside the folder is add, removed or renamed. * returning true for other changes in the folder is optional */ - public function hasUpdated($path,$time); + public function hasUpdated($path, $time); /** + * get a cache instance for the storage + * * @param string $path * @return \OC\Files\Cache\Cache */ - public function getCache($path=''); + public function getCache($path = ''); + /** + * get a scanner instance for the storage + * * @param string $path * @return \OC\Files\Cache\Scanner */ - public function getScanner($path=''); + public function getScanner($path = ''); public function getOwner($path); /** + * get a permissions cache instance for the cache + * * @param string $path * @return \OC\Files\Cache\Permissions */ - public function getPermissionsCache($path=''); + public function getPermissionsCache($path = ''); /** + * get a watcher instance for the cache + * * @param string $path * @return \OC\Files\Cache\Watcher */ - public function getWatcher($path=''); + public function getWatcher($path = ''); /** * get the ETag for a file or folder -- 2.39.5