Add @since tags to all methods in public namespace

* enhance the app development experience - you can look up the
  method introduction right inside the code without searching
  via git blame
* easier to write apps for multiple versions

1 files changed, 54 insertions, 8 deletions

diff --git a/lib/public/util.php b/lib/public/util.php
index 721bcaadb62..626c98022e3 100644
--- a/lib/public/util.php
+++ b/lib/public/util.php
@@ -51,6 +51,7 @@ use DateTimeZone;
 
 /**
  * This class provides different helper functions to make the life of a developer easier
+ * @since 4.0.0
  */
 class Util {
 	// consts for Logging
@@ -63,6 +64,7 @@ class Util {
 	/**
 	 * get the current installed version of ownCloud
 	 * @return array
+	 * @since 4.0.0
 	 */
 	public static function getVersion() {
 		return(\OC_Util::getVersion());
@@ -82,6 +84,7 @@ class Util {
 	 * @param string $ccname
 	 * @param string $bcc
 	 * @deprecated Use \OCP\Mail\IMailer instead
+	 * @since 4.0.0
 	 */
 	public static function sendMail($toaddress, $toname, $subject, $mailtext, $fromaddress, $fromname,
 		$html = 0, $altbody = '', $ccaddress = '', $ccname = '', $bcc = '') {
@@ -122,6 +125,7 @@ class Util {
 	 * @param string $app
 	 * @param string $message
 	 * @param int $level
+	 * @since 4.0.0
 	 */
 	public static function writeLog( $app, $message, $level ) {
 		// call the internal log class
@@ -133,6 +137,7 @@ class Util {
 	 * @param string $app app name
 	 * @param \Exception $ex exception to log
 	 * @param int $level log level, defaults to \OCP\Util::FATAL
+	 * @since ....0.0 - parameter $level was added in 7.0.0
 	 */
 	public static function logException( $app, \Exception $ex, $level = \OCP\Util::FATAL ) {
 		$exception = array(
@@ -149,6 +154,7 @@ class Util {
 	 * check if sharing is disabled for the current user
 	 *
 	 * @return boolean
+	 * @since 7.0.0
 	 */
 	public static function isSharingDisabledForUser() {
 		return \OC_Util::isSharingDisabledForUser();
@@ -159,6 +165,7 @@ class Util {
 	 * @param string $application
 	 * @param string|null $language
 	 * @return \OC_L10N
+	 * @since 6.0.0 - parameter $language was added in 8.0.0
 	 */
 	public static function getL10N($application, $language = null) {
 		return \OC::$server->getL10N($application, $language);
@@ -168,6 +175,7 @@ class Util {
 	 * add a css file
 	 * @param string $application
 	 * @param string $file
+	 * @since 4.0.0
 	 */
 	public static function addStyle( $application, $file = null ) {
 		\OC_Util::addStyle( $application, $file );
@@ -177,6 +185,7 @@ class Util {
 	 * add a javascript file
 	 * @param string $application
 	 * @param string $file
+	 * @since 4.0.0
 	 */
 	public static function addScript( $application, $file = null ) {
 		\OC_Util::addScript( $application, $file );
@@ -186,6 +195,7 @@ class Util {
 	 * Add a translation JS file
 	 * @param string $application application id
 	 * @param string $languageCode language code, defaults to the current locale
+	 * @since 8.0.0
 	 */
 	public static function addTranslations($application, $languageCode = null) {
 		\OC_Util::addTranslations($application, $languageCode);
@@ -198,6 +208,7 @@ class Util {
 	 * @param string $tag tag name of the element
 	 * @param array $attributes array of attributes for the element
 	 * @param string $text the text content for the element
+	 * @since 4.0.0
 	 */
 	public static function addHeader($tag, $attributes, $text=null) {
 		\OC_Util::addHeader($tag, $attributes, $text);
@@ -211,6 +222,7 @@ class Util {
 	 * @return string timestamp
 	 *
 	 * @deprecated Use \OC::$server->query('DateTimeFormatter') instead
+	 * @since 4.0.0
 	 */
 	public static function formatDate($timestamp, $dateOnly=false, $timeZone = null) {
 		return(\OC_Util::formatDate($timestamp, $dateOnly, $timeZone));
@@ -221,6 +233,7 @@ class Util {
 	 * @return bool
 	 *
 	 * @deprecated No longer required
+	 * @since 6.0.0
 	 */
 	public static function encryptedFiles() {
 		return false;
@@ -233,6 +246,7 @@ class Util {
 	 * @param array $args array with param=>value, will be appended to the returned url
 	 * 	The value of $args will be urlencoded
 	 * @return string the url
+	 * @since 4.0.0 - parameter $args was added in 4.5.0
 	 */
 	public static function linkToAbsolute( $app, $file, $args = array() ) {
 		return(\OC_Helper::linkToAbsolute( $app, $file, $args ));
@@ -242,6 +256,7 @@ class Util {
 	 * Creates an absolute url for remote use.
 	 * @param string $service id
 	 * @return string the url
+	 * @since 4.0.0
 	 */
 	public static function linkToRemote( $service ) {
 		return(\OC_Helper::linkToRemote( $service ));
@@ -251,6 +266,7 @@ class Util {
 	 * Creates an absolute url for public use
 	 * @param string $service id
 	 * @return string the url
+	 * @since 4.5.0
 	 */
 	public static function linkToPublic($service) {
 		return \OC_Helper::linkToPublic($service);
@@ -263,20 +279,22 @@ class Util {
 	 * @internal param array $args with param=>value, will be appended to the returned url
 	 * @return string the url
 	 * @deprecated Use \OC::$server->getURLGenerator()->linkToRoute($route, $parameters)
+	 * @since 5.0.0
 	 */
 	public static function linkToRoute( $route, $parameters = array() ) {
 		return \OC_Helper::linkToRoute($route, $parameters);
 	}
 
 	/**
-	* Creates an url to the given app and file
-	* @param string $app app
-	* @param string $file file
-	* @param array $args array with param=>value, will be appended to the returned url
-	* 	The value of $args will be urlencoded
-	* @return string the url
-	* @deprecated Use \OC::$server->getURLGenerator()->linkTo($app, $file, $args)
-	*/
+	 * Creates an url to the given app and file
+	 * @param string $app app
+	 * @param string $file file
+	 * @param array $args array with param=>value, will be appended to the returned url
+	 * 	The value of $args will be urlencoded
+	 * @return string the url
+	 * @deprecated Use \OC::$server->getURLGenerator()->linkTo($app, $file, $args)
+	 * @since 4.0.0 - parameter $args was added in 4.5.0
+	 */
 	public static function linkTo( $app, $file, $args = array() ) {
 		return(\OC_Helper::linkTo( $app, $file, $args ));
 	}
@@ -285,6 +303,7 @@ class Util {
 	 * Returns the server host, even if the website uses one or more reverse proxy
 	 * @return string the server host
 	 * @deprecated Use \OCP\IRequest::getServerHost
+	 * @since 4.0.0
 	 */
 	public static function getServerHost() {
 		return \OC::$server->getRequest()->getServerHost();
@@ -293,6 +312,7 @@ class Util {
 	/**
 	 * Returns the server host name without an eventual port number
 	 * @return string the server hostname
+	 * @since 5.0.0
 	 */
 	public static function getServerHostName() {
 		$host_name = self::getServerHost();
@@ -318,6 +338,7 @@ class Util {
 	 * If the configuration value 'mail_from_address' is set in
 	 * config.php, this value will override the $user_part that
 	 * is passed to this function
+	 * @since 5.0.0
 	 */
 	public static function getDefaultEmailAddress($user_part) {
 		$user_part = \OC_Config::getValue('mail_from_address', $user_part);
@@ -338,6 +359,7 @@ class Util {
 	 * Returns the server protocol. It respects reverse proxy servers and load balancers
 	 * @return string the server protocol
 	 * @deprecated Use \OCP\IRequest::getServerProtocol
+	 * @since 4.5.0
 	 */
 	public static function getServerProtocol() {
 		return \OC::$server->getRequest()->getServerProtocol();
@@ -347,6 +369,7 @@ class Util {
 	 * Returns the request uri, even if the website uses one or more reverse proxies
 	 * @return string the request uri
 	 * @deprecated Use \OCP\IRequest::getRequestUri
+	 * @since 5.0.0
 	 */
 	public static function getRequestUri() {
 		return \OC::$server->getRequest()->getRequestUri();
@@ -356,6 +379,7 @@ class Util {
 	 * Returns the script name, even if the website uses one or more reverse proxies
 	 * @return string the script name
 	 * @deprecated Use \OCP\IRequest::getScriptName
+	 * @since 5.0.0
 	 */
 	public static function getScriptName() {
 		return \OC::$server->getRequest()->getScriptName();
@@ -367,6 +391,7 @@ class Util {
 	 * @param string $image image name
 	 * @return string the url
 	 * @deprecated Use \OC::$server->getURLGenerator()->imagePath($app, $image)
+	 * @since 4.0.0
 	 */
 	public static function imagePath( $app, $image ) {
 		return(\OC_Helper::imagePath( $app, $image ));
@@ -376,6 +401,7 @@ class Util {
 	 * Make a human file size (2048 to 2 kB)
 	 * @param int $bytes file size in bytes
 	 * @return string a human readable file size
+	 * @since 4.0.0
 	 */
 	public static function humanFileSize( $bytes ) {
 		return(\OC_Helper::humanFileSize( $bytes ));
@@ -387,6 +413,7 @@ class Util {
 	 * @return int a file size in bytes
 	 *
 	 * Inspired by: http://www.php.net/manual/en/function.filesize.php#92418
+	 * @since 4.0.0
 	 */
 	public static function computerFileSize( $str ) {
 		return(\OC_Helper::computerFileSize( $str ));
@@ -404,6 +431,7 @@ class Util {
 	 * This function makes it very easy to connect to use hooks.
 	 *
 	 * TODO: write example
+	 * @since 4.0.0
 	 */
 	static public function connectHook($signalClass, $signalName, $slotClass, $slotName ) {
 		return(\OC_Hook::connect($signalClass, $signalName, $slotClass, $slotName ));
@@ -417,6 +445,7 @@ class Util {
 	 * @return bool true if slots exists or false if not
 	 *
 	 * TODO: write example
+	 * @since 4.0.0
 	 */
 	static public function emitHook( $signalclass, $signalname, $params = array()) {
 		return(\OC_Hook::emit( $signalclass, $signalname, $params ));
@@ -425,6 +454,7 @@ class Util {
 	/**
 	 * Register an get/post call. This is important to prevent CSRF attacks
 	 * TODO: write example
+	 * @since 4.5.0
 	 */
 	public static function callRegister() {
 		return(\OC_Util::callRegister());
@@ -433,6 +463,7 @@ class Util {
 	/**
 	 * Check an ajax get/post call if the request token is valid. exit if not.
 	 * Todo: Write howto
+	 * @since 4.5.0
 	 */
 	public static function callCheck() {
 		\OC_Util::callCheck();
@@ -446,6 +477,7 @@ class Util {
 	 *
 	 * @param string|array $value
 	 * @return string|array an array of sanitized strings or a single sinitized string, depends on the input parameter.
+	 * @since 4.5.0
 	 */
 	public static function sanitizeHTML( $value ) {
 		return(\OC_Util::sanitizeHTML($value));
@@ -460,6 +492,7 @@ class Util {
 	 *
 	 * @param string $component part of URI to encode
 	 * @return string
+	 * @since 6.0.0
 	 */
 	public static function encodePath($component) {
 		return(\OC_Util::encodePath($component));
@@ -472,6 +505,7 @@ class Util {
 	 * @param int $case Either MB_CASE_UPPER or MB_CASE_LOWER (default)
 	 * @param string $encoding The encoding parameter is the character encoding. Defaults to UTF-8
 	 * @return array
+	 * @since 4.5.0
 	 */
 	public static function mb_array_change_key_case($input, $case = MB_CASE_LOWER, $encoding = 'UTF-8') {
 		return(\OC_Helper::mb_array_change_key_case($input, $case, $encoding));
@@ -486,6 +520,7 @@ class Util {
 	 * @param int $length Length of the part to be replaced
 	 * @param string $encoding The encoding parameter is the character encoding. Defaults to UTF-8
 	 * @return string
+	 * @since 4.5.0
 	 */
 	public static function mb_substr_replace($string, $replacement, $start, $length = null, $encoding = 'UTF-8') {
 		return(\OC_Helper::mb_substr_replace($string, $replacement, $start, $length, $encoding));
@@ -500,6 +535,7 @@ class Util {
 	 * @param string $encoding The encoding parameter is the character encoding. Defaults to UTF-8
 	 * @param int $count If passed, this will be set to the number of replacements performed.
 	 * @return string
+	 * @since 4.5.0
 	 */
 	public static function mb_str_replace($search, $replace, $subject, $encoding = 'UTF-8', &$count = null) {
 		return(\OC_Helper::mb_str_replace($search, $replace, $subject, $encoding, $count));
@@ -512,6 +548,7 @@ class Util {
 	 * @param string $needle the search string
 	 * @param int $index optional, only search this key name
 	 * @return mixed the key of the matching field, otherwise false
+	 * @since 4.5.0
 	 */
 	public static function recursiveArraySearch($haystack, $needle, $index = null) {
 		return(\OC_Helper::recursiveArraySearch($haystack, $needle, $index));
@@ -523,6 +560,7 @@ class Util {
 	 * @param string $dir the current folder where the user currently operates
 	 * @param int $free the number of bytes free on the storage holding $dir, if not set this will be received from the storage directly
 	 * @return int number of bytes representing
+	 * @since 5.0.0
 	 */
 	public static function maxUploadFilesize($dir, $free = null) {
 		return \OC_Helper::maxUploadFilesize($dir, $free);
@@ -532,6 +570,7 @@ class Util {
 	 * Calculate free space left within user quota
 	 * @param string $dir the current folder where the user currently operates
 	 * @return int number of bytes representing
+	 * @since 7.0.0
 	 */
 	public static function freeSpace($dir) {
 		return \OC_Helper::freeSpace($dir);
@@ -541,6 +580,7 @@ class Util {
 	 * Calculate PHP upload limit
 	 *
 	 * @return int number of bytes representing
+	 * @since 7.0.0
 	 */
 	public static function uploadLimit() {
 		return \OC_Helper::uploadLimit();
@@ -551,6 +591,7 @@ class Util {
 	 * @param string $file file name to check
 	 * @return bool true if the file name is valid, false otherwise
 	 * @deprecated use \OC\Files\View::verifyPath()
+	 * @since 7.0.0
 	 */
 	public static function isValidFileName($file) {
 		return \OC_Util::isValidFileName($file);
@@ -561,6 +602,7 @@ class Util {
 	 * @param int $length of the random string
 	 * @return string
 	 * @deprecated Use \OC::$server->getSecureRandom()->getMediumStrengthGenerator()->generate($length); instead
+	 * @since 7.0.0
 	 */
 	public static function generateRandomBytes($length = 30) {
 		return \OC_Util::generateRandomBytes($length);
@@ -572,6 +614,7 @@ class Util {
 	 * @param string $b second string to compare
 	 * @return -1 if $b comes before $a, 1 if $a comes before $b
 	 * or 0 if the strings are identical
+	 * @since 7.0.0
 	 */
 	public static function naturalSortCompare($a, $b) {
 		return \OC\NaturalSort::getInstance()->compare($a, $b);
@@ -580,6 +623,7 @@ class Util {
 	/**
 	 * check if a password is required for each public link
 	 * @return boolean
+	 * @since 7.0.0
 	 */
 	public static function isPublicLinkPasswordRequired() {
 		return \OC_Util::isPublicLinkPasswordRequired();
@@ -588,6 +632,7 @@ class Util {
 	/**
 	 * check if share API enforces a default expire date
 	 * @return boolean
+	 * @since 8.0.0
 	 */
 	public static function isDefaultExpireDateEnforced() {
 		return \OC_Util::isDefaultExpireDateEnforced();
@@ -598,6 +643,7 @@ class Util {
 	 * Checks whether the current version needs upgrade.
 	 *
 	 * @return bool true if upgrade is needed, false otherwise
+	 * @since 7.0.0
 	 */
 	public static function needUpgrade() {
 		return \OC_Util::needUpgrade(\OC::$server->getConfig());