Merge pull request #8542 from owncloud/phpdoc-improvements

PHPDoc Improvements

5 files changed, 59 insertions, 37 deletions

diff --git a/lib/private/share/helper.php b/lib/private/share/helper.php
index 515ec85909a..bc83d569840 100644
--- a/lib/private/share/helper.php
+++ b/lib/private/share/helper.php
@@ -25,13 +25,14 @@ class Helper extends \OC\Share\Constants {
 
 	/**
 	 * Generate a unique target for the item
-	 * @param string Item type
-	 * @param string Item source
-	 * @param int SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK
-	 * @param string User or group the item is being shared with
-	 * @param string User that is the owner of shared item
-	 * @param string The suggested target originating from a reshare (optional)
-	 * @param int The id of the parent group share (optional)
+	 * @param string $itemType
+	 * @param string $itemSource
+	 * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK
+	 * @param string $shareWith User or group the item is being shared with
+	 * @param string $uidOwner User that is the owner of shared item
+	 * @param string $suggestedTarget The suggested target originating from a reshare (optional)
+	 * @param int $groupParent The id of the parent group share (optional)
+	 * @throws \Exception
 	 * @return string Item target
 	 */
 	public static function generateTarget($itemType, $itemSource, $shareType, $shareWith, $uidOwner,
@@ -142,9 +143,9 @@ class Helper extends \OC\Share\Constants {
 
 	/**
 	 * Delete all reshares of an item
-	 * @param int Id of item to delete
-	 * @param bool If true, exclude the parent from the delete (optional)
-	 * @param string The user that the parent was shared with (optinal)
+	 * @param int $parent Id of item to delete
+	 * @param bool $excludeParent If true, exclude the parent from the delete (optional)
+	 * @param string $uidOwner The user that the parent was shared with (optional)
 	 */
 	public static function delete($parent, $excludeParent = false, $uidOwner = null) {
 		$ids = array($parent);
diff --git a/lib/private/share/hooks.php b/lib/private/share/hooks.php
index a33c71eedd2..9ac64d888ea 100644
--- a/lib/private/share/hooks.php
+++ b/lib/private/share/hooks.php
@@ -22,9 +22,9 @@
 namespace OC\Share;
 
 class Hooks extends \OC\Share\Constants {
-		/**
+	/**
 	 * Function that is called after a user is deleted. Cleans up the shares of that user.
-	 * @param array arguments
+	 * @param array $arguments
 	 */
 	public static function post_deleteUser($arguments) {
 		// Delete any items shared with the deleted user
@@ -42,7 +42,7 @@ class Hooks extends \OC\Share\Constants {
 	/**
 	 * Function that is called after a user is added to a group.
 	 * TODO what does it do?
-	 * @param array arguments
+	 * @param array $arguments
 	 */
 	public static function post_addToGroup($arguments) {
 		// Find the group shares and check if the user needs a unique target
@@ -76,7 +76,7 @@ class Hooks extends \OC\Share\Constants {
 
 	/**
 	 * Function that is called after a user is removed from a group. Shares are cleaned up.
-	 * @param array arguments
+	 * @param array $arguments
 	 */
 	public static function post_removeFromGroup($arguments) {
 		$sql = 'SELECT `id`, `share_type` FROM `*PREFIX*share`'
@@ -95,7 +95,7 @@ class Hooks extends \OC\Share\Constants {
 
 	/**
 	 * Function that is called after a group is removed. Cleans up the shares to that group.
-	 * @param array arguments
+	 * @param array $arguments
 	 */
 	public static function post_deleteGroup($arguments) {
 		$sql = 'SELECT `id` FROM `*PREFIX*share` WHERE `share_type` = ? AND `share_with` = ?';
diff --git a/lib/private/share/mailnotifications.php b/lib/private/share/mailnotifications.php
index 4799db52330..ca0dff6562d 100644
--- a/lib/private/share/mailnotifications.php
+++ b/lib/private/share/mailnotifications.php
@@ -21,11 +21,30 @@
 
 namespace OC\Share;
 
+use DateTime;
+
 class MailNotifications {
 
-	private $senderId;    // sender userId
-	private $from;        // sender email address
+	/**
+	 * sender userId
+	 * @var null|string
+	 */
+	private $senderId;
+
+	/**
+	 * sender email address
+	 * @var string
+	 */
+	private $from;
+
+	/**
+	 * @var string
+	 */
 	private $senderDisplayName;
+
+	/**
+	 * @var \OC_L10N
+	 */
 	private $l;
 
 	/**
@@ -50,8 +69,8 @@ class MailNotifications {
 	 * @brief inform users if a file was shared with them
 	 *
 	 * @param array $recipientList list of recipients
-	 * @param type $itemSource shared item source
-	 * @param type $itemType shared item type
+	 * @param string $itemSource shared item source
+	 * @param string $itemType shared item type
 	 * @return array list of user to whom the mail send operation failed
 	 */
 	public function sendInternalShareMail($recipientList, $itemSource, $itemType) {
@@ -136,7 +155,7 @@ class MailNotifications {
 	 * @param string $filename the shared file
 	 * @param string $link link to the shared file
 	 * @param int $expiration expiration date (timestamp)
-	 * @return array with the html mail body and the plain text mail body
+	 * @return array an array of the html mail body and the plain text mail body
 	 */
 	private function createMailBody($filename, $link, $expiration) {
 
diff --git a/lib/private/share/searchresultsorter.php b/lib/private/share/searchresultsorter.php
index 76abbf30846..91709902fff 100644
--- a/lib/private/share/searchresultsorter.php
+++ b/lib/private/share/searchresultsorter.php
@@ -18,8 +18,8 @@ class SearchResultSorter {
 	 * @param string $search the search term as was given by the user
 	 * @param string $key the array key containing the value that should be compared
 	 * against
-	 * @param $encoding optional, encoding to use, defaults to UTF-8
-	 * @param $log optional, an \OC\Log instance
+	 * @param string $encoding optional, encoding to use, defaults to UTF-8
+	 * @param \OC\Log $log optional
 	 */
 	public function __construct($search, $key, \OC\Log $log = null, $encoding = 'UTF-8') {
 		$this->encoding = $encoding;
diff --git a/lib/private/share/share.php b/lib/private/share/share.php
index 6f8830e73f2..a8537a916fb 100644
--- a/lib/private/share/share.php
+++ b/lib/private/share/share.php
@@ -254,13 +254,13 @@ class Share extends \OC\Share\Constants {
 
 	/**
 	 * Get the items of item type shared with a user
-	 * @param string Item type
-	 * @param sting user id for which user we want the shares
-	 * @param int Format (optional) Format type must be defined by the backend
-	 * @param mixed Parameters (optional)
-	 * @param int Number of items to return (optional) Returns all by default
-	 * @param boolean include collections (optional)
-	 * @return Return depends on format
+	 * @param string $itemType
+	 * @param string $user id for which user we want the shares
+	 * @param int $format (optional) Format type must be defined by the backend
+	 * @param mixed $parameters (optional)
+	 * @param int $limit Number of items to return (optional) Returns all by default
+	 * @param boolean $includeCollections (optional)
+	 * @return mixed Return depends on format
 	 */
 	public static function getItemsSharedWithUser($itemType, $user, $format = self::FORMAT_NONE,
 		$parameters = null, $limit = -1, $includeCollections = false) {
@@ -352,7 +352,7 @@ class Share extends \OC\Share\Constants {
 	 * @param string $itemType
 	 * @param string $itemSource
 	 * @param string $uidOwner Owner of link
-	 * @return Item
+	 * @return array
 	 */
 	public static function getItemSharedWithByLink($itemType, $itemSource, $uidOwner) {
 		return self::getItems($itemType, $itemSource, self::SHARE_TYPE_LINK, null, $uidOwner, self::FORMAT_NONE,
@@ -362,7 +362,7 @@ class Share extends \OC\Share\Constants {
 	/**
 	 * Based on the given token the share information will be returned - password protected shares will be verified
 	 * @param string $token
-	 * @return array | boolean false will be returned in case the token is unknown or unauthorized
+	 * @return array|boolean false will be returned in case the token is unknown or unauthorized
 	 */
 	public static function getShareByToken($token, $checkPasswordProtection = true) {
 		$query = \OC_DB::prepare('SELECT * FROM `*PREFIX*share` WHERE `token` = ?', 1);
@@ -388,8 +388,8 @@ class Share extends \OC\Share\Constants {
 
 	/**
 	 * resolves reshares down to the last real share
-	 * @param $linkItem
-	 * @return $fileOwner
+	 * @param array $linkItem
+	 * @return array file owner
 	 */
 	public static function resolveReShare($linkItem)
 	{
@@ -446,7 +446,7 @@ class Share extends \OC\Share\Constants {
 	 * @param string $uidOwner
 	 * @param boolean $includeCollections
 	 * @param boolean $checkExpireDate
-	 * @return Return array of users
+	 * @return array Return array of users
 	 */
 	public static function getUsersItemShared($itemType, $itemSource, $uidOwner, $includeCollections = false, $checkExpireDate = true) {
 
@@ -926,6 +926,7 @@ class Share extends \OC\Share\Constants {
 	/**
 	 * Get the backend class for the specified item type
 	 * @param string $itemType
+	 * @throws \Exception
 	 * @return \OCP\Share_Backend
 	 */
 	public static function getBackend($itemType) {
@@ -1000,10 +1001,10 @@ class Share extends \OC\Share\Constants {
 	/**
 	 * Get shared items from the database
 	 * @param string $itemType
-	 * @param string Item source or target (optional)
+	 * @param string $item Item source or target (optional)
 	 * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, SHARE_TYPE_LINK, $shareTypeUserAndGroups, or $shareTypeGroupUserUnique
 	 * @param string $shareWith User or group the item is being shared with
-	 * @param string uidOwner User that is the owner of shared items (optional)
+	 * @param string $uidOwner User that is the owner of shared items (optional)
 	 * @param int $format Format to convert items to with formatItems() (optional)
 	 * @param mixed $parameters to pass to formatItems() (optional)
 	 * @param int $limit Number of items to return, -1 to return all matches (optional)
@@ -1353,6 +1354,7 @@ class Share extends \OC\Share\Constants {
 	 * @param boolean|array $parentFolder Parent folder target (optional)
 	 * @param string $token (optional)
 	 * @param string $itemSourceName name of the source item (optional)
+	 * @throws \Exception
 	 * @return boolean Returns true on success or false on failure
 	 */
 	private static function put($itemType, $itemSource, $shareType, $shareWith, $uidOwner,
@@ -1641,7 +1643,7 @@ class Share extends \OC\Share\Constants {
 	}
 
 	/**
-	 * @breif construct select statement
+	 * @brief construct select statement
 	 * @param int $format
 	 * @param boolean $fileDependent ist it a file/folder share or a generla share
 	 * @param string $uidOwner