Public API documentation fixes

refs #4883

 * http/response.php
 * config.php
 * response.php
 * files.php
 * idbconnection.php
 * app.php
 * user.php
 * template.php
 * share.php
 * db.php
 * icache.php & il10n.php

12 files changed, 166 insertions, 167 deletions

diff --git a/lib/public/app.php b/lib/public/app.php
index 0a5721b334e..18681670ddd 100644
--- a/lib/public/app.php
+++ b/lib/public/app.php
@@ -35,14 +35,12 @@ namespace OCP;
  */
 class App {
 	/**
-	 * @brief Makes ownCloud aware of this app
-	 * @brief This call is deprecated and not necessary to use.
-	 * @param $data array with all information
-	 * @returns boolean
+	 * Makes ownCloud aware of this app
+	 * @param array with all information
+	 * @return boolean
 	 *
-	 * @deprecated this method is deprecated
-	 * Do not call it anymore
-	 * It'll remain in our public API for compatibility reasons
+	 * @deprecated This method is deprecated. Do not call it anymore.
+	 * It'll remain in our public API for compatibility reasons.
 	 *
 	 */
 	public static function register( $data ) {
@@ -50,9 +48,9 @@ class App {
 	}
 
 	/**
-	 * @brief adds an entry to the navigation
-	 * @param $data array containing the data
-	 * @returns boolean
+	 * Adds an entry to the navigation
+	 * @param array containing the data
+	 * @return boolean
 	 *
 	 * This function adds a new entry to the navigation visible to users. $data
 	 * is an associative array.
@@ -71,9 +69,9 @@ class App {
 	}
 
 	/**
-	 * @brief marks a navigation entry as active
-	 * @param $id string id of the entry
-	 * @returns boolean
+	 * Marks a navigation entry as active
+	 * @param string id of the entry
+	 * @return boolean
 	 *
 	 * This function sets a navigation entry as active and removes the 'active'
 	 * property from all other entries. The templates can use this for
@@ -84,7 +82,7 @@ class App {
 	}
 
 	/**
-	 * @brief Register a Configuration Screen that should appear in the personal settings section.
+	 * Register a Configuration Screen that should appear in the personal settings section.
 	 * @param $app string appid
 	 * @param $page string page to be included
 	*/
@@ -93,7 +91,7 @@ class App {
 	}
 
 	/**
-	 * @brief Register a Configuration Screen that should appear in the Admin section.
+	 * Register a Configuration Screen that should appear in the Admin section.
 	 * @param $app string appid
 	 * @param $page string page to be included
 	 */
@@ -102,19 +100,19 @@ class App {
 	}
 
 	/**
-	 * @brief Read app metadata from the info.xml file
+	 * Read app metadata from the info.xml file
 	 * @param string $app id of the app or the path of the info.xml file
 	 * @param boolean $path (optional)
-	 * @returns array
+	 * @return array
 	*/
 	public static function getAppInfo( $app, $path=false ) {
 		return \OC_App::getAppInfo( $app, $path);
 	}
 
 	/**
-	 * @brief checks whether or not an app is enabled
-	 * @param $app app
-	 * @returns boolean
+	 * checks whether or not an app is enabled
+	 * @param string
+	 * @return boolean
 	 *
 	 * This function checks whether or not an app is enabled.
 	 */
@@ -123,17 +121,17 @@ class App {
 	}
 
 	/**
-	 * @brief Check if the app is enabled, redirects to home if not
-	 * @param $app app
+	 * Check if the app is enabled, redirects to home if not
+	 * @param string
 	*/
 	public static function checkAppEnabled( $app ) {
 		\OC_Util::checkAppEnabled( $app );
 	}
 
 	/**
-	 * @brief Get the last version of the app, either from appinfo/version or from appinfo/info.xml
-	 * @param $app app
-	 * @returns boolean
+	 * Get the last version of the app, either from appinfo/version or from appinfo/info.xml
+	 * @param string
+	 * @return boolean
 	 */
 	public static function getAppVersion( $app ) {
 		return \OC_App::getAppVersion( $app );
diff --git a/lib/public/appframework/http/response.php b/lib/public/appframework/http/response.php
index 64477258948..5ca389b9946 100644
--- a/lib/public/appframework/http/response.php
+++ b/lib/public/appframework/http/response.php
@@ -26,12 +26,15 @@ namespace OCP\AppFramework\Http;
 
 
 /**
- * Base class for responses. Also used to just send headers
+ * Base class for responses. Also used to just send headers.
+ *
+ * It handles headers, HTTP status code, last modified and ETag.
  */
 class Response {
 
 	/**
-	 * @var array default headers
+	 * Headers - defaults to ['Cache-Control' => 'no-cache, must-revalidate']
+	 * @var array
 	 */
 	private $headers = array(
 		'Cache-Control' => 'no-cache, must-revalidate'
@@ -39,18 +42,21 @@ class Response {
 
 
 	/**
+	 * HTTP status code - defaults to STATUS OK
 	 * @var string
 	 */
 	private $status = Http::STATUS_OK;
 
 
 	/**
+	 * Last modified date
 	 * @var \DateTime
 	 */
 	private $lastModified;
 
 
 	/**
+	 * ETag
 	 * @var string
 	 */
 	private $ETag;
@@ -135,6 +141,7 @@ class Response {
 
 
 	/**
+	 * Get the ETag
 	 * @return string the etag
 	 */
 	public function getETag() {
@@ -143,6 +150,7 @@ class Response {
 
 
 	/**
+	 * Get "last modified" date
 	 * @return string RFC2822 formatted last modified date
 	 */
 	public function getLastModified() {
@@ -151,6 +159,7 @@ class Response {
 
 
 	/**
+	 * Set the ETag
 	 * @param string $ETag
 	 */
 	public function setETag($ETag) {
@@ -159,6 +168,7 @@ class Response {
 
 
 	/**
+	 * Set "last modified" date
 	 * @param \DateTime $lastModified
 	 */
 	public function setLastModified($lastModified) {
diff --git a/lib/public/config.php b/lib/public/config.php
index 73476d7551d..74aaa4e1891 100644
--- a/lib/public/config.php
+++ b/lib/public/config.php
@@ -40,7 +40,7 @@ namespace OCP;
  */
 class Config {
 	/**
-	 * @brief Gets a value from config.php
+	 * Gets a value from config.php
 	 * @param string $key key
 	 * @param string $default = null default value
 	 * @return string the value or $default
@@ -53,7 +53,7 @@ class Config {
 	}
 
 	/**
-	 * @brief Sets a value
+	 * Sets a value
 	 * @param string $key key
 	 * @param string $value value
 	 * @return bool
@@ -71,7 +71,7 @@ class Config {
 	}
 
 	/**
-	 * @brief Gets the config value
+	 * Gets the config value
 	 * @param string $app app
 	 * @param string $key key
 	 * @param string $default = null, default value if the key does not exist
@@ -85,7 +85,7 @@ class Config {
 	}
 
 	/**
-	 * @brief sets a value in the appconfig
+	 * Sets a value in the appconfig
 	 * @param string $app app
 	 * @param string $key key
 	 * @param string $value value
@@ -103,7 +103,7 @@ class Config {
 	}
 
 	/**
-	 * @brief Gets the preference
+	 * Gets the preference
 	 * @param string $user user
 	 * @param string $app app
 	 * @param string $key key
@@ -118,12 +118,12 @@ class Config {
 	}
 
 	/**
-	 * @brief sets a value in the preferences
+	 * Sets a value in the preferences
 	 * @param string $user user
 	 * @param string $app app
 	 * @param string $key key
 	 * @param string $value value
-	 * @returns bool
+	 * @return bool
 	 *
 	 * Adds a value to the preferences. If the key did not exist before, it
 	 * will be added automagically.
diff --git a/lib/public/db.php b/lib/public/db.php
index 9512cca2d19..fc6621f5b51 100644
--- a/lib/public/db.php
+++ b/lib/public/db.php
@@ -35,7 +35,7 @@ namespace OCP;
  */
 class DB {
 	/**
-	 * @brief Prepare a SQL query
+	 * Prepare a SQL query
 	 * @param string $query Query string
 	 * @return \MDB2_Statement_Common prepared SQL query
 	 *
@@ -46,7 +46,7 @@ class DB {
 	}
 
 	/**
-	 * @brief Insert a row if a matching row doesn't exists.
+	 * Insert a row if a matching row doesn't exists.
 	 * @param $table string The table name (will replace *PREFIX*) to perform the replace on.
 	 * @param $input array
 	 *
@@ -67,7 +67,7 @@ class DB {
 	}
 
 	/**
-	 * @brief gets last value of autoincrement
+	 * Gets last value of autoincrement
 	 * @param $table string The optional table name (will replace *PREFIX*) and add sequence suffix
 	 * @return int
 	 *
@@ -81,21 +81,21 @@ class DB {
 	}
 
 	/**
-	 * @brief Start a transaction
+	 * Start a transaction
 	 */
 	public static function beginTransaction() {
 		return(\OC_DB::beginTransaction());
 	}
 
 	/**
-	 * @brief Commit the database changes done during a transaction that is in progress
+	 * Commit the database changes done during a transaction that is in progress
 	 */
 	public static function commit() {
 		return(\OC_DB::commit());
 	}
 
 	/**
-	 * @brief check if a result is an error, works with MDB2 and PDOException
+	 * Check if a result is an error, works with MDB2 and PDOException
 	 * @param mixed $result
 	 * @return bool
 	 */
diff --git a/lib/public/files.php b/lib/public/files.php
index 852b041eefb..1e4c25c5ef1 100644
--- a/lib/public/files.php
+++ b/lib/public/files.php
@@ -36,9 +36,8 @@ namespace OCP;
  */
 class Files {
 	/**
-	 * @brief Recusive deletion of folders
-	 * @param string $dir path to the folder
-	 *
+	 * Recusive deletion of folders
+	 * @param string path to the folder
 	 * @return bool
 	 */
 	static function rmdirr( $dir ) {
@@ -46,7 +45,7 @@ class Files {
 	}
 
 	/**
-	 * get the mimetype form a local file
+	 * Get the mimetype form a local file
 	 * @param string path
 	 * @return string
 	 * does NOT work for ownClouds filesystem, use OC_FileSystem::getMimeType instead
@@ -56,17 +55,16 @@ class Files {
 	}
 
 	/**
-	 * search for files by mimetype
-	 *
-	 * @param string $query
+	 * Search for files by mimetype
+	 * @param string mimetype
 	 * @return array
 	 */
-	static public function searchByMime($mimetype) {
+	static public function searchByMime( $mimetype ) {
 		return(\OC\Files\Filesystem::searchByMime( $mimetype ));
 	}
 
 	/**
-	 * copy the contents of one stream to another
+	 * Copy the contents of one stream to another
 	 * @param resource source
 	 * @param resource target
 	 * @return int the number of bytes copied
@@ -77,7 +75,7 @@ class Files {
 	}
 
 	/**
-	 * create a temporary file with an unique filename
+	 * Create a temporary file with an unique filename
 	 * @param string postfix
 	 * @return string
 	 *
@@ -88,7 +86,7 @@ class Files {
 	}
 
 	/**
-	 * create a temporary folder with an unique filename
+	 * Create a temporary folder with an unique filename
 	 * @return string
 	 *
 	 * temporary files are automatically cleaned up after the script is finished
@@ -99,9 +97,8 @@ class Files {
 
 	/**
 	 * Adds a suffix to the name in case the file exists
-	 *
-	 * @param $path
-	 * @param $filename
+	 * @param string path
+	 * @param string filename
 	 * @return string
 	 */
 	public static function buildNotExistingFileName( $path, $filename ) {
@@ -109,8 +106,9 @@ class Files {
 	}
 
 	/**
+	 * Gets the Storage for an app - creates the needed folder if they are not
+	 * existant
 	 * @param string appid
-	 * @param $app app
 	 * @return \OC\Files\View
 	 */
 	public static function getStorage( $app ) {
diff --git a/lib/public/icache.php b/lib/public/icache.php
index 436ee71b2b9..a73004ec9a7 100644
--- a/lib/public/icache.php
+++ b/lib/public/icache.php
@@ -14,7 +14,6 @@ interface ICache {
 
 	/**
 	 * Get a value from the user cache
-	 *
 	 * @param string $key
 	 * @return mixed
 	 */
@@ -22,7 +21,6 @@ interface ICache {
 
 	/**
 	 * Set a value in the user cache
-	 *
 	 * @param string $key
 	 * @param mixed $value
 	 * @param int $ttl Time To Live in seconds. Defaults to 60*60*24
@@ -32,7 +30,6 @@ interface ICache {
 
 	/**
 	 * Check if a value is set in the user cache
-	 *
 	 * @param string $key
 	 * @return bool
 	 */
@@ -40,14 +37,13 @@ interface ICache {
 
 	/**
 	 * Remove an item from the user cache
-	 * 
 	 * @param string $key
 	 * @return bool
 	 */
 	public function remove($key);
 
 	/**
-	 * clear the user cache of all entries starting with a prefix
+	 * Clear the user cache of all entries starting with a prefix
 	 * @param string $prefix (optional)
 	 * @return bool
 	 */
diff --git a/lib/public/idbconnection.php b/lib/public/idbconnection.php
index c741a0f061a..252902eda6c 100644
--- a/lib/public/idbconnection.php
+++ b/lib/public/idbconnection.php
@@ -4,7 +4,7 @@
  * This file is licensed under the Affero General Public License version 3 or
  * later.
  * See the COPYING-README file.
- * 
+ *
  */
 
 namespace OCP;
@@ -30,9 +30,9 @@ interface IDBConnection {
 	public function lastInsertId($table = null);
 
 	/**
-	 * @brief Insert a row if a matching row doesn't exists.
-	 * @param $table string The table name (will replace *PREFIX*) to perform the replace on.
-	 * @param $input array
+	 * Insert a row if a matching row doesn't exists.
+	 * @param string The table name (will replace *PREFIX*) to perform the replace on.
+	 * @param array
 	 *
 	 * The input array if in the form:
 	 *
@@ -49,25 +49,25 @@ interface IDBConnection {
 	public function insertIfNotExist($table, $input);
 
 	/**
-	 * @brief Start a transaction
+	 * Start a transaction
 	 * @return bool TRUE on success or FALSE on failure
 	 */
 	public function beginTransaction();
 
 	/**
-	 * @brief Commit the database changes done during a transaction that is in progress
+	 * Commit the database changes done during a transaction that is in progress
 	 * @return bool TRUE on success or FALSE on failure
 	 */
 	public function commit();
 
 	/**
-	 * @brief Rollback the database changes done during a transaction that is in progress
+	 * Rollback the database changes done during a transaction that is in progress
 	 * @return bool TRUE on success or FALSE on failure
 	 */
 	public function rollBack();
 
 	/**
-	 * returns the error code and message as a string for logging
+	 * Gets the error code and message as a string for logging
 	 * @return string
 	 */
 	public function getError();
diff --git a/lib/public/il10n.php b/lib/public/il10n.php
index 9cf9093d391..805c8988aa2 100644
--- a/lib/public/il10n.php
+++ b/lib/public/il10n.php
@@ -14,7 +14,7 @@ namespace OCP;
  */
 interface IL10N {
 	/**
-	 * @brief Translating
+	 * Translating
 	 * @param $text String The text we need a translation for
 	 * @param array $parameters default:array() Parameters for sprintf
 	 * @return \OC_L10N_String|string Translation or the same text
@@ -25,7 +25,7 @@ interface IL10N {
 	public function t($text, $parameters = array());
 
 	/**
-	 * @brief Translating
+	 * Translating
 	 * @param $text_singular String the string to translate for exactly one object
 	 * @param $text_plural String the string to translate for n objects
 	 * @param $count Integer Number of objects
@@ -42,10 +42,10 @@ interface IL10N {
 	public function n($text_singular, $text_plural, $count, $parameters = array());
 
 	/**
-	 * @brief Localization
+	 * Localization
 	 * @param $type Type of localization
 	 * @param $params parameters for this localization
-	 * @returns String or false
+	 * @return String or false
 	 *
 	 * Returns the localized data.
 	 *
diff --git a/lib/public/response.php b/lib/public/response.php
index de0c3f25347..f7f6afcec95 100644
--- a/lib/public/response.php
+++ b/lib/public/response.php
@@ -35,7 +35,7 @@ namespace OCP;
  */
 class Response {
 	/**
-	* @brief Enable response caching by sending correct HTTP headers
+	* Enable response caching by sending correct HTTP headers
 	* @param int $cache_time time to cache the response
 	*  >0		cache time in seconds
 	*  0 and <0	enable default browser caching
@@ -55,7 +55,7 @@ class Response {
 	}
 
 	/**
-	* @brief disable browser caching
+	* Disable browser caching
 	* @see enableCaching with cache_time = 0
 	*/
 	static public function disableCaching() {
@@ -72,7 +72,7 @@ class Response {
 	}
 
 	/**
-	* @brief Send file as response, checking and setting caching headers
+	* Send file as response, checking and setting caching headers
 	* @param string $filepath of file to send
 	*/
 	static public function sendFile( $filepath ) {
@@ -80,7 +80,7 @@ class Response {
 	}
 
 	/**
-	* @brief Set response expire time
+	* Set response expire time
 	* @param string|\DateTime $expires date-time when the response expires
 	*  string for DateInterval from now
 	*  DateTime object when to expire response
@@ -90,7 +90,7 @@ class Response {
 	}
 
 	/**
-	* @brief Send redirect response
+	* Send redirect response
 	* @param string $location to redirect to
 	*/
 	static public function redirect( $location ) {
diff --git a/lib/public/share.php b/lib/public/share.php
index 66605dafee5..1b6f5d05f10 100644
--- a/lib/public/share.php
+++ b/lib/public/share.php
@@ -64,7 +64,7 @@ class Share {
 	private static $isResharingAllowed;
 
 	/**
-	* @brief Register a sharing backend class that implements OCP\Share_Backend for an item type
+	* 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
@@ -94,11 +94,10 @@ class Share {
 	}
 
 	/**
-	* @brief Check if the Share API is enabled
+	* 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') {
@@ -108,7 +107,7 @@ class Share {
 	}
 
 	/**
-	* @brief Prepare a path to be passed to DB as file_target
+	* Prepare a path to be passed to DB as file_target
 	* @return string Prepared path
 	*/
 	public static function prepFileTarget( $path ) {
@@ -125,7 +124,7 @@ class Share {
 	}
 
 	/**
-	* @brief Find which users can access a shared item
+	* 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
@@ -232,7 +231,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get the items of item type shared with the current user
+	* 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
@@ -245,7 +244,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get the item of item type shared with the current user
+	* 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
@@ -258,7 +257,7 @@ class Share {
 	}
 
 	/**
-	 * @brief Get the item of item type shared with a given user by source
+	 * Get the item of item type shared with a given user by source
 	 * @param string $ItemType
 	 * @param string $ItemSource
 	 * @param string $user User user to whom the item was shared
@@ -307,7 +306,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get the item of item type shared with the current user by source
+	* 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
@@ -320,7 +319,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get the item of item type shared by a link
+	* Get the item of item type shared by a link
 	* @param string Item type
 	* @param string Item source
 	* @param string Owner of link
@@ -332,7 +331,7 @@ class Share {
 	}
 
 	/**
-	 * @brief Get the item shared by a token
+	 * Get the item shared by a token
 	 * @param string token
 	 * @return Item
 	 */
@@ -357,7 +356,7 @@ class Share {
 	}
 
 	/**
-	 * @brief resolves reshares down to the last real share
+	 * resolves reshares down to the last real share
 	 * @param $linkItem
 	 * @return $fileOwner
 	 */
@@ -380,7 +379,7 @@ class Share {
 
 
 	/**
-	* @brief Get the shared items of item type owned by the current user
+	* 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
@@ -393,7 +392,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get the shared item of item type owned by the current user
+	* 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
@@ -429,7 +428,7 @@ class Share {
 	}
 
 	/**
-	* @brief Share an item with a user, group, or via private link
+	* Share an item with a user, group, or via private link
 	* @param string Item type
 	* @param string Item source
 	* @param int SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK
@@ -606,7 +605,7 @@ class Share {
 	}
 
 	/**
-	* @brief Unshare an item from a user, group, or delete a private link
+	* 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
@@ -639,7 +638,7 @@ class Share {
 	}
 
 	/**
-	* @brief Unshare an item from all users, groups, and remove all links
+	* 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
@@ -666,7 +665,7 @@ class Share {
 	}
 
 	/**
-	* @brief Unshare an item shared with the current user
+	* 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
@@ -703,7 +702,7 @@ class Share {
 		return false;
 	}
 	/**
-	 * @brief sent status if users got informed by mail about share
+	 * sent status if users got informed by mail about share
 	 * @param string $itemType
 	 * @param string $itemSource
 	 * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK
@@ -727,7 +726,7 @@ class Share {
 	}
 
 	/**
-	* @brief Set the permissions of an item for a specific user or group
+	* 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
@@ -831,7 +830,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get the backend class for the specified item type
+	* Get the backend class for the specified item type
 	* @param string $itemType
 	* @return Share_Backend
 	*/
@@ -860,7 +859,7 @@ class Share {
 	}
 
 	/**
-	* @brief Check if resharing is allowed
+	* Check if resharing is allowed
 	* @return Returns true if allowed or false
 	*
 	* Resharing is allowed by default if not configured
@@ -878,7 +877,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get a list of collection item types for the specified item type
+	* Get a list of collection item types for the specified item type
 	* @param string Item type
 	* @return array
 	*/
@@ -902,7 +901,7 @@ class Share {
 	}
 
 	/**
-	* @brief Get shared items from the database
+	* 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
@@ -1307,7 +1306,7 @@ class Share {
 	}
 
 	/**
-	* @brief Put shared item into the database
+	* 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
@@ -1543,7 +1542,7 @@ class Share {
 	}
 
 	/**
-	* @brief Generate a unique target for the item
+	* 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
@@ -1659,7 +1658,7 @@ class Share {
 	}
 
 	/**
-	* @brief Delete all reshares of an item
+	* 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)
@@ -1797,7 +1796,7 @@ class Share {
 interface Share_Backend {
 
 	/**
-	* @brief Get the source of the item to be stored in the database
+	* 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
@@ -1810,7 +1809,7 @@ interface Share_Backend {
 	public function isValidSource($itemSource, $uidOwner);
 
 	/**
-	* @brief Get a unique name of the item for the specified user
+	* 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
@@ -1822,7 +1821,7 @@ interface Share_Backend {
 	public function generateTarget($itemSource, $shareWith, $exclude = null);
 
 	/**
-	* @brief Converts the shared item sources back into the item in the specified format
+	* Converts the shared item sources back into the item in the specified format
 	* @param array Shared items
 	* @param int Format
 	* @return ?
@@ -1853,10 +1852,7 @@ interface Share_Backend {
 interface Share_Backend_File_Dependent extends Share_Backend {
 
 	/**
-	* @brief Get the file path of the item
-	* @param
-	* @param
-	* @return
+	* Get the file path of the item
 	*/
 	public function getFilePath($itemSource, $uidOwner);
 
@@ -1869,7 +1865,7 @@ interface Share_Backend_File_Dependent extends Share_Backend {
 interface Share_Backend_Collection extends Share_Backend {
 
 	/**
-	* @brief Get the sources of the children of the item
+	* 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
 	*/
diff --git a/lib/public/template.php b/lib/public/template.php
index a5c500b0e25..cf2dc7766f5 100644
--- a/lib/public/template.php
+++ b/lib/public/template.php
@@ -32,12 +32,12 @@ namespace OCP;
 
 
 /**
- * @brief make OC_Helper::imagePath available as a simple function
- * @param $app app
- * @param $image image
- * @returns link to the image
+ * Make OC_Helper::imagePath available as a simple function
+ * @param string app
+ * @param string image
+ * @return link to the image
  *
- * For further information have a look at OC_Helper::imagePath
+ * @see OC_Helper::imagePath
  */
 function image_path( $app, $image ) {
 	return(\image_path( $app, $image ));
@@ -45,40 +45,39 @@ function image_path( $app, $image ) {
 
 
 /**
- * @brief make OC_Helper::mimetypeIcon available as a simple function
- * Returns the path to the image of this file type.
- * @param $mimetype mimetype
- * @returns link to the image
+ * Make OC_Helper::mimetypeIcon available as a simple function
+ * @param string mimetype
+ * @return path to the image of this file type.
  */
 function mimetype_icon( $mimetype ) {
 	return(\mimetype_icon( $mimetype ));
 }
 
 /**
- * @brief make preview_icon available as a simple function
- * Returns the path to the preview of the image.
- * @param $path path of file
- * @returns link to the preview
+ * Make preview_icon available as a simple function
+ * @param string path of file
+ * @return path to the preview of the image
  */
 function preview_icon( $path ) {
 	return(\preview_icon( $path ));
 }
 
 /**
- * @brief make publicpreview_icon available as a simple function
+ * Make publicpreview_icon available as a simple function
  * Returns the path to the preview of the image.
- * @param $path path of file
- * @returns link to the preview
+ * @param string path of file
+ * @param string token
+ * @return link to the preview
  */
 function publicPreview_icon ( $path, $token ) {
 	return(\publicPreview_icon( $path, $token ));
 }
 
 /**
- * @brief make OC_Helper::humanFileSize available as a simple function
- * Makes 2048 to 2 kB.
- * @param $bytes size in bytes
- * @returns size as string
+ * Make OC_Helper::humanFileSize available as a simple function
+ * Example: 2048 to 2 kB.
+ * @param int size in bytes
+ * @return size as string
  */
 function human_file_size( $bytes ) {
 	return(\human_file_size( $bytes ));
@@ -86,20 +85,21 @@ function human_file_size( $bytes ) {
 
 
 /**
- * @brief Return the relative date in relation to today. Returns something like "last hour" or "two month ago"
- * @param $timestamp unix timestamp
- * @returns human readable interpretation of the timestamp
+ * Return the relative date in relation to today. Returns something like "last hour" or "two month ago"
+ * @param int unix timestamp
+ * @param boolean date only
+ * @return human readable interpretation of the timestamp
  */
-function relative_modified_date($timestamp, $dateOnly = false) {
+function relative_modified_date( $timestamp, $dateOnly = false ) {
 	return(\relative_modified_date($timestamp, null, $dateOnly));
 }
 
 
 /**
- * @brief DEPRECATED Return a human readable outout for a file size.
+ * Return a human readable outout for a file size.
  * @deprecated human_file_size() instead
- * @param $byte size of a file in byte
- * @returns human readable interpretation of a file size
+ * @param integer size of a file in byte
+ * @return human readable interpretation of a file size
  */
 function simple_file_size($bytes) {
 	return(\human_file_size($bytes));
@@ -107,11 +107,11 @@ function simple_file_size($bytes) {
 
 
 /**
- * @brief Generate html code for an options block.
+ * Generate html code for an options block.
  * @param $options the options
  * @param $selected which one is selected?
- * @param $params the parameters
- * @returns html options
+ * @param array the parameters
+ * @return html options
  */
 function html_select_options($options, $selected, $params=array()) {
 	return(\html_select_options($options, $selected, $params));
diff --git a/lib/public/user.php b/lib/public/user.php
index 576a64d7048..b4931ecc0fa 100644
--- a/lib/public/user.php
+++ b/lib/public/user.php
@@ -36,7 +36,7 @@ namespace OCP;
  */
 class User {
 	/**
-	 * @brief get the user id of the user currently logged in.
+	 * Get the user id of the user currently logged in.
 	 * @return string uid or false
 	 */
 	public static function getUser() {
@@ -44,45 +44,46 @@ class User {
 	}
 
 	/**
-	 * @brief Get a list of all users
-	 * @returns array with all uids
-	 *
-	 * Get a list of all users.
+	 * Get a list of all users
+	 * @param string search pattern
+	 * @param int limit
+	 * @param int offset
+	 * @return array with all uids
 	 */
-	public static function getUsers($search = '', $limit = null, $offset = null) {
-		return \OC_User::getUsers($search, $limit, $offset);
+	public static function getUsers( $search = '', $limit = null, $offset = null ) {
+		return \OC_User::getUsers( $search, $limit, $offset );
 	}
 
 	/**
-	 * @brief get the user display name of the user currently logged in.
+	 * Get the user display name of the user currently logged in.
+	 * @param string user id or null for current user
 	 * @return string display name
 	 */
-	public static function getDisplayName($user=null) {
-		return \OC_User::getDisplayName($user);
+	public static function getDisplayName( $user = null ) {
+		return \OC_User::getDisplayName( $user );
 	}
 
 	/**
-	 * @brief Get a list of all display names
-	 * @returns array with all display names (value) and the correspondig uids (key)
-	 *
 	 * Get a list of all display names and user ids.
+	 * @param string search pattern
+	 * @param int limit
+	 * @param int offset
+	 * @return array with all display names (value) and the correspondig uids (key)
 	 */
-	public static function getDisplayNames($search = '', $limit = null, $offset = null) {
-		return \OC_User::getDisplayNames($search, $limit, $offset);
+	public static function getDisplayNames( $search = '', $limit = null, $offset = null ) {
+		return \OC_User::getDisplayNames( $search, $limit, $offset );
 	}
 
 	/**
-	 * @brief Check if the user is logged in
-	 * @returns true/false
-	 *
-	 * Checks if the user is logged in
+	 * Check if the user is logged in
+	 * @return boolean
 	 */
 	public static function isLoggedIn() {
 		return \OC_User::isLoggedIn();
 	}
 
 	/**
-	 * @brief check if a user exists
+	 * Check if a user exists
 	 * @param string $uid the username
 	 * @param string $excludingBackend (default none)
 	 * @return boolean
@@ -91,7 +92,7 @@ class User {
 		return \OC_User::userExists( $uid, $excludingBackend );
 	}
 	/**
-	 * @brief Loggs the user out including all the session data
+	 * Logs the user out including all the session data
 	 * Logout, destroys session
 	 */
 	public static function logout() {
@@ -99,10 +100,10 @@ class User {
 	}
 
 	/**
-	 * @brief Check if the password is correct
-	 * @param $uid The username
-	 * @param $password The password
-	 * @returns mixed username on success, false otherwise
+	 * Check if the password is correct
+	 * @param string The username
+	 * @param string The password
+	 * @return mixed username on success, false otherwise
 	 *
 	 * Check if the password is correct without logging in the user
 	 */