[Share 2.0] Fix interfaces and comments

* Made comments more clear
* Removed unneeded methods
* IShares shareTime is now a proper DateTime object
* IShares getPath -> getNode & setPath -> setNode
* Fix unit tests

6 files changed, 106 insertions, 101 deletions

diff --git a/lib/private/share20/defaultshareprovider.php b/lib/private/share20/defaultshareprovider.php
index 74dd408ad21..baa12d6c933 100644
--- a/lib/private/share20/defaultshareprovider.php
+++ b/lib/private/share20/defaultshareprovider.php
@@ -128,15 +128,15 @@ class DefaultShareProvider implements IShareProvider {
 
 		// Set what is shares
 		$qb->setValue('item_type', $qb->createParameter('itemType'));
-		if ($share->getPath() instanceof \OCP\Files\File) {
+		if ($share->getNode() instanceof \OCP\Files\File) {
 			$qb->setParameter('itemType', 'file');
 		} else {
 			$qb->setParameter('itemType', 'folder');
 		}
 
 		// Set the file id
-		$qb->setValue('item_source', $qb->createNamedParameter($share->getPath()->getId()));
-		$qb->setValue('file_source', $qb->createNamedParameter($share->getPath()->getId()));
+		$qb->setValue('item_source', $qb->createNamedParameter($share->getNode()->getId()));
+		$qb->setValue('file_source', $qb->createNamedParameter($share->getNode()->getId()));
 
 		// set the permissions
 		$qb->setValue('permissions', $qb->createNamedParameter($share->getPermissions()));
@@ -195,8 +195,8 @@ class DefaultShareProvider implements IShareProvider {
 				->set('uid_owner', $qb->createNamedParameter($share->getShareOwner()->getUID()))
 				->set('uid_initiator', $qb->createNamedParameter($share->getSharedBy()->getUID()))
 				->set('permissions', $qb->createNamedParameter($share->getPermissions()))
-				->set('item_source', $qb->createNamedParameter($share->getPath()->getId()))
-				->set('file_source', $qb->createNamedParameter($share->getPath()->getId()))
+				->set('item_source', $qb->createNamedParameter($share->getNode()->getId()))
+				->set('file_source', $qb->createNamedParameter($share->getNode()->getId()))
 				->execute();
 		} else if ($share->getShareType() === \OCP\Share::SHARE_TYPE_GROUP) {
 			$qb = $this->dbConn->getQueryBuilder();
@@ -205,8 +205,8 @@ class DefaultShareProvider implements IShareProvider {
 				->set('uid_owner', $qb->createNamedParameter($share->getShareOwner()->getUID()))
 				->set('uid_initiator', $qb->createNamedParameter($share->getSharedBy()->getUID()))
 				->set('permissions', $qb->createNamedParameter($share->getPermissions()))
-				->set('item_source', $qb->createNamedParameter($share->getPath()->getId()))
-				->set('file_source', $qb->createNamedParameter($share->getPath()->getId()))
+				->set('item_source', $qb->createNamedParameter($share->getNode()->getId()))
+				->set('file_source', $qb->createNamedParameter($share->getNode()->getId()))
 				->execute();
 
 			/*
@@ -217,8 +217,8 @@ class DefaultShareProvider implements IShareProvider {
 				->where($qb->expr()->eq('parent', $qb->createNamedParameter($share->getId())))
 				->set('uid_owner', $qb->createNamedParameter($share->getShareOwner()->getUID()))
 				->set('uid_initiator', $qb->createNamedParameter($share->getSharedBy()->getUID()))
-				->set('item_source', $qb->createNamedParameter($share->getPath()->getId()))
-				->set('file_source', $qb->createNamedParameter($share->getPath()->getId()))
+				->set('item_source', $qb->createNamedParameter($share->getNode()->getId()))
+				->set('file_source', $qb->createNamedParameter($share->getNode()->getId()))
 				->execute();
 
 			/*
@@ -239,8 +239,8 @@ class DefaultShareProvider implements IShareProvider {
 				->set('uid_owner', $qb->createNamedParameter($share->getShareOwner()->getUID()))
 				->set('uid_initiator', $qb->createNamedParameter($share->getSharedBy()->getUID()))
 				->set('permissions', $qb->createNamedParameter($share->getPermissions()))
-				->set('item_source', $qb->createNamedParameter($share->getPath()->getId()))
-				->set('file_source', $qb->createNamedParameter($share->getPath()->getId()))
+				->set('item_source', $qb->createNamedParameter($share->getNode()->getId()))
+				->set('file_source', $qb->createNamedParameter($share->getNode()->getId()))
 				->set('token', $qb->createNamedParameter($share->getToken()))
 				->set('expiration', $qb->createNamedParameter($share->getExpirationDate(), IQueryBuilder::PARAM_DATE))
 				->execute();
@@ -342,7 +342,7 @@ class DefaultShareProvider implements IShareProvider {
 			if ($data === false) {
 				$qb = $this->dbConn->getQueryBuilder();
 
-				$type = $share->getPath() instanceof \OCP\Files\File ? 'file' : 'folder';
+				$type = $share->getNode() instanceof \OCP\Files\File ? 'file' : 'folder';
 
 				//Insert new share
 				$qb->insert('share')
@@ -353,11 +353,11 @@ class DefaultShareProvider implements IShareProvider {
 						'uid_initiator' => $qb->createNamedParameter($share->getSharedBy()->getUID()),
 						'parent' => $qb->createNamedParameter($share->getId()),
 						'item_type' => $qb->createNamedParameter($type),
-						'item_source' => $qb->createNamedParameter($share->getPath()->getId()),
-						'file_source' => $qb->createNamedParameter($share->getPath()->getId()),
+						'item_source' => $qb->createNamedParameter($share->getNode()->getId()),
+						'file_source' => $qb->createNamedParameter($share->getNode()->getId()),
 						'file_target' => $qb->createNamedParameter($share->getTarget()),
 						'permissions' => $qb->createNamedParameter(0),
-						'stime' => $qb->createNamedParameter($share->getShareTime()),
+						'stime' => $qb->createNamedParameter($share->getShareTime()->getTimestamp()),
 					])->execute();
 
 			} else if ($data['permissions'] !== 0) {
@@ -451,7 +451,7 @@ class DefaultShareProvider implements IShareProvider {
 	 * Get share by id
 	 *
 	 * @param int $id
-	 * @return IShare
+	 * @return \OCP\Share\IShare
 	 * @throws ShareNotFound
 	 */
 	public function getShareById($id) {
@@ -650,7 +650,7 @@ class DefaultShareProvider implements IShareProvider {
 	 * Create a share object from an database row
 	 *
 	 * @param mixed[] $data
-	 * @return Share
+	 * @return \OCP\Share\IShare
 	 * @throws InvalidShare
 	 */
 	private function createShare($data) {
@@ -659,9 +659,12 @@ class DefaultShareProvider implements IShareProvider {
 			->setShareType((int)$data['share_type'])
 			->setPermissions((int)$data['permissions'])
 			->setTarget($data['file_target'])
-			->setShareTime((int)$data['stime'])
 			->setMailSend((bool)$data['mail_send']);
 
+		$shareTime = new \DateTime();
+		$shareTime->setTimestamp((int)$data['stime']);
+		$share->setShareTime($shareTime);
+
 		if ($share->getShareType() === \OCP\Share::SHARE_TYPE_USER) {
 			$sharedWith = $this->userManager->get($data['share_with']);
 			if ($sharedWith === null) {
@@ -702,7 +705,7 @@ class DefaultShareProvider implements IShareProvider {
 		}
 
 		$path = $this->getNode($share->getShareOwner(), (int)$data['file_source']);
-		$share->setPath($path);
+		$share->setNode($path);
 
 		if ($data['expiration'] !== null) {
 			$expiration = \DateTime::createFromFormat('Y-m-d H:i:s', $data['expiration']);
diff --git a/lib/private/share20/manager.php b/lib/private/share20/manager.php
index f17bc559e64..52580e27818 100644
--- a/lib/private/share20/manager.php
+++ b/lib/private/share20/manager.php
@@ -176,19 +176,19 @@ class Manager implements IManager {
 		}
 
 		// The path should be set
-		if ($share->getPath() === null) {
+		if ($share->getNode() === null) {
 			throw new \InvalidArgumentException('Path should be set');
 		}
 
 		// And it should be a file or a folder
-		if (!($share->getPath() instanceof \OCP\Files\File) &&
-				!($share->getPath() instanceof \OCP\Files\Folder)) {
+		if (!($share->getNode() instanceof \OCP\Files\File) &&
+				!($share->getNode() instanceof \OCP\Files\Folder)) {
 			throw new \InvalidArgumentException('Path should be either a file or a folder');
 		}
 
 		// Check if we actually have share permissions
-		if (!$share->getPath()->isShareable()) {
-			$message_t = $this->l->t('You are not allowed to share %s', [$share->getPath()->getPath()]);
+		if (!$share->getNode()->isShareable()) {
+			$message_t = $this->l->t('You are not allowed to share %s', [$share->getNode()->getPath()]);
 			throw new HintException($message_t, $message_t, 404);
 		}
 
@@ -198,8 +198,8 @@ class Manager implements IManager {
 		}
 
 		// Check that we do not share with more permissions than we have
-		if ($share->getPermissions() & ~$share->getPath()->getPermissions()) {
-			$message_t = $this->l->t('Cannot increase permissions of %s', [$share->getPath()->getPath()]);
+		if ($share->getPermissions() & ~$share->getNode()->getPermissions()) {
+			$message_t = $this->l->t('Cannot increase permissions of %s', [$share->getNode()->getPath()]);
 			throw new HintException($message_t, $message_t, 404);
 		}
 
@@ -283,7 +283,7 @@ class Manager implements IManager {
 		 * Also this is not what we want in the future.. then we want to squash identical shares.
 		 */
 		$provider = $this->factory->getProviderForType(\OCP\Share::SHARE_TYPE_USER);
-		$existingShares = $provider->getSharesByPath($share->getPath());
+		$existingShares = $provider->getSharesByPath($share->getNode());
 		foreach($existingShares as $existingShare) {
 			// Ignore if it is the same share
 			if ($existingShare->getFullId() === $share->getFullId()) {
@@ -324,7 +324,7 @@ class Manager implements IManager {
 		 * Also this is not what we want in the future.. then we want to squash identical shares.
 		 */
 		$provider = $this->factory->getProviderForType(\OCP\Share::SHARE_TYPE_GROUP);
-		$existingShares = $provider->getSharesByPath($share->getPath());
+		$existingShares = $provider->getSharesByPath($share->getNode());
 		foreach($existingShares as $existingShare) {
 			if ($existingShare->getFullId() === $share->getFullId()) {
 				continue;
@@ -391,7 +391,7 @@ class Manager implements IManager {
 			return false;
 		}
 
-		if ($this->isSharingDisabledForUser($share->getSharedBy())) {
+		if ($this->sharingDisabledForUser($share->getSharedBy())) {
 			return false;
 		}
 
@@ -447,10 +447,10 @@ class Manager implements IManager {
 		}
 
 		// Verify if there are any issues with the path
-		$this->pathCreateChecks($share->getPath());
+		$this->pathCreateChecks($share->getNode());
 
 		// On creation of a share the owner is always the owner of the path
-		$share->setShareOwner($share->getPath()->getOwner());
+		$share->setShareOwner($share->getNode()->getOwner());
 
 		// Cannot share with the owner
 		if ($share->getSharedWith() === $share->getShareOwner()) {
@@ -458,7 +458,7 @@ class Manager implements IManager {
 		}
 
 		// Generate the target
-		$target = $this->config->getSystemValue('share_folder', '/') .'/'. $share->getPath()->getName();
+		$target = $this->config->getSystemValue('share_folder', '/') .'/'. $share->getNode()->getName();
 		$target = \OC\Files\Filesystem::normalizePath($target);
 		$share->setTarget($target);
 
@@ -476,12 +476,12 @@ class Manager implements IManager {
 		$run = true;
 		$error = '';
 		$preHookData = [
-			'itemType' => $share->getPath() instanceof \OCP\Files\File ? 'file' : 'folder',
-			'itemSource' => $share->getPath()->getId(),
+			'itemType' => $share->getNode() instanceof \OCP\Files\File ? 'file' : 'folder',
+			'itemSource' => $share->getNode()->getId(),
 			'shareType' => $share->getShareType(),
 			'uidOwner' => $share->getSharedBy()->getUID(),
 			'permissions' => $share->getPermissions(),
-			'fileSource' => $share->getPath()->getId(),
+			'fileSource' => $share->getNode()->getId(),
 			'expiration' => $share->getExpirationDate(),
 			'token' => $share->getToken(),
 			'itemTarget' => $share->getTarget(),
@@ -501,12 +501,12 @@ class Manager implements IManager {
 
 		// Post share hook
 		$postHookData = [
-			'itemType' => $share->getPath() instanceof \OCP\Files\File ? 'file' : 'folder',
-			'itemSource' => $share->getPath()->getId(),
+			'itemType' => $share->getNode() instanceof \OCP\Files\File ? 'file' : 'folder',
+			'itemSource' => $share->getNode()->getId(),
 			'shareType' => $share->getShareType(),
 			'uidOwner' => $share->getSharedBy()->getUID(),
 			'permissions' => $share->getPermissions(),
-			'fileSource' => $share->getPath()->getId(),
+			'fileSource' => $share->getNode()->getId(),
 			'expiration' => $share->getExpirationDate(),
 			'token' => $share->getToken(),
 			'id' => $share->getId(),
@@ -578,7 +578,7 @@ class Manager implements IManager {
 			}
 		}
 
-		$this->pathCreateChecks($share->getPath());
+		$this->pathCreateChecks($share->getNode());
 
 		// Now update the share!
 		$provider = $this->factory->getProviderForType($share->getShareType());
@@ -586,8 +586,8 @@ class Manager implements IManager {
 
 		if ($expirationDateUpdated === true) {
 			\OC_Hook::emit('OCP\Share', 'post_set_expiration_date', [
-				'itemType' => $share->getPath() instanceof \OCP\Files\File ? 'file' : 'folder',
-				'itemSource' => $share->getPath()->getId(),
+				'itemType' => $share->getNode() instanceof \OCP\Files\File ? 'file' : 'folder',
+				'itemSource' => $share->getNode()->getId(),
 				'date' => $share->getExpirationDate(),
 				'uidOwner' => $share->getSharedBy()->getUID(),
 			]);
@@ -644,13 +644,13 @@ class Manager implements IManager {
 
 			$hookParams = [
 				'id'         => $share->getId(),
-				'itemType'   => $share->getPath() instanceof \OCP\Files\File ? 'file' : 'folder',
-				'itemSource' => $share->getPath()->getId(),
+				'itemType'   => $share->getNode() instanceof \OCP\Files\File ? 'file' : 'folder',
+				'itemSource' => $share->getNode()->getId(),
 				'shareType'  => $shareType,
 				'shareWith'  => $sharedWith,
 				'itemparent' => $share->getParent(),
 				'uidOwner'   => $share->getSharedBy()->getUID(),
-				'fileSource' => $share->getPath()->getId(),
+				'fileSource' => $share->getNode()->getId(),
 				'fileTarget' => $share->getTarget()
 			];
 			return $hookParams;
@@ -933,7 +933,7 @@ class Manager implements IManager {
 	 * @param IUser $user
 	 * @return bool
 	 */
-	public function isSharingDisabledForUser(IUser $user) {
+	public function sharingDisabledForUser(IUser $user) {
 		if ($this->config->getAppValue('core', 'shareapi_exclude_groups', 'no') === 'yes') {
 			$groupsList = $this->config->getAppValue('core', 'shareapi_exclude_groups_list', '');
 			$excludedGroups = json_decode($groupsList);
diff --git a/lib/private/share20/share.php b/lib/private/share20/share.php
index 6b38d2db490..f9cba10a07a 100644
--- a/lib/private/share20/share.php
+++ b/lib/private/share20/share.php
@@ -34,11 +34,11 @@ class Share implements \OCP\Share\IShare {
 	private $path;
 	/** @var int */
 	private $shareType;
-	/** @var IUser|IGroup|string */
+	/** @var IUser|IGroup */
 	private $sharedWith;
-	/** @var IUser|string */
+	/** @var IUser */
 	private $sharedBy;
-	/** @var IUser|string */
+	/** @var IUser */
 	private $shareOwner;
 	/** @var int */
 	private $permissions;
@@ -52,7 +52,7 @@ class Share implements \OCP\Share\IShare {
 	private $parent;
 	/** @var string */
 	private $target;
-	/** @var int */
+	/** @var \DateTime */
 	private $shareTime;
 	/** @var bool */
 	private $mailSend;
@@ -90,7 +90,7 @@ class Share implements \OCP\Share\IShare {
 	/**
 	 * @inheritdoc
 	 */
-	public function setPath(Node $path) {
+	public function setNode(Node $path) {
 		$this->path = $path;
 		return $this;
 	}
@@ -98,7 +98,7 @@ class Share implements \OCP\Share\IShare {
 	/**
 	 * @inheritdoc
 	 */
-	public function getPath() {
+	public function getNode() {
 		return $this->path;
 	}
 
@@ -265,7 +265,7 @@ class Share implements \OCP\Share\IShare {
 	/**
 	 * @inheritdoc
 	 */
-	public function setShareTime($shareTime) {
+	public function setShareTime(\DateTime $shareTime) {
 		$this->shareTime = $shareTime;
 		return $this;
 	}
diff --git a/lib/public/share/imanager.php b/lib/public/share/imanager.php
index fda4faa55cb..6531c14a857 100644
--- a/lib/public/share/imanager.php
+++ b/lib/public/share/imanager.php
@@ -129,7 +129,9 @@ interface IManager {
 	public function checkPassword(IShare $share, $password);
 
 	/**
-	 * Create a new share
+	 * Instantiates a new share object. This is to be passed to
+	 * createShare.
+	 *
 	 * @return IShare
 	 * @since 9.0.0
 	 */
@@ -205,6 +207,6 @@ interface IManager {
 	 * @return bool
 	 * @since 9.0.0
 	 */
-	public function isSharingDisabledForUser(IUser $user);
+	public function sharingDisabledForUser(IUser $user);
 
 }
diff --git a/lib/public/share/ishare.php b/lib/public/share/ishare.php
index 1038ccf4389..2fb41a17add 100644
--- a/lib/public/share/ishare.php
+++ b/lib/public/share/ishare.php
@@ -36,7 +36,7 @@ use OCP\IGroup;
 interface IShare {
 
 	/**
-	 * Get the id of the share
+	 * Get the internal id of the share.
 	 *
 	 * @return string
 	 * @since 9.0.0
@@ -44,7 +44,7 @@ interface IShare {
 	public function getId();
 
 	/**
-	 * Set the id of the share
+	 * Set the internal id of the share.
 	 *
 	 * @param string $id
 	 * @return \OCP\Share\IShare The modified share object
@@ -53,7 +53,8 @@ interface IShare {
 	public function setId($id);
 
 	/**
-	 * Get the full share id
+	 * Get the full share id. This is the <providerid>:<internalid>.
+	 * The full id is unique in the system.
 	 *
 	 * @return string
 	 * @since 9.0.0
@@ -70,21 +71,21 @@ interface IShare {
 	public function setProviderId($id);
 
 	/**
-	 * Set the path of this share
+	 * Set the node of the file/folder that is shared
 	 *
-	 * @param Node $path
+	 * @param File|Folder $path
 	 * @return \OCP\Share\IShare The modified object
 	 * @since 9.0.0
 	 */
-	public function setPath(Node $path);
+	public function setNode(Node $path);
 
 	/**
-	 * Get the path of this share for the current user
+	 * Get the node of the file/folder that is shared
 	 *
 	 * @return File|Folder
 	 * @since 9.0.0
 	 */
-	public function getPath();
+	public function getNode();
 
 	/**
 	 * Set the shareType
@@ -104,24 +105,25 @@ interface IShare {
 	public function getShareType();
 
 	/**
-	 * Set the receiver of this share
+	 * Set the receiver of this share.
 	 *
-	 * @param IUser|IGroup|string
+	 * @param IUser|IGroup
 	 * @return \OCP\Share\IShare The modified object
 	 * @since 9.0.0
 	 */
 	public function setSharedWith($sharedWith);
 
 	/**
-	 * Get the receiver of this share
+	 * Get the receiver of this share.
 	 *
-	 * @return IUser|IGroup|string
+	 * @return IUser|IGroup
 	 * @since 9.0.0
 	 */
 	public function getSharedWith();
 
 	/**
-	 * Set the permissions
+	 * Set the permissions.
+	 * See \OCP\Constants::PERMISSION_*
 	 *
 	 * @param int $permissions
 	 * @return \OCP\Share\IShare The modified object
@@ -131,6 +133,7 @@ interface IShare {
 
 	/**
 	 * Get the share permissions
+	 * See \OCP\Constants::PERMISSION_*
 	 *
 	 * @return int
 	 * @since 9.0.0
@@ -147,7 +150,7 @@ interface IShare {
 	public function setExpirationDate($expireDate);
 
 	/**
-	 * Get the share expiration date
+	 * Get the expiration date
 	 *
 	 * @return \DateTime
 	 * @since 9.0.0
@@ -155,9 +158,9 @@ interface IShare {
 	public function getExpirationDate();
 
 	/**
-	 * Set the sharer of the path
+	 * Set the sharer of the path.
 	 *
-	 * @param IUser|string $sharedBy
+	 * @param IUser $sharedBy
 	 * @return \OCP\Share\IShare The modified object
 	 * @since 9.0.0
 	 */
@@ -166,30 +169,32 @@ interface IShare {
 	/**
 	 * Get share sharer
 	 *
-	 * @return IUser|string
+	 * @return IUser
 	 * @since 9.0.0
 	 */
 	public function getSharedBy();
 
 	/**
-	 * Set the original share owner (who owns the path)
+	 * Set the original share owner (who owns the path that is shared)
 	 *
-	 * @param IUser|string
+	 * @param IUser
 	 * @return \OCP\Share\IShare The modified object
 	 * @since 9.0.0
 	 */
 	public function setShareOwner($shareOwner);
 
 	/**
-	 * Get the original share owner (who owns the path)
+	 * Get the original share owner (who owns the path that is shared)
 	 *
-	 * @return IUser|string
+	 * @return IUser
 	 * @since 9.0.0
 	 */
 	public function getShareOwner();
 
 	/**
-	 * Set the password
+	 * Set the password for this share.
+	 * When the share is passed to the share manager to be created
+	 * or updated the password will be hashed.
 	 *
 	 * @param string $password
 	 * @return \OCP\Share\IShare The modified object
@@ -198,7 +203,9 @@ interface IShare {
 	public function setPassword($password);
 
 	/**
-	 * Is a password set for this share
+	 * Get the password of this share.
+	 * If this share is obtained via a shareprovider the password is
+	 * hashed.
 	 *
 	 * @return string
 	 * @since 9.0.0
@@ -206,7 +213,7 @@ interface IShare {
 	public function getPassword();
 
 	/**
-	 * Set the token
+	 * Set the public link token.
 	 *
 	 * @param string $token
 	 * @return \OCP\Share\IShare The modified object
@@ -215,7 +222,7 @@ interface IShare {
 	public function setToken($token);
 
 	/**
-	 * Get the token
+	 * Get the public link token.
 	 *
 	 * @return string
 	 * @since 9.0.0
@@ -223,15 +230,7 @@ interface IShare {
 	public function getToken();
 
 	/**
-	 * Get the parent it
-	 *
-	 * @return int
-	 * @since 9.0.0
-	 */
-	public function getParent();
-
-	/**
-	 * Set the target of this share
+	 * Set the target path of this share relative to the recipients user folder.
 	 *
 	 * @param string $target
 	 * @return \OCP\Share\IShare The modified object
@@ -240,7 +239,7 @@ interface IShare {
 	public function setTarget($target);
 
 	/**
-	 * Get the target of this share
+	 * Get the target path of this share relative to the recipients user folder.
 	 *
 	 * @return string
 	 * @since 9.0.0
@@ -250,22 +249,22 @@ interface IShare {
 	/**
 	 * Set the time this share was created
 	 *
-	 * @param int $shareTime
+	 * @param \DateTime $shareTime
 	 * @return \OCP\Share\IShare The modified object
 	 * @since 9.0.0
 	 */
-	public function setShareTime($shareTime);
+	public function setShareTime(\DateTime $shareTime);
 
 	/**
 	 * Get the timestamp this share was created
 	 *
-	 * @return int
+	 * @return \DateTime
 	 * @since 9.0.0
 	 */
 	public function getShareTime();
 
 	/**
-	 * Set mailSend
+	 * Set if the recipient is informed by mail about the share.
 	 *
 	 * @param bool $mailSend
 	 * @return \OCP\Share\IShare The modified object
@@ -274,7 +273,7 @@ interface IShare {
 	public function setMailSend($mailSend);
 
 	/**
-	 * Get mailSend
+	 * Get if the recipient informed by mail about the share.
 	 *
 	 * @return bool
 	 * @since 9.0.0
diff --git a/lib/public/share/ishareprovider.php b/lib/public/share/ishareprovider.php
index fa1b63d2d1a..50964c88dd6 100644
--- a/lib/public/share/ishareprovider.php
+++ b/lib/public/share/ishareprovider.php
@@ -42,7 +42,7 @@ interface IShareProvider {
 	public function identifier();
 
 	/**
-	 * Share a path
+	 * Create a share
 	 * 
 	 * @param \OCP\Share\IShare $share
 	 * @return \OCP\Share\IShare The share object
@@ -69,7 +69,8 @@ interface IShareProvider {
 
 	/**
 	 * Unshare a file from self as recipient.
-	 * This may require special handling.
+	 * This may require special handling. If a user unshares a group
+	 * share from their self then the original group share should still exist.
 	 *
 	 * @param \OCP\Share\IShare $share
 	 * @param IUser $recipient
@@ -86,7 +87,7 @@ interface IShareProvider {
 	 * @param bool $reshares Also get the shares where $user is the owner instead of just the shares where $user is the initiator
 	 * @param int $limit The maximum number of shares to be returned, -1 for all shares
 	 * @param int $offset
-	 * @return Share[]
+	 * @return \OCP\Share\I Share[]
 	 * @since 9.0.0
 	 */
 	public function getSharesBy(IUser $user, $shareType, $node, $reshares, $limit, $offset);
@@ -95,7 +96,7 @@ interface IShareProvider {
 	 * Get share by id
 	 *
 	 * @param int $id
-	 * @return IShare
+	 * @return \OCP\Share\IShare
 	 * @throws ShareNotFound
 	 * @since 9.0.0
 	 */
@@ -105,7 +106,7 @@ interface IShareProvider {
 	 * Get shares for a given path
 	 *
 	 * @param \OCP\Files\Node $path
-	 * @return IShare[]
+	 * @return \OCP\Share\IShare[]
 	 * @since 9.0.0
 	 */
 	public function getSharesByPath(\OCP\Files\Node $path);
@@ -117,7 +118,7 @@ interface IShareProvider {
 	 * @param int $shareType
 	 * @param int $limit The max number of entries returned, -1 for all
 	 * @param int $offset
-	 * @param Share
+	 * @return \OCP\Share\IShare[]
 	 * @since 9.0.0
 	 */
 	public function getSharedWith(IUser $user, $shareType, $limit, $offset);
@@ -126,7 +127,7 @@ interface IShareProvider {
 	 * Get a share by token
 	 *
 	 * @param string $token
-	 * @return IShare
+	 * @return \OCP\Share\IShare
 	 * @throws ShareNotFound
 	 * @since 9.0.0
 	 */