[TASK] Clean up the phpDoc of t3lib/utility/
authorWouter Wolters <typo3@wouterwolters.nl>
Mon, 28 May 2012 20:09:32 +0000 (22:09 +0200)
committerGeorg Ringer <mail@ringerge.org>
Tue, 29 May 2012 04:20:45 +0000 (06:20 +0200)
Clean up the phpDoc of t3lib/utility/

So I made a patch doing mostly:

* Provide correct parameter names in phpDoc
* Provide correct data types in phpDoc
* CGLify phpDoc (remove tabs)
* CGLify method signatures (the first line of the method)

Change-Id: Iad4a09a537060499c93b055225588f95a7d9701b
Resolves: #37555
Releases: 6.0
Reviewed-on: http://review.typo3.org/11665
Reviewed-by: Georg Ringer
Tested-by: Georg Ringer
t3lib/utility/class.t3lib_utility_array.php
t3lib/utility/class.t3lib_utility_client.php
t3lib/utility/class.t3lib_utility_command.php
t3lib/utility/class.t3lib_utility_debug.php
t3lib/utility/class.t3lib_utility_http.php
t3lib/utility/class.t3lib_utility_mail.php
t3lib/utility/class.t3lib_utility_math.php
t3lib/utility/class.t3lib_utility_monitor.php
t3lib/utility/class.t3lib_utility_phpoptions.php
t3lib/utility/class.t3lib_utility_versionnumber.php

index 91914dc..d71c934 100644 (file)
@@ -63,7 +63,6 @@ final class t3lib_utility_Array {
         *
         * See the unit tests for more examples and expected behaviour
         *
-        * @static
         * @param mixed $needle The value to search for
         * @param array $haystack The array in which to search
         * @return array $haystack array reduced matching $needle values
index 31404cd..54a9278 100644 (file)
 /**
  * Class to handle and determine browser specific information.
  *
- * @author     Oliver Hader <oliver@typo3.org>
+ * @author Oliver Hader <oliver@typo3.org>
  */
 final class t3lib_utility_Client {
 
        /**
         * Generates an array with abstracted browser information
         *
-        * @param       string          $userAgent: The useragent string, t3lib_div::getIndpEnv('HTTP_USER_AGENT')
-        * @return      array           Contains keys "browser", "version", "system"
+        * @param string $userAgent The useragent string, t3lib_div::getIndpEnv('HTTP_USER_AGENT')
+        * @return array Contains keys "browser", "version", "system"
         */
        public static function getBrowserInfo($userAgent) {
                        // Hook: $TYPO3_CONF_VARS['SC_OPTIONS']['t3lib/div/class.t3lib_utility_client.php']['getBrowserInfo']:
@@ -66,7 +66,6 @@ final class t3lib_utility_Client {
 
                        // Analyze the userAgent string
                        // Declare known browsers to look for
-
                $known = array('msie', 'firefox', 'webkit', 'opera', 'netscape', 'konqueror',
                                        'gecko', 'chrome', 'safari', 'seamonkey', 'navigator', 'mosaic',
                                        'lynx', 'amaya', 'omniweb', 'avant', 'camino', 'flock', 'aol');
@@ -86,13 +85,13 @@ final class t3lib_utility_Client {
                        $lastIndex = count($matches['browser']) - 1;
                        $browserInfo['browser'] = $matches['browser'][$lastIndex];
                        $browserInfo['version'] = $browserInfo['browser'] === 'msie' ? $matches['version'][0] : $matches['version'][$lastIndex];
-                               //But return all parsed browsers / version in an extra array
+                               // But return all parsed browsers / version in an extra array
                        for ($i = 0; $i <= $lastIndex; $i++) {
                                if (!isset($browserInfo['all'][$matches['browser'][$i]])) {
                                        $browserInfo['all'][$matches['browser'][$i]] = $matches['version'][$i];
                                }
                        }
-                               //Replace gecko build date with version given by rv
+                               // Replace gecko build date with version given by rv
                        if (isset($browserInfo['all']['gecko'])) {
                                preg_match_all('/rv:([0-9\.]*)/', strtolower($userAgent), $version);
                                if ($version[1][0]) {
@@ -103,7 +102,7 @@ final class t3lib_utility_Client {
 
                $browserInfo['all_systems'] = array();
                if (strstr($userAgent, 'Win')) {
-                               // windows
+                               // Windows
                        if (strstr($userAgent, 'Windows NT 6.1')) {
                                $browserInfo['all_systems'][] = 'win7';
                                $browserInfo['all_systems'][] = 'winNT';
@@ -132,7 +131,7 @@ final class t3lib_utility_Client {
                        } else {
                                $browserInfo['all_systems'][] = 'mac';
                        }
-                               // unixes
+                       // Unixes
                } elseif (strstr($userAgent, 'Android')) {
                        $browserInfo['all_systems'][] = 'android';
                        $browserInfo['all_systems'][] = 'linux';
@@ -158,8 +157,8 @@ final class t3lib_utility_Client {
         * Returns the version of a browser; Basically getting doubleval() of the input string,
         * stripping of any non-numeric values in the beginning of the string first.
         *
-        * @param       string          $version: A string with version number, eg. "/7.32 blablabla"
-        * @return      double          Returns double value, eg. "7.32"
+        * @param string $version A string with version number, eg. "/7.32 blablabla"
+        * @return double Returns double value, eg. "7.32"
         */
        public static function getVersion($version) {
                return doubleval(preg_replace('/^[^0-9]*/', '', $version));
@@ -168,8 +167,8 @@ final class t3lib_utility_Client {
        /**
         * Gets a code for a browsing device based on the input useragent string.
         *
-        * @param       string          $userAgent: The useragent string, t3lib_div::getIndpEnv('HTTP_USER_AGENT')
-        * @return      string          Code for the specific device type
+        * @param string $userAgent The useragent string, t3lib_div::getIndpEnv('HTTP_USER_AGENT')
+        * @return string Code for the specific device type
         */
        public static function getDeviceType($userAgent) {
                        // Hook: $TYPO3_CONF_VARS['SC_OPTIONS']['t3lib/div/class.t3lib_utility_client.php']['getDeviceType']:
index 1b7a1d3..2b71a0f 100644 (file)
 /**
  * Class to handle system commands.
  *
- * @author     Steffen Kamper <steffen@typo3.org>
+ * @author Steffen Kamper <steffen@typo3.org>
  */
 final class t3lib_utility_Command {
 
-
        /**
         * Wrapper function for php exec function
         * Needs to be central to have better control and possible fix for issues
         *
         * @static
-        * @param  string  $command
-        * @param  NULL|array $output
-        * @param  integer $returnValue
+        * @param string $command
+        * @param NULL|array $output
+        * @param integer $returnValue
         * @return NULL|array
         */
        public static function exec($command, &$output = NULL, &$returnValue = 0) {
@@ -51,10 +50,10 @@ final class t3lib_utility_Command {
        /**
         * Compile the command for running ImageMagick/GraphicsMagick.
         *
-        * @param       string          Command to be run: identify, convert or combine/composite
-        * @param       string          The parameters string
-        * @param       string          Override the default path (e.g. used by the install tool)
-        * @return      string          Compiled command that deals with IM6 & GraphicsMagick
+        * @param string $command Command to be run: identify, convert or combine/composite
+        * @param string $parameters The parameters string
+        * @param string $path Override the default path (e.g. used by the install tool)
+        * @return string Compiled command that deals with IM6 & GraphicsMagick
         */
        public static function imageMagickCommand($command, $parameters, $path = '') {
                $gfxConf = $GLOBALS['TYPO3_CONF_VARS']['GFX'];
@@ -69,7 +68,8 @@ final class t3lib_utility_Command {
                $im_version = strtolower($gfxConf['im_version_5']);
                $combineScript = $gfxConf['im_combine_filename'] ? trim($gfxConf['im_combine_filename']) : 'combine';
 
-               if ($command === 'combine') { // This is only used internally, has no effect outside
+                       // This is only used internally, has no effect outside
+               if ($command === 'combine') {
                        $command = 'composite';
                }
 
@@ -98,10 +98,13 @@ final class t3lib_utility_Command {
 
                $cmdLine = $path . ' ' . $parameters;
 
-               if ($command == 'composite' && $switchCompositeParameters) { // Because of some weird incompatibilities between ImageMagick 4 and 6 (plus GraphicsMagick), it is needed to change the parameters order under some preconditions
+                       // Because of some weird incompatibilities between ImageMagick 4 and 6 (plus GraphicsMagick),
+                       // it is needed to change the parameters order under some preconditions
+               if ($command == 'composite' && $switchCompositeParameters) {
                        $paramsArr = t3lib_div::unQuoteFilenames($parameters);
 
-                       if (count($paramsArr) > 5) { // The mask image has been specified => swap the parameters
+                               // The mask image has been specified => swap the parameters
+                       if (count($paramsArr) > 5) {
                                $tmp = $paramsArr[count($paramsArr) - 3];
                                $paramsArr[count($paramsArr) - 3] = $paramsArr[count($paramsArr) - 4];
                                $paramsArr[count($paramsArr) - 4] = $tmp;
@@ -112,7 +115,6 @@ final class t3lib_utility_Command {
 
                return $cmdLine;
        }
-
 }
 
 ?>
\ No newline at end of file
index 431a5c9..7fb0eee 100644 (file)
@@ -29,7 +29,7 @@
  * Class to handle debug
  *
  *
- * @author      Steffen Kamper <steffen@typo3.org>
+ * @author Steffen Kamper <steffen@typo3.org>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -54,6 +54,14 @@ final class t3lib_utility_Debug {
        ';
 
 
+       /**
+        * Debug
+        *
+        * @param string $var
+        * @param string $header
+        * @param string $group
+        * @return void
+        */
        public static function debug($var = '', $header = '', $group = 'Debug') {
                        // buffer the output of debug if no buffering started before
                if (ob_get_level() == 0) {
@@ -216,7 +224,7 @@ final class t3lib_utility_Debug {
        /**
         * Displays the "path" of the function call stack in a string, using debug_backtrace
         *
-        * @return      string
+        * @return string
         */
        public static function debugTrail() {
                $trail = debug_backtrace();
@@ -239,10 +247,10 @@ final class t3lib_utility_Debug {
        /**
         * Displays an array as rows in a table. Useful to debug output like an array of database records.
         *
-        * @param       mixed           Array of arrays with similar keys
-        * @param       string          Table header
-        * @param       boolean         If TRUE, will return content instead of echo'ing out.
-        * @return      void            Outputs to browser.
+        * @param mixed $rows Array of arrays with similar keys
+        * @param string $header Table header
+        * @param boolean $returnHTML If TRUE, will return content instead of echo'ing out.
+        * @return void Outputs to browser.
         */
        public static function debugRows($rows, $header = '', $returnHTML = FALSE) {
                if (is_array($rows)) {
@@ -283,13 +291,10 @@ final class t3lib_utility_Debug {
                                        </table>';
                                if ($returnHTML) {
                                        return $table;
-                               }
-                               else
-                               {
+                               } else {
                                        echo $table;
                                }
-                       } else
-                       {
+                       } else {
                                debug('Empty array of rows', $header);
                        }
                } else {
@@ -300,9 +305,9 @@ final class t3lib_utility_Debug {
        /**
         * Returns a string with a list of ascii-values for the first $characters characters in $string
         *
-        * @param       string          String to show ASCII value for
-        * @param       integer         Number of characters to show
-        * @return      string          The string with ASCII values in separated by a space char.
+        * @param string $string String to show ASCII value for
+        * @param integer $characters Number of characters to show
+        * @return string The string with ASCII values in separated by a space char.
         */
        public static function ordinalValue($string, $characters = 100) {
                if (strlen($string) < $characters) {
@@ -319,8 +324,8 @@ final class t3lib_utility_Debug {
         * use t3lib_div::print_array() in order to print an array
         * Returns FALSE if $array_in is not an array
         *
-        * @param       mixed           Array to view
-        * @return      string          HTML output
+        * @param mixed $array_in Array to view
+        * @return string HTML output
         */
        public static function viewArray($array_in) {
                if (is_array($array_in)) {
@@ -367,16 +372,17 @@ final class t3lib_utility_Debug {
                                        nl2br(htmlspecialchars((string) $array_in)) .
                                        '<br /></font></td>
                                </tr>
-                       </table>'; // Output it as a string.
+                       </table>';
                }
+                       // Output it as a string.
                return $result;
        }
 
        /**
         * Prints an array
         *
-        * @param       mixed           Array to print visually (in a table).
-        * @return      void
+        * @param mixed $array_in Array to print visually (in a table).
+        * @return void
         * @see viewArray()
         */
        public static function printArray($array_in) {
index aa6925c..c6d7e54 100644 (file)
@@ -26,7 +26,7 @@
 /**
  * HTTP Utility class
  *
- * @author     Ingo Renner <ingo@typo3.org>
+ * @author Ingo Renner <ingo@typo3.org>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -88,8 +88,8 @@ class t3lib_utility_Http {
         * Location redirect header. By default the HTTP status code sent is
         * a 'HTTP/1.1 303 See Other'.
         *
-        * @param       string  The target URL to redirect to
-        * @param       string  An optional HTTP status header. Default is 'HTTP/1.1 303 See Other'
+        * @param string $url The target URL to redirect to
+        * @param string $httpStatus An optional HTTP status header. Default is 'HTTP/1.1 303 See Other'
         */
        public static function redirect($url, $httpStatus = self::HTTP_STATUS_303) {
                header($httpStatus);
index 7c216ee..35dc26a 100644 (file)
@@ -29,7 +29,7 @@
  * Class to handle mail specific functionality
  *
  *
- * @author      Tolleiv Nietsch <nietsch@aoemedia.de>
+ * @author Tolleiv Nietsch <nietsch@aoemedia.de>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -40,14 +40,14 @@ final class t3lib_utility_Mail {
         * The hook can be used by adding function to the configuration array:
         * $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/utility/class.t3lib_utility_mail.php']['substituteMailDelivery']
         *
-        * @param       string          Email address to send to.
-        * @param       string          Subject line, non-encoded. (see PHP function mail())
-        * @param       string          Message content, non-encoded. (see PHP function mail())
-        * @param       string           Additional headers for the mail (see PHP function mail())
-        * @param       string          Additional flags for the sending mail tool (see PHP function mail())
-        * @return      boolean         Indicates whether the mail has been sent or not
-        * @see         PHP function mail() []
-        * @link        http://www.php.net/manual/en/function.mail.php
+        * @param string $to Email address to send to.
+        * @param string $subject Subject line, non-encoded. (see PHP function mail())
+        * @param string $messageBody Message content, non-encoded. (see PHP function mail())
+        * @param string $additionalHeaders Additional headers for the mail (see PHP function mail())
+        * @param string $additionalParameters Additional flags for the sending mail tool (see PHP function mail())
+        * @return boolean Indicates whether the mail has been sent or not
+        * @see PHP function mail() []
+        * @link http://www.php.net/manual/en/function.mail.php
         */
        public static function mail($to, $subject, $messageBody, $additionalHeaders = NULL, $additionalParameters = NULL) {
                $success = TRUE;
@@ -154,7 +154,7 @@ final class t3lib_utility_Mail {
         *
         * Ready to be passed to $mail->setFrom() (t3lib_mail)
         *
-        * @return      string  An email address
+        * @return string An email address
         */
        public static function getSystemFromAddress() {
                        // default, first check the localconf setting
@@ -177,7 +177,7 @@ final class t3lib_utility_Mail {
                                if (!t3lib_div::isFirstPartOfStr($tempUrl, 'http')) {
                                                // shouldn't be the case anyways, but you never know
                                                // ... there're crazy people out there
-                                       $tempUrl = 'http://' .$tempUrl;
+                                       $tempUrl = 'http://' . $tempUrl;
                                }
                                $host = parse_url($tempUrl, PHP_URL_HOST);
                        }
@@ -204,7 +204,7 @@ final class t3lib_utility_Mail {
         * @param string $str The string to break up
         * @param string $newlineChar The string to implode the broken lines with (default/typically \n)
         * @param integer $lineWidth The line width
-        * @return string reformated text
+        * @return string Reformated text
         */
        public static function breakLinesForEmail($str, $newlineChar = LF, $lineWidth = 76) {
                $lines = array();
index 4bbdd26..1e2124f 100644 (file)
  * @package TYPO3
  * @subpackage t3lib
  */
-
 final class t3lib_utility_Math {
 
        /**
         * Forces the integer $theInt into the boundaries of $min and $max. If the $theInt is FALSE then the $defaultValue is applied.
         *
-        * @param $theInt integer Input value
-        * @param $min integer Lower limit
-        * @param $max integer Higher limit
-        * @param $defaultValue integer Default value if input is FALSE.
+        * @param integer $theInt Input value
+        * @param integer $min Lower limit
+        * @param integer $max Higher limit
+        * @param integer $defaultValue Default value if input is FALSE.
         * @return integer The input value forced into the boundaries of $min and $max
         */
        public static function forceIntegerInRange($theInt, $min, $max = 2000000000, $defaultValue = 0) {
                        // Returns $theInt as an integer in the integerspace from $min to $max
                $theInt = intval($theInt);
+                       // If the input value is zero after being converted to integer,
+                       // defaultValue may set another default value for it.
                if ($defaultValue && !$theInt) {
                        $theInt = $defaultValue;
-               } // If the input value is zero after being converted to integer, defaultValue may set another default value for it.
+               }
+
                if ($theInt < $min) {
                        $theInt = $min;
                }
@@ -61,7 +63,7 @@ final class t3lib_utility_Math {
        /**
         * Returns $theInt if it is greater than zero, otherwise returns zero.
         *
-        * @param $theInt integer Integer string to process
+        * @param integer $theInt Integer string to process
         * @return integer
         */
        public static function convertToPositiveInteger($theInt) {
@@ -78,7 +80,7 @@ final class t3lib_utility_Math {
         * Note: Integer casting from objects or arrays is considered undefined and thus will return false.
         * @see http://php.net/manual/en/language.types.integer.php#language.types.integer.casting.from-other
         *
-        * @param $var mixed Any input variable to test
+        * @param mixed $var Any input variable to test
         * @return boolean Returns TRUE if string is an integer
         */
        public static function canBeInterpretedAsInteger($var) {
@@ -91,16 +93,18 @@ final class t3lib_utility_Math {
        /**
         * Calculates the input by +,-,*,/,%,^ with priority to + and -
         *
-        * @param $string string Input string, eg "123 + 456 / 789 - 4"
+        * @param string $string Input string, eg "123 + 456 / 789 - 4"
         * @return integer Calculated value. Or error string.
         * @see t3lib_utility_Math::calculateWithParentheses()
         */
        public static function calculateWithPriorityToAdditionAndSubtraction($string) {
-               $string = preg_replace('/[[:space:]]*/', '', $string); // removing all whitespace
-               $string = '+' . $string; // Ensuring an operator for the first entrance
+                       // Removing all whitespace
+               $string = preg_replace('/[[:space:]]*/', '', $string);
+                       // Ensuring an operator for the first entrance
+               $string = '+' . $string;
                $qm = '\*\/\+-^%';
                $regex = '([' . $qm . '])([' . $qm . ']?[0-9\.]*)';
-                       // split the expression here:
+                       // Split the expression here:
                $reg = array();
                preg_match_all('/' . $regex . '/', $string, $reg);
 
@@ -109,7 +113,8 @@ final class t3lib_utility_Math {
                $Msign = '+';
                $err = '';
                $buffer = doubleval(current($reg[2]));
-               next($reg[2]); // Advance pointer
+                       // Advance pointer
+               next($reg[2]);
 
                while (list($k, $v) = each($reg[2])) {
                        $v = doubleval($v);
@@ -148,7 +153,7 @@ final class t3lib_utility_Math {
        /**
         * Calculates the input with parenthesis levels
         *
-        * @param $string string Input string, eg "(123 + 456) / 789 - 4"
+        * @param string $string Input string, eg "(123 + 456) / 789 - 4"
         * @return integer Calculated value. Or error string.
         * @see calculateWithPriorityToAdditionAndSubtraction(), tslib_cObj::stdWrap()
         */
index b594f04..14f7f66 100644 (file)
@@ -28,7 +28,7 @@
 /**
  * Class to handle monitoring actions.
  *
- * @author     Jigal van Hemert <jigal@xs4all.nl>
+ * @author Jigal van Hemert <jigal@xs4all.nl>
  */
 final class t3lib_utility_Monitor {
 
index 3475dc3..7214a3c 100644 (file)
@@ -28,7 +28,7 @@
 /**
  * Class to handle php environment specific options / functions
  *
- * @author      Christian Kuhn <lolli@schwarzbu.ch>
+ * @author Christian Kuhn <lolli@schwarzbu.ch>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -78,6 +78,7 @@ final class t3lib_utility_PhpOptions {
        /**
         * Cast a on/off php ini value to boolean
         *
+        * @param string $configOption
         * @return boolean TRUE if the given option is enabled, FALSE if disabled
         */
        public static function getIniValueBoolean($configOption) {
index 1f4107f..d145473 100644 (file)
@@ -37,7 +37,7 @@ final class t3lib_utility_VersionNumber {
        /**
         * Returns an integer from a three part version number, eg '4.12.3' -> 4012003
         *
-        * @param $versionNumber string Version number on format x.x.x
+        * @param string $versionNumber Version number on format x.x.x
         * @return integer Integer version of version number (where each part can count to 999)
         */
        public static function convertVersionNumberToInteger($versionNumber) {
@@ -48,7 +48,7 @@ final class t3lib_utility_VersionNumber {
        /**
         * Returns the three part version number (string) from an integer, eg 4012003 -> '4.12.3'
         *
-        * @param $versionInteger integer Integer representation of version number
+        * @param integer $versionInteger Integer representation of version number
         * @return string Version number as format x.x.x
         * @throws \InvalidArgumentException if $versionInteger is not an integer
         */