fix documentation stuff

1 files changed, 262 insertions, 240 deletions

diff --git a/lib/public/share.php b/lib/public/share.php
index c62f964fe1b..e4f68017d26 100644
--- a/lib/public/share.php
+++ b/lib/public/share.php
@@ -1,32 +1,32 @@
 <?php
 /**
-* ownCloud
-*
-* @author Michael Gapczynski
-* @copyright 2012 Michael Gapczynski mtgap@owncloud.com
-*
-* This library is free software; you can redistribute it and/or
-* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
-* License as published by the Free Software Foundation; either
-* version 3 of the License, or any later version.
-*
-* This library is distributed in the hope that it will be useful,
-* but WITHOUT ANY WARRANTY; without even the implied warranty of
-* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
-*
-* You should have received a copy of the GNU Affero General Public
-* License along with this library.  If not, see <http://www.gnu.org/licenses/>.
-*/
+ * ownCloud
+ *
+ * @author Michael Gapczynski
+ * @copyright 2012 Michael Gapczynski mtgap@owncloud.com
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public
+ * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
 namespace OCP;
 
 /**
-* This class provides the ability for apps to share their content between users.
-* Apps must create a backend class that implements OCP\Share_Backend and register it with this class.
-*
-* It provides the following hooks:
-*  - post_shared
-*/
+ * This class provides the ability for apps to share their content between users.
+ * Apps must create a backend class that implements OCP\Share_Backend and register it with this class.
+ *
+ * It provides the following hooks:
+ *  - post_shared
+ */
 class Share {
 
 	const SHARE_TYPE_USER = 0;
@@ -37,19 +37,19 @@ class Share {
 	const SHARE_TYPE_REMOTE = 6;
 
 	/** CRUDS permissions (Create, Read, Update, Delete, Share) using a bitmask
-	* Construct permissions for share() and setPermissions with Or (|) e.g.
-	* Give user read and update permissions: PERMISSION_READ | PERMISSION_UPDATE
-	*
-	* Check if permission is granted with And (&) e.g. Check if delete is
-	* granted: if ($permissions & PERMISSION_DELETE)
-	*
-	* Remove permissions with And (&) and Not (~) e.g. Remove the update
-	* permission: $permissions &= ~PERMISSION_UPDATE
-	*
-	* Apps are required to handle permissions on their own, this class only
-	* stores and manages the permissions of shares
-	* @see lib/public/constants.php
-	*/
+	 * Construct permissions for share() and setPermissions with Or (|) e.g.
+	 * Give user read and update permissions: PERMISSION_READ | PERMISSION_UPDATE
+	 *
+	 * Check if permission is granted with And (&) e.g. Check if delete is
+	 * granted: if ($permissions & PERMISSION_DELETE)
+	 *
+	 * Remove permissions with And (&) and Not (~) e.g. Remove the update
+	 * permission: $permissions &= ~PERMISSION_UPDATE
+	 *
+	 * Apps are required to handle permissions on their own, this class only
+	 * stores and manages the permissions of shares
+	 * @see lib/public/constants.php
+	 */
 
 	const FORMAT_NONE = -1;
 	const FORMAT_STATUSES = -2;
@@ -64,13 +64,13 @@ class Share {
 	private static $isResharingAllowed;
 
 	/**
-	* Register a sharing backend class that implements OCP\Share_Backend for an item type
-	* @param string Item type
-	* @param string Backend class
-	* @param string (optional) Depends on item type
-	* @param array (optional) List of supported file extensions if this item type depends on files
-	* @return Returns true if backend is registered or false if error
-	*/
+	 * Register a sharing backend class that implements OCP\Share_Backend for an item type
+	 * @param string Item type
+	 * @param string Backend class
+	 * @param string (optional) Depends on item type
+	 * @param array (optional) List of supported file extensions if this item type depends on files
+	 * @return Returns true if backend is registered or false if error
+	 */
 	public static function registerBackend($itemType, $class, $collectionOf = null, $supportedFileExtensions = null) {
 		if (self::isEnabled()) {
 			if (!isset(self::$backendTypes[$itemType])) {
@@ -94,11 +94,11 @@ class Share {
 	}
 
 	/**
-	* Check if the Share API is enabled
-	* @return Returns true if enabled or false
-	*
-	* The Share API is enabled by default if not configured
-	*/
+	 * Check if the Share API is enabled
+	 * @return Returns true if enabled or false
+	 *
+	 * The Share API is enabled by default if not configured
+	 */
 	public static function isEnabled() {
 		if (\OC_Appconfig::getValue('core', 'shareapi_enabled', 'yes') == 'yes') {
 			return true;
@@ -107,9 +107,10 @@ class Share {
 	}
 
 	/**
-	* Prepare a path to be passed to DB as file_target
-	* @return string Prepared path
-	*/
+	 * Prepare a path to be passed to DB as file_target
+	 * @param string $path path
+	 * @return string Prepared path
+	 */
 	public static function prepFileTarget( $path ) {
 
 		// Paths in DB are stored with leading slashes, so add one if necessary
@@ -124,14 +125,14 @@ class Share {
 	}
 
 	/**
-	* Find which users can access a shared item
-	* @param $path to the file
-	* @param $user owner of the file
-	* @param include owner to the list of users with access to the file
-	* @return array
-	* @note $path needs to be relative to user data dir, e.g. 'file.txt'
-	*       not '/admin/data/file.txt'
-	*/
+	 * Find which users can access a shared item
+	 * @param $path to the file
+	 * @param $user owner of the file
+	 * @param include owner to the list of users with access to the file
+	 * @return array
+	 * @note $path needs to be relative to user data dir, e.g. 'file.txt'
+	 *       not '/admin/data/file.txt'
+	 */
 	public static function getUsersSharingFile($path, $user, $includeOwner = false) {
 
 		$shares = array();
@@ -231,12 +232,12 @@ class Share {
 	}
 
 	/**
-	* Get the items of item type shared with the current user
-	* @param string Item type
-	* @param int Format (optional) Format type must be defined by the backend
-	* @param int Number of items to return (optional) Returns all by default
-	* @return Return depends on format
-	*/
+	 * Get the items of item type shared with the current user
+	 * @param string Item type
+	 * @param int Format (optional) Format type must be defined by the backend
+	 * @param int Number of items to return (optional) Returns all by default
+	 * @return Return depends on format
+	 */
 	public static function getItemsSharedWith($itemType, $format = self::FORMAT_NONE,
 		$parameters = null, $limit = -1, $includeCollections = false) {
 		return self::getItems($itemType, null, self::$shareTypeUserAndGroups, \OC_User::getUser(), null, $format,
@@ -244,12 +245,12 @@ class Share {
 	}
 
 	/**
-	* Get the item of item type shared with the current user
-	* @param string $itemType
-	* @param string $ItemTarget
-	* @param int $format (optional) Format type must be defined by the backend
-	* @return Return depends on format
-	*/
+	 * Get the item of item type shared with the current user
+	 * @param string $itemType
+	 * @param string $ItemTarget
+	 * @param int $format (optional) Format type must be defined by the backend
+	 * @return Return depends on format
+	 */
 	public static function getItemSharedWith($itemType, $itemTarget, $format = self::FORMAT_NONE,
 		$parameters = null, $includeCollections = false) {
 		return self::getItems($itemType, $itemTarget, self::$shareTypeUserAndGroups, \OC_User::getUser(), null, $format,
@@ -306,12 +307,14 @@ class Share {
 	}
 
 	/**
-	* Get the item of item type shared with the current user by source
-	* @param string Item type
-	* @param string Item source
-	* @param int Format (optional) Format type must be defined by the backend
-	* @return Return depends on format
-	*/
+	 * Get the item of item type shared with the current user by source
+	 * @param string Item type
+	 * @param string Item source
+	 * @param int Format (optional) Format type must be defined by the backend
+	 * @param mixed Parameters
+	 * @param bool include collections
+	 * @return Return depends on format
+	 */
 	public static function getItemSharedWithBySource($itemType, $itemSource, $format = self::FORMAT_NONE,
 		$parameters = null, $includeCollections = false) {
 		return self::getItems($itemType, $itemSource, self::$shareTypeUserAndGroups, \OC_User::getUser(), null, $format,
@@ -319,12 +322,12 @@ class Share {
 	}
 
 	/**
-	* Get the item of item type shared by a link
-	* @param string Item type
-	* @param string Item source
-	* @param string Owner of link
-	* @return Item
-	*/
+	 * Get the item of item type shared by a link
+	 * @param string Item type
+	 * @param string Item source
+	 * @param string Owner of link
+	 * @return Item
+	 */
 	public static function getItemSharedWithByLink($itemType, $itemSource, $uidOwner) {
 		return self::getItems($itemType, $itemSource, self::SHARE_TYPE_LINK, null, $uidOwner, self::FORMAT_NONE,
 			null, 1);
@@ -379,12 +382,14 @@ class Share {
 
 
 	/**
-	* Get the shared items of item type owned by the current user
-	* @param string Item type
-	* @param int Format (optional) Format type must be defined by the backend
-	* @param int Number of items to return (optional) Returns all by default
-	* @return Return depends on format
-	*/
+	 * Get the shared items of item type owned by the current user
+	 * @param string Item type
+	 * @param int Format (optional) Format type must be defined by the backend
+	 * @param mixed Parameters
+	 * @param int Number of items to return (optional) Returns all by default
+	 * @param bool include collections
+	 * @return Return depends on format
+	 */
 	public static function getItemsShared($itemType, $format = self::FORMAT_NONE, $parameters = null,
 		$limit = -1, $includeCollections = false) {
 		return self::getItems($itemType, null, null, null, \OC_User::getUser(), $format,
@@ -392,12 +397,14 @@ class Share {
 	}
 
 	/**
-	* Get the shared item of item type owned by the current user
-	* @param string Item type
-	* @param string Item source
-	* @param int Format (optional) Format type must be defined by the backend
-	* @return Return depends on format
-	*/
+	 * Get the shared item of item type owned by the current user
+	 * @param string Item type
+	 * @param string Item source
+	 * @param int Format (optional) Format type must be defined by the backend
+	 * @param mixed Parameters
+	 * @param bool include collections
+	 * @return Return depends on format
+	 */
 	public static function getItemShared($itemType, $itemSource, $format = self::FORMAT_NONE,
 	                                     $parameters = null, $includeCollections = false) {
 		return self::getItems($itemType, $itemSource, null, null, \OC_User::getUser(), $format,
@@ -405,13 +412,13 @@ class Share {
 	}
 
 	/**
-	* Get all users an item is shared with
-	* @param string Item type
-	* @param string Item source
-	* @param string Owner
-	* @param bool Include collections
-	* @return Return array of users
-	*/
+	 * Get all users an item is shared with
+	 * @param string Item type
+	 * @param string Item source
+	 * @param string Owner
+	 * @param bool Include collections
+	 * @return Return array of users
+	 */
 	public static function getUsersItemShared($itemType, $itemSource, $uidOwner, $includeCollections = false) {
 		$users = array();
 		$items = self::getItems($itemType, $itemSource, null, null, $uidOwner, self::FORMAT_NONE, null, -1, $includeCollections);
@@ -617,13 +624,13 @@ class Share {
 	}
 
 	/**
-	* Unshare an item from a user, group, or delete a private link
-	* @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
-	* @return Returns true on success or false on failure
-	*/
+	 * Unshare an item from a user, group, or delete a private link
+	 * @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
+	 * @return Returns true on success or false on failure
+	 */
 	public static function unshare($itemType, $itemSource, $shareType, $shareWith) {
 		if ($item = self::getItems($itemType, $itemSource, $shareType, $shareWith, \OC_User::getUser(),
 			self::FORMAT_NONE, null, 1)) {
@@ -650,11 +657,11 @@ class Share {
 	}
 
 	/**
-	* Unshare an item from all users, groups, and remove all links
-	* @param string Item type
-	* @param string Item source
-	* @return Returns true on success or false on failure
-	*/
+	 * Unshare an item from all users, groups, and remove all links
+	 * @param string Item type
+	 * @param string Item source
+	 * @return Returns true on success or false on failure
+	 */
 	public static function unshareAll($itemType, $itemSource) {
 		if ($shares = self::getItemShared($itemType, $itemSource)) {
 			// Pass all the vars we have for now, they may be useful
@@ -677,14 +684,13 @@ class Share {
 	}
 
 	/**
-	* Unshare an item shared with the current user
-	* @param string Item type
-	* @param string Item target
-	* @return Returns true on success or false on failure
-	*
-	* Unsharing from self is not allowed for items inside collections
-	*
-	*/
+	 * Unshare an item shared with the current user
+	 * @param string Item type
+	 * @param string Item target
+	 * @return Returns true on success or false on failure
+	 *
+	 * Unsharing from self is not allowed for items inside collections
+	 */
 	public static function unshareFromSelf($itemType, $itemTarget) {
 		if ($item = self::getItemSharedWith($itemType, $itemTarget)) {
 			if ((int)$item['share_type'] === self::SHARE_TYPE_GROUP) {
@@ -733,19 +739,17 @@ class Share {
 		if($result === false) {
 			\OC_Log::write('OCP\Share', 'Couldn\'t set send mail status', \OC_Log::ERROR);
 		}
-
-
 	}
 
 	/**
-	* Set the permissions of an item for a specific user or group
-	* @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 int CRUDS permissions
-	* @return Returns true on success or false on failure
-	*/
+	 * Set the permissions of an item for a specific user or group
+	 * @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 int CRUDS permissions
+	 * @return Returns true on success or false on failure
+	 */
 	public static function setPermissions($itemType, $itemSource, $shareType, $shareWith, $permissions) {
 		if ($item = self::getItems($itemType, $itemSource, $shareType, $shareWith,
 			\OC_User::getUser(), self::FORMAT_NONE, null, 1, false)) {
@@ -821,6 +825,13 @@ class Share {
 		throw new \Exception($message);
 	}
 
+	/**
+	 * Set expiration date for a share
+	 * @param string $itemType
+	 * @param string $itemSource
+	 * @param string $date expiration date
+	 * @return Share_Backend
+	 */
 	public static function setExpirationDate($itemType, $itemSource, $date) {
 		if ($items = self::getItems($itemType, $itemSource, null, null, \OC_User::getUser(),
 			self::FORMAT_NONE, null, -1, false)) {
@@ -842,10 +853,10 @@ class Share {
 	}
 
 	/**
-	* Get the backend class for the specified item type
-	* @param string $itemType
-	* @return Share_Backend
-	*/
+	 * Get the backend class for the specified item type
+	 * @param string $itemType
+	 * @return Share_Backend
+	 */
 	public static function getBackend($itemType) {
 		if (isset(self::$backends[$itemType])) {
 			return self::$backends[$itemType];
@@ -871,12 +882,11 @@ class Share {
 	}
 
 	/**
-	* Check if resharing is allowed
-	* @return Returns true if allowed or false
-	*
-	* Resharing is allowed by default if not configured
-	*
-	*/
+	 * Check if resharing is allowed
+	 * @return Returns true if allowed or false
+	 *
+	 * Resharing is allowed by default if not configured
+	 */
 	private static function isResharingAllowed() {
 		if (!isset(self::$isResharingAllowed)) {
 			if (\OC_Appconfig::getValue('core', 'shareapi_allow_resharing', 'yes') == 'yes') {
@@ -889,10 +899,10 @@ class Share {
 	}
 
 	/**
-	* Get a list of collection item types for the specified item type
-	* @param string Item type
-	* @return array
-	*/
+	 * Get a list of collection item types for the specified item type
+	 * @param string Item type
+	 * @return array
+	 */
 	private static function getCollectionItemTypes($itemType) {
 		$collectionTypes = array($itemType);
 		foreach (self::$backendTypes as $type => $backend) {
@@ -913,21 +923,21 @@ class Share {
 	}
 
 	/**
-	* Get shared items from the database
-	* @param string Item type
-	* @param string Item source or target (optional)
-	* @param int SHARE_TYPE_USER, SHARE_TYPE_GROUP, SHARE_TYPE_LINK, $shareTypeUserAndGroups, or $shareTypeGroupUserUnique
-	* @param string User or group the item is being shared with
-	* @param string User that is the owner of shared items (optional)
-	* @param int Format to convert items to with formatItems()
-	* @param mixed Parameters to pass to formatItems()
-	* @param int Number of items to return, -1 to return all matches (optional)
-	* @param bool Include collection item types (optional)
-	* @return mixed
-	*
-	* See public functions getItem(s)... for parameter usage
-	*
-	*/
+	 * Get shared items from the database
+	 * @param string Item type
+	 * @param string Item source or target (optional)
+	 * @param int SHARE_TYPE_USER, SHARE_TYPE_GROUP, SHARE_TYPE_LINK, $shareTypeUserAndGroups, or $shareTypeGroupUserUnique
+	 * @param string User or group the item is being shared with
+	 * @param string User that is the owner of shared items (optional)
+	 * @param int Format to convert items to with formatItems()
+	 * @param mixed Parameters to pass to formatItems()
+	 * @param int Number of items to return, -1 to return all matches (optional)
+	 * @param bool Include collection item types (optional)
+	 * @return mixed
+	 *
+	 * See public functions getItem(s)... for parameter usage
+	 *
+	 */
 	private static function getItems($itemType, $item = null, $shareType = null, $shareWith = null,
 		$uidOwner = null, $format = self::FORMAT_NONE, $parameters = null, $limit = -1,
 		$includeCollections = false, $itemShareWithBySource = false) {
@@ -1322,15 +1332,15 @@ class Share {
 	}
 
 	/**
-	* Put shared item into the database
-	* @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 int CRUDS permissions
-	* @param bool|array Parent folder target (optional)
-	* @return bool Returns true on success or false on failure
-	*/
+	 * Put shared item into the database
+	 * @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 int CRUDS permissions
+	 * @param bool|array Parent folder target (optional)
+	 * @return bool Returns true on success or false on failure
+	 */
 	private static function put($itemType, $itemSource, $shareType, $shareWith, $uidOwner,
 		$permissions, $parentFolder = null, $token = null, $itemSourceName = null) {
 		$backend = self::getBackend($itemType);
@@ -1561,15 +1571,15 @@ class Share {
 	}
 
 	/**
-	* 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 The suggested target originating from a reshare (optional)
-	* @param int The id of the parent group share (optional)
-	* @return string Item target
-	*/
+	 * 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 The suggested target originating from a reshare (optional)
+	 * @param int The id of the parent group share (optional)
+	 * @return string Item target
+	 */
 	private static function generateTarget($itemType, $itemSource, $shareType, $shareWith, $uidOwner,
 		$suggestedTarget = null, $groupParent = null) {
 		$backend = self::getBackend($itemType);
@@ -1677,11 +1687,11 @@ class Share {
 	}
 
 	/**
-	* 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)
-	*/
+	 * 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)
+	 */
 	private static function delete($parent, $excludeParent = false, $uidOwner = null) {
 		$ids = array($parent);
 		$parents = array($parent);
@@ -1749,9 +1759,12 @@ class Share {
 	}
 
 	/**
-	* Hook Listeners
-	*/
+	 * Hook Listeners
+	 */
 
+	/**
+	 * @param array arguments
+	 */
 	public static function post_deleteUser($arguments) {
 		// Delete any items shared with the deleted user
 		$query = \OC_DB::prepare('DELETE FROM `*PREFIX*share`'
@@ -1765,6 +1778,9 @@ class Share {
 		}
 	}
 
+	/**
+	 * @param array arguments
+	 */
 	public static function post_addToGroup($arguments) {
 		// Find the group shares and check if the user needs a unique target
 		$query = \OC_DB::prepare('SELECT * FROM `*PREFIX*share` WHERE `share_type` = ? AND `share_with` = ?');
@@ -1795,6 +1811,9 @@ class Share {
 		}
 	}
 
+	/**
+	 * @param array arguments
+	 */
 	public static function post_removeFromGroup($arguments) {
 		// TODO Don't call if user deleted?
 		$sql = 'SELECT `id`, `share_type` FROM `*PREFIX*share`'
@@ -1811,6 +1830,9 @@ class Share {
 		}
 	}
 
+	/**
+	 * @param array arguments
+	 */
 	public static function post_deleteGroup($arguments) {
 		$sql = 'SELECT `id` FROM `*PREFIX*share` WHERE `share_type` = ? AND `share_with` = ?';
 		$result = \OC_DB::executeAudited($sql, array(self::SHARE_TYPE_GROUP, $arguments['gid']));
@@ -1822,84 +1844,84 @@ class Share {
 }
 
 /**
-* Interface that apps must implement to share content.
-*/
+ * Interface that apps must implement to share content.
+ */
 interface Share_Backend {
 
 	/**
-	* Get the source of the item to be stored in the database
-	* @param string Item source
-	* @param string Owner of the item
-	* @return mixed|array|false Source
-	*
-	* Return an array if the item is file dependent, the array needs two keys: 'item' and 'file'
-	* Return false if the item does not exist for the user
-	*
-	* The formatItems() function will translate the source returned back into the item
-	*/
+	 * Get the source of the item to be stored in the database
+	 * @param string Item source
+	 * @param string Owner of the item
+	 * @return mixed|array|false Source
+	 *
+	 * Return an array if the item is file dependent, the array needs two keys: 'item' and 'file'
+	 * Return false if the item does not exist for the user
+	 *
+	 * The formatItems() function will translate the source returned back into the item
+	 */
 	public function isValidSource($itemSource, $uidOwner);
 
 	/**
-	* Get a unique name of the item for the specified user
-	* @param string Item source
-	* @param string|false User the item is being shared with
-	* @param array|null List of similar item names already existing as shared items
-	* @return string Target name
-	*
-	* This function needs to verify that the user does not already have an item with this name.
-	* If it does generate a new name e.g. name_#
-	*/
+	 * Get a unique name of the item for the specified user
+	 * @param string Item source
+	 * @param string|false User the item is being shared with
+	 * @param array|null List of similar item names already existing as shared items
+	 * @return string Target name
+	 *
+	 * This function needs to verify that the user does not already have an item with this name.
+	 * If it does generate a new name e.g. name_#
+	 */
 	public function generateTarget($itemSource, $shareWith, $exclude = null);
 
 	/**
-	* Converts the shared item sources back into the item in the specified format
-	* @param array Shared items
-	* @param int Format
-	* @return ?
-	*
-	* The items array is a 3-dimensional array with the item_source as the
-	* first key and the share id as the second key to an array with the share
-	* info.
-	*
-	* The key/value pairs included in the share info depend on the function originally called:
-	* If called by getItem(s)Shared: id, item_type, item, item_source,
-	* share_type, share_with, permissions, stime, file_source
-	*
-	* If called by getItem(s)SharedWith: id, item_type, item, item_source,
-	* item_target, share_type, share_with, permissions, stime, file_source,
-	* file_target
-	*
-	* This function allows the backend to control the output of shared items with custom formats.
-	* It is only called through calls to the public getItem(s)Shared(With) functions.
-	*/
+	 * Converts the shared item sources back into the item in the specified format
+	 * @param array Shared items
+	 * @param int Format
+	 * @return ?
+	 *
+	 * The items array is a 3-dimensional array with the item_source as the
+	 * first key and the share id as the second key to an array with the share
+	 * info.
+	 *
+	 * The key/value pairs included in the share info depend on the function originally called:
+	 * If called by getItem(s)Shared: id, item_type, item, item_source,
+	 * share_type, share_with, permissions, stime, file_source
+	 *
+	 * If called by getItem(s)SharedWith: id, item_type, item, item_source,
+	 * item_target, share_type, share_with, permissions, stime, file_source,
+	 * file_target
+	 *
+	 * This function allows the backend to control the output of shared items with custom formats.
+	 * It is only called through calls to the public getItem(s)Shared(With) functions.
+	 */
 	public function formatItems($items, $format, $parameters = null);
 
 }
 
 /**
-* Interface for share backends that share content that is dependent on files.
-* Extends the Share_Backend interface.
-*/
+ * Interface for share backends that share content that is dependent on files.
+ * Extends the Share_Backend interface.
+ */
 interface Share_Backend_File_Dependent extends Share_Backend {
 
 	/**
-	* Get the file path of the item
-	*/
+	 * Get the file path of the item
+	 */
 	public function getFilePath($itemSource, $uidOwner);
 
 }
 
 /**
-* Interface for collections of of items implemented by another share backend.
-* Extends the Share_Backend interface.
-*/
+ * Interface for collections of of items implemented by another share backend.
+ * Extends the Share_Backend interface.
+ */
 interface Share_Backend_Collection extends Share_Backend {
 
 	/**
-	* Get the sources of the children of the item
-	* @param string Item source
-	* @return array Returns an array of children each inside an array with the keys: source, target, and file_path if applicable
-	*/
+	 * Get the sources of the children of the item
+	 * @param string Item source
+	 * @return array Returns an array of children each inside an array with the keys: source, target, and file_path if applicable
+	 */
 	public function getChildren($itemSource);
 
 }