From 9ad7891b4e7ddf1c4420f485c5d3cf4477835087 Mon Sep 17 00:00:00 2001
From: Robin Appelman <icewind@owncloud.com>
Date: Tue, 10 Sep 2013 20:02:15 +0200
Subject: [PATCH] improve phpdoc for the public files interface
---
lib/files/exceptions.php | 21 ------------
lib/public/files/file.php | 19 ++++++++---
lib/public/files/folder.php | 51 +++++++++++++++++++----------
lib/public/files/node.php | 65 +++++++++++++++++++++++++++++++++----
4 files changed, 105 insertions(+), 51 deletions(-)
delete mode 100644 lib/files/exceptions.php
diff --git a/lib/files/exceptions.php b/lib/files/exceptions.php
deleted file mode 100644
index 8a3c40ab0c..0000000000
--- a/lib/files/exceptions.php
+++ /dev/null
@@ -1,21 +0,0 @@
-<?php
-/**
- * Copyright (c) 2013 Robin Appelman <icewind@owncloud.com>
- * This file is licensed under the Affero General Public License version 3 or
- * later.
- * See the COPYING-README file.
- */
-
-namespace OC\Files;
-
-class NotFoundException extends \Exception {
-}
-
-class NotPermittedException extends \Exception {
-}
-
-class AlreadyExistsException extends \Exception {
-}
-
-class NotEnoughSpaceException extends \Exception {
-}
diff --git a/lib/public/files/file.php b/lib/public/files/file.php
index c571e184ce..916b2edd6c 100644
--- a/lib/public/files/file.php
+++ b/lib/public/files/file.php
@@ -8,34 +8,43 @@
namespace OCP\Files;
-use OC\Files\NotPermittedException;
-
interface File extends Node {
/**
+ * Get the content of the file as string
+ *
* @return string
- * @throws \OC\Files\NotPermittedException
+ * @throws \OCP\Files\NotPermittedException
*/
public function getContent();
/**
+ * Write to the file from string data
+ *
* @param string $data
- * @throws \OC\Files\NotPermittedException
+ * @throws \OCP\Files\NotPermittedException
*/
public function putContent($data);
/**
+ * Get the mimetype of the file
+ *
* @return string
*/
public function getMimeType();
/**
+ * Open the file as stream, resulting resource can be operated as stream like the result from php's own fopen
+ *
* @param string $mode
* @return resource
- * @throws \OC\Files\NotPermittedException
+ * @throws \OCP\Files\NotPermittedException
*/
public function fopen($mode);
/**
+ * Compute the hash of the file
+ * Type of hash is set with $type and can be anything supported by php's hash_file
+ *
* @param string $type
* @param bool $raw
* @return string
diff --git a/lib/public/files/folder.php b/lib/public/files/folder.php
index a8e57f7ae2..da7f20fd36 100644
--- a/lib/public/files/folder.php
+++ b/lib/public/files/folder.php
@@ -8,22 +8,21 @@
namespace OCP\Files;
-use OC\Files\Cache\Cache;
-use OC\Files\Cache\Scanner;
-use OC\Files\NotFoundException;
-use OC\Files\NotPermittedException;
-
interface Folder extends Node {
/**
- * @param string $path path relative to the folder
+ * Get the full path of an item in the folder within owncloud's filesystem
+ *
+ * @param string $path relative path of an item in the folder
* @return string
- * @throws \OC\Files\NotPermittedException
+ * @throws \OCP\Files\NotPermittedException
*/
public function getFullPath($path);
/**
- * @param string $path
- * @throws \OC\Files\NotFoundException
+ * Get the path of an item in the folder relative to the folder
+ *
+ * @param string $path absolute path of an item in the folder
+ * @throws \OCP\Files\NotFoundException
* @return string
*/
public function getRelativePath($path);
@@ -39,7 +38,7 @@ interface Folder extends Node {
/**
* get the content of this directory
*
- * @throws \OC\Files\NotFoundException
+ * @throws \OCP\Files\NotFoundException
* @return \OCP\Files\Node[]
*/
public function getDirectoryListing();
@@ -47,29 +46,35 @@ interface Folder extends Node {
/**
* Get the node at $path
*
- * @param string $path
+ * @param string $path relative path of the file or folder
* @return \OCP\Files\Node
- * @throws \OC\Files\NotFoundException
+ * @throws \OCP\Files\NotFoundException
*/
public function get($path);
/**
- * @param string $path
+ * Check if a file or folder exists in the folder
+ *
+ * @param string $path relative path of the file or folder
* @return bool
*/
public function nodeExists($path);
/**
- * @param string $path
+ * Create a new folder
+ *
+ * @param string $path relative path of the new folder
* @return \OCP\Files\Folder
- * @throws NotPermittedException
+ * @throws \OCP\Files\NotPermittedException
*/
public function newFolder($path);
/**
- * @param string $path
+ * Create a new file
+ *
+ * @param string $path relative path of the new file
* @return \OCP\Files\File
- * @throws NotPermittedException
+ * @throws \OCP\Files\NotPermittedException
*/
public function newFile($path);
@@ -83,6 +88,7 @@ interface Folder extends Node {
/**
* search for files by mimetype
+ * $mimetype can either be a full mimetype (image/png) or a wildcard mimetype (image)
*
* @param string $mimetype
* @return \OCP\Files\Node[]
@@ -90,14 +96,23 @@ interface Folder extends Node {
public function searchByMime($mimetype);
/**
- * @param $id
+ * get a file or folder inside the folder by it's internal id
+ *
+ * @param int $id
* @return \OCP\Files\Node[]
*/
public function getById($id);
+ /**
+ * Get the amount of free space inside the folder
+ *
+ * @return int
+ */
public function getFreeSpace();
/**
+ * Check if new files or folders can be created within the folder
+ *
* @return bool
*/
public function isCreatable();
diff --git a/lib/public/files/node.php b/lib/public/files/node.php
index d3b71803f5..42dd910871 100644
--- a/lib/public/files/node.php
+++ b/lib/public/files/node.php
@@ -10,98 +10,149 @@ namespace OCP\Files;
interface Node {
/**
- * @param string $targetPath
- * @throws \OC\Files\NotPermittedException
+ * Move the file or folder to a new location
+ *
+ * @param string $targetPath the absolute target path
+ * @throws \OCP\Files\NotPermittedException
* @return \OCP\Files\Node
*/
public function move($targetPath);
+ /**
+ * Delete the file or folder
+ */
public function delete();
/**
- * @param string $targetPath
+ * Cope the file or folder to a new location
+ *
+ * @param string $targetPath the absolute target path
* @return \OCP\Files\Node
*/
public function copy($targetPath);
/**
- * @param int $mtime
- * @throws \OC\Files\NotPermittedException
+ * Change the modified date of the file or folder
+ * If $mtime is omitted the current time will be used
+ *
+ * @param int $mtime (optional) modified date as unix timestamp
+ * @throws \OCP\Files\NotPermittedException
*/
public function touch($mtime = null);
/**
+ * Get the storage backend the file or folder is stored on
+ *
* @return \OC\Files\Storage\Storage
- * @throws \OC\Files\NotFoundException
+ * @throws \OCP\Files\NotFoundException
*/
public function getStorage();
/**
+ * Get the full path of the file or folder
+ *
* @return string
*/
public function getPath();
/**
+ * Get the path of the file or folder relative to the mountpoint of it's storage
+ *
* @return string
*/
public function getInternalPath();
/**
+ * Get the internal file id for the file or folder
+ *
* @return int
*/
public function getId();
/**
+ * Get metadata of the file or folder
+ * The returned array contains the following values:
+ * - mtime
+ * - size
+ *
* @return array
*/
public function stat();
/**
+ * Get the modified date of the file or folder as unix timestamp
+ *
* @return int
*/
public function getMTime();
/**
+ * Get the size of the file or folder in bytes
+ *
* @return int
*/
public function getSize();
/**
+ * Get the Etag of the file or folder
+ * The Etag is an string id used to detect changes to a file or folder,
+ * every time the file or folder is changed the Etag will change to
+ *
* @return string
*/
public function getEtag();
+
/**
+ * Get the permissions of the file or folder as a combination of one or more of the following constants:
+ * - \OCP\PERMISSION_READ
+ * - \OCP\PERMISSION_UPDATE
+ * - \OCP\PERMISSION_CREATE
+ * - \OCP\PERMISSION_DELETE
+ * - \OCP\PERMISSION_SHARE
+ *
* @return int
*/
public function getPermissions();
/**
+ * Check if the file or folder is readable
+ *
* @return bool
*/
public function isReadable();
/**
+ * Check if the file or folder is writable
+ *
* @return bool
*/
public function isUpdateable();
/**
+ * Check if the file or folder is deletable
+ *
* @return bool
*/
public function isDeletable();
/**
+ * Check if the file or folder is shareable
+ *
* @return bool
*/
public function isShareable();
/**
- * @return Node
+ * Get the parent folder of the file or folder
+ *
+ * @return Folder
*/
public function getParent();
/**
+ * Get the filename of the file or folder
+ *
* @return string
*/
public function getName();
--
GitLab