[TASK] Clean up the phpDoc of t3lib/spritemanager/
authorWouter Wolters <typo3@wouterwolters.nl>
Tue, 29 May 2012 16:50:53 +0000 (18:50 +0200)
committerGeorg Ringer <mail@ringerge.org>
Wed, 30 May 2012 02:06:40 +0000 (04:06 +0200)
Clean up the phpDoc of t3lib/spritemanager/

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: Ib98dc3badbcdfb2fa36a1edee3d634f354be7781
Resolves: #37580
Releases: 6.0
Reviewed-on: http://review.typo3.org/11696
Reviewed-by: Georg Ringer
Tested-by: Georg Ringer
t3lib/spritemanager/class.t3lib_spritemanager_abstracthandler.php
t3lib/spritemanager/class.t3lib_spritemanager_simplehandler.php
t3lib/spritemanager/class.t3lib_spritemanager_spritebuildinghandler.php
t3lib/spritemanager/class.t3lib_spritemanager_spritegenerator.php

index a02532a..87f79bf 100644 (file)
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * An abstract class implementing t3lib_spritemanager_SpriteIconGenerator.
  * Provides base functionality for all handlers.
  *
- * @author     Steffen Ritter <info@steffen-ritter.net>
+ * @author Steffen Ritter <info@steffen-ritter.net>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -43,13 +42,13 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
 
        /**
         * contains the content of the CSS file to write
-        * @var String
+        * @var string
         */
        protected $styleSheetData = '';
 
        /**
         * path to CSS file for generated styles
-        * @var String
+        * @var string
         */
        protected $cssTcaFile = "";
 
@@ -57,8 +56,8 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
         * constructor just init's the temp-file-name
         * @return void
         */
-       function __construct() {
-                       // the file name is prefixed with "z" since the concatenator orders files per name
+       public function __construct() {
+                       // The file name is prefixed with "z" since the concatenator orders files per name
                $this->cssTcaFile = PATH_site . t3lib_SpriteManager::$tempPath . 'zextensions.css';
                $this->styleSheetData = '/* Auto-Generated via ' . get_class($this) . ' */' . LF;
        }
@@ -74,12 +73,12 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
         * @return void
         */
        protected function loadRegisteredSprites() {
-                       // saves which CSS Files are currently "allowed to be in place"
+                       // Saves which CSS Files are currently "allowed to be in place"
                $allowedCssFilesinTempDir = array(basename($this->cssTcaFile));
-                       // process every registeres file
+                       // Process every registeres file
                foreach ((array) $GLOBALS['TBE_STYLES']['spritemanager']['cssFiles'] as $file) {
                        $fileName = basename($file);
-                               // file should be present
+                               // File should be present
                        $allowedCssFilesinTempDir[] = $fileName;
                                // get-Cache Filename
                        $unique = md5($fileName . filemtime(PATH_site . $file) . filesize(PATH_site . $file));
@@ -88,7 +87,7 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
                                copy(PATH_site . $file, $cacheFile);
                        }
                }
-                       // get all .css files in dir
+                       // Get all .css files in dir
                $cssFilesPresentInTempDir = t3lib_div::getFilesInDir(PATH_site . t3lib_SpriteManager::$tempPath, '.css', 0);
                        // and delete old ones which are not needed anymore
                $filesToDelete = array_diff($cssFilesPresentInTempDir, $allowedCssFilesinTempDir);
@@ -104,10 +103,10 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
         * @return void
         */
        public function generate() {
-                       // include registered Sprites
+                       // Include registered Sprites
                $this->loadRegisteredSprites();
 
-                       // cache results in the CSS file
+                       // Cache results in the CSS file
                t3lib_div::writeFile($this->cssTcaFile, $this->styleSheetData);
        }
 
@@ -124,14 +123,14 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
         * this method creates sprite icon names for all tables in TCA (including their possible type-icons)
         * where there is no "typeicon_classes" of this TCA table ctrl section (moved form t3lib_iconWorks)
         *
-        * @return array array as $iconName => $fileName
+        * @return array Array as $iconName => $fileName
         */
        protected function collectTcaSpriteIcons() {
                $tcaTables = array_keys($GLOBALS['TCA']);
 
                $resultArray = array();
 
-                       // path (relative from typo3 dir) for skin-Images
+                       // Path (relative from typo3 dir) for skin-Images
                if (isset($GLOBALS['TBE_STYLES']['skinImgAutoCfg']['relDir'])) {
                        $skinPath = $GLOBALS['TBE_STYLES']['skinImgAutoCfg']['relDir'];
                } else {
@@ -141,14 +140,14 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
                        // check every table in the TCA, if an icon is needed
                foreach ($tcaTables as $tableName) {
 
-                               // this method is only needed for TCA tables where
+                               // This method is only needed for TCA tables where
                                // typeicon_classes are not configured
                        if (!is_array($GLOBALS['TCA'][$tableName]['ctrl']['typeicon_classes'])) {
                                $tcaCtrl = $GLOBALS['TCA'][$tableName]['ctrl'];
 
-                                       // adding the default Icon (without types)
+                                       // Adding the default Icon (without types)
                                if (isset($tcaCtrl['iconfile'])) {
-                                               // in CSS wie need a path relative to the css file
+                                               // In CSS we need a path relative to the css file
                                                // [TCA][ctrl][iconfile] defines icons without path info to reside in gfx/i/
                                        if (strpos($tcaCtrl['iconfile'], '/') !== FALSE) {
                                                $icon = $tcaCtrl['iconfile'];
@@ -161,11 +160,11 @@ abstract class t3lib_spritemanager_AbstractHandler implements t3lib_spritemanage
 
                                }
 
-                                       // if records types are available, register them
+                                       // If records types are available, register them
                                if (isset($tcaCtrl['typeicon_column']) && is_array($tcaCtrl['typeicons'])) {
                                        foreach ($tcaCtrl['typeicons'] as $type => $icon) {
 
-                                                       // in CSS wie need a path relative to the css file
+                                                       // In CSS we need a path relative to the css file
                                                        // [TCA][ctrl][iconfile] defines icons without path info to reside in gfx/i/
                                                if (strpos($icon, '/') === FALSE) {
                                                        $icon = $skinPath . 'gfx/i/' . $icon;
index 1012857..79478ae 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * A class with an concrete implementation of t3lib_spritemanager_SpriteIconGenerator.
  * It is the standard / fallback handler of the sprite manager.
@@ -33,7 +32,7 @@
  * for all registered icons so that they may be used through t3lib_iconWorks::getSpriteIcon*
  * Without the css classes generated here, icons of for example tca records would be empty.
  *
- * @author     Steffen Ritter <info@steffen-ritter.net>
+ * @author Steffen Ritter <info@steffen-ritter.net>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -41,7 +40,7 @@ class t3lib_spritemanager_SimpleHandler extends t3lib_spritemanager_AbstractHand
 
        /**
         * css template for single Icons registered by extension authors
-        * @var String
+        * @var string
         */
        protected $styleSheetTemplateExtIcons = '
 .t3-icon-###NAME### {
@@ -54,7 +53,7 @@ class t3lib_spritemanager_SimpleHandler extends t3lib_spritemanager_AbstractHand
         * constructor just init's the temp-file-name
         * @return void
         */
-       function __construct() {
+       public function __construct() {
                parent::__construct();
        }
 
@@ -66,13 +65,12 @@ class t3lib_spritemanager_SimpleHandler extends t3lib_spritemanager_AbstractHand
         */
        public function generate() {
 
-                       // generate IconData for single Icons registered
+                       // Generate IconData for single Icons registered
                $this->buildCssAndRegisterIcons();
 
                parent::generate();
        }
 
-
        /**
         * This function builds an css class for every single icon registered via
         * t3lib_SpriteManager::addSingleIcons to use them via t3lib_iconWorks::getSpriteIcon
@@ -82,7 +80,7 @@ class t3lib_spritemanager_SimpleHandler extends t3lib_spritemanager_AbstractHand
         * @return void
         */
        protected function buildCssAndRegisterIcons() {
-                       // backpath from the stylesheet file ($cssTcaFile) to PATH_site dir
+                       // Backpath from the stylesheet file ($cssTcaFile) to PATH_site dir
                        // in order to set the background-image URL paths correct
                $iconPath = '../../' . TYPO3_mainDir;
 
index 851dd2b..ac3a5ac 100644 (file)
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  *
- * @author     Steffen Ritter <info@steffen-ritter.net>
+ * @author Steffen Ritter <info@steffen-ritter.net>
  * @package TYPO3
  * @subpackage t3lib
  */
index 38fcf2d..8cfc3fd 100644 (file)
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
- * sprite generator
+ * Sprite generator
  *
- * @author     Steffen Ritter <info@steffen-ritter.net>
+ * @author Steffen Ritter <info@steffen-ritter.net>
  * @package TYPO3
  * @subpackage t3lib
  */
 
 class t3lib_spritemanager_SpriteGenerator {
        /**
-        * template creating CSS for the spritefile
+        * Template creating CSS for the spritefile
         *
         * @var string
         */
@@ -50,7 +49,7 @@ class t3lib_spritemanager_SpriteGenerator {
 
        /**
         *
-        * template creating CSS for position and size of a single icon
+        * Template creating CSS for position and size of a single icon
         *
         * @var string
         */
@@ -61,69 +60,69 @@ class t3lib_spritemanager_SpriteGenerator {
 ';
 
        /**
-        * most common icon-width in the sprite
+        * Most common icon-width in the sprite
         *
-        * @var int
+        * @var integer
         */
        protected $defaultWidth = 0;
 
        /**
-        * most common icon-height in the sprite
+        * Most common icon-height in the sprite
         *
-        * @var int
+        * @var integer
         */
        protected $defaultHeight = 0;
 
        /**
-        * calculated width of the sprite
+        * Calculated width of the sprite
         *
-        * @var int
+        * @var integer
         */
        protected $spriteWidth = 0;
 
        /**
-        * calculated height of the sprite
-        * @var int
+        * Calculated height of the sprite
+        * @var integer
         */
        protected $spriteHeight = 0;
 
        /**
-        * sprite name, will be the filename, too
+        * Sprite name, will be the filename, too
         *
         * @var string
         */
        protected $spriteName = '';
 
        /**
-        * the folder the sprite-images will be saved (relative to PATH_site)
+        * The folder the sprite-images will be saved (relative to PATH_site)
         *
         * @var string
         */
        protected $spriteFolder = 'typo3temp/sprites/';
 
        /**
-        * the folder the sprite-cs will be saved (relative to PATH_site)
+        * The folder the sprite-cs will be saved (relative to PATH_site)
         *
         * @var string
         */
        protected $cssFolder = 'typo3temp/sprites/';
 
        /**
-        * the spriteName will not be included in icon names
+        * The spriteName will not be included in icon names
         *
         * @var boolean
         */
        protected $ommitSpriteNameInIconName = FALSE;
 
        /**
-        * namespace of css classes
+        * Namespace of css classes
         *
         * @var string
         */
        protected $nameSpace = 't3-icon';
 
        /**
-        * setting this to TRUE, the timestamp of the creation will be included to the background import
+        * Setting this to TRUE, the timestamp of the creation will be included to the background import
         * helps to easily rebuild sprites without cache problems
         *
         * @var boolean
@@ -131,7 +130,7 @@ class t3lib_spritemanager_SpriteGenerator {
        protected $includeTimestampInCSS = TRUE;
 
        /**
-        * all bases/root-names included in the sprite which has to be in css
+        * All bases/root-names included in the sprite which has to be in css
         * as sprite to include the background-image
         *
         * @var array
@@ -139,21 +138,21 @@ class t3lib_spritemanager_SpriteGenerator {
        protected $spriteBases = array();
 
        /**
-        * collects data about all icons to process
+        * Collects data about all icons to process
         *
         * @var array
         */
        protected $iconsData = array();
 
        /**
-        * collects all sizes of icons within this sprite and there count
+        * Collects all sizes of icons within this sprite and there count
         *
         * @var array
         */
        protected $iconSizes = array();
 
        /**
-        * maps icon-sizes to iconnames
+        * Maps icon-sizes to iconnames
         *
         * @var array
         */
@@ -162,14 +161,14 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * space in px between to icons in the sprite (gap)
         *
-        * @var int
+        * @var integer
         */
        protected $space = 2;
 
        /**
         * Initializes the configuration of the spritegenerator
         *
-        * @param string $spriteName    the name of the sprite to be generated
+        * @param string $spriteName The name of the sprite to be generated
         * @return void
         */
        public function __construct($spriteName) {
@@ -179,8 +178,8 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * Sets namespace of css code
         *
-        * @param string $string
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @param string $nameSpace
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setNamespace($nameSpace) {
                $this->nameSpace = $nameSpace;
@@ -190,8 +189,8 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * Sets the spritename
         *
-        * @param string $spriteName    the name of the sprite to be generated
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @param string $spriteName The name of the sprite to be generated
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setSpriteName($spriteName) {
                $this->spriteName = $spriteName;
@@ -201,8 +200,8 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * Sets the sprite-graphics target-folder
         *
-        * @param string $folder the target folder where the generated sprite is stored
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @param string $folder The target folder where the generated sprite is stored
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setSpriteFolder($folder) {
                $this->spriteFolder = $folder;
@@ -213,7 +212,7 @@ class t3lib_spritemanager_SpriteGenerator {
         * Sets the sprite-css target-folder
         *
         * @param string $folder the target folder where the generated CSS files are stored
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setCSSFolder($folder) {
                $this->cssFolder = $folder;
@@ -224,7 +223,7 @@ class t3lib_spritemanager_SpriteGenerator {
         * Setter do enable the exclusion of the sprites-name from iconnames
         *
         * @param boolean $value
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setOmmitSpriteNameInIconName($value) {
                $this->ommitSpriteNameInIconName = is_bool($value) ? $value : FALSE;
@@ -234,8 +233,8 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * Setter to adjust how much space is between to icons in the sprite
         *
-        * @param int $value
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @param integer $value
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setIconSpace($value) {
                $this->space = intval($value);
@@ -246,7 +245,7 @@ class t3lib_spritemanager_SpriteGenerator {
         * Setter for timestamp inclusion: imageFiles will be included with ?timestamp
         *
         * @param boolean $value
-        * @return t3lib_spritemanager_SpriteGenerator  an instance of $this, to enable chaining.
+        * @return t3lib_spritemanager_SpriteGenerator An instance of $this, to enable chaining.
         */
        public function setIncludeTimestampInCSS($value) {
                $this->includeTimestampInCSS = is_bool($value) ? $value : TRUE;
@@ -258,13 +257,13 @@ class t3lib_spritemanager_SpriteGenerator {
         * extracts size information and stores data in internal array,
         * afterwards triggers sprite generation.
         *
-        * @param array $inputFolder folder from which files are read
-        * @return      array
+        * @param array $inputFolder Folder from which files are read
+        * @return array
         */
        public function generateSpriteFromFolder(array $inputFolder) {
                $iconArray = array();
                foreach ($inputFolder as $folder) {
-                               // detect all files to be included in sprites
+                               // Detect all files to be included in sprites
                        $iconArray = array_merge(
                                $iconArray,
                                $this->getFolder($folder)
@@ -287,7 +286,7 @@ class t3lib_spritemanager_SpriteGenerator {
                }
 
                $this->buildFileInformationCache($files);
-                       // calculate Icon Position in sprite
+                       // Calculate Icon Position in sprite
                $this->calculateSpritePositions();
 
                $this->generateGraphic();
@@ -397,10 +396,10 @@ class t3lib_spritemanager_SpriteGenerator {
                $filePath = array(
                        'mainFile' => PATH_site . $this->spriteFolder . $this->spriteName . '.png',
                );
-                       // create black true color image with given size
+                       // Create black true color image with given size
                $newSprite = imagecreatetruecolor($this->spriteWidth, $this->spriteHeight);
                imagesavealpha($newSprite, TRUE);
-                       // make it transparent
+                       // Make it transparent
                imagefill($newSprite, 0, 0, imagecolorallocatealpha($newSprite, 0, 255, 255, 127));
                foreach ($this->iconsData as $icon) {
                        $function = 'imagecreatefrom' . strtolower($icon['fileExtension']);
@@ -422,7 +421,7 @@ class t3lib_spritemanager_SpriteGenerator {
        protected function calculateSpritePositions() {
                $currentLeft = 0;
                $currentTop = 0;
-                       // calculate width of every icon-size-group
+                       // Calculate width of every icon-size-group
                $sizes = array();
                foreach ($this->iconSizes as $sizeTag => $count) {
                        $size = $this->explodeSizeTag($sizeTag);
@@ -432,9 +431,9 @@ class t3lib_spritemanager_SpriteGenerator {
                        }
                        $sizes[$rowWidth] = $sizeTag;
                }
-                       // reverse sorting: widest group to top
+                       // Reverse sorting: widest group to top
                krsort($sizes);
-                       // integerate all icons grouped by icons size into the sprite
+                       // Integerate all icons grouped by icons size into the sprite
                foreach ($sizes as $sizeTag) {
                        $size = $this->explodeSizeTag($sizeTag);
                        $currentLeft = 0;
@@ -476,8 +475,8 @@ class t3lib_spritemanager_SpriteGenerator {
         * Function getFolder traverses the target directory,
         * locates all iconFiles and collects them into an array
         *
-        * @param string path to an folder which contains images
-        * @return array returns an array with all files key: iconname, value: fileName
+        * @param string $directoryPath Path to an folder which contains images
+        * @return array Returns an array with all files key: iconname, value: fileName
         */
        protected function getFolder($directoryPath) {
                $subFolders = t3lib_div::get_dirs(PATH_site . $directoryPath);
@@ -510,7 +509,7 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * Generates file information cache from file array
         *
-        * @param array list of all files with their icon name
+        * @param array $files List of all files with their icon name
         * @return void
         */
        protected function buildFileInformationCache(array $files) {
@@ -544,7 +543,7 @@ class t3lib_spritemanager_SpriteGenerator {
                        }
                        $this->iconNamesPerSize[$sizeTag][] = $iconName;
                }
-                       // find most common image size, save it as default
+                       // Find most common image size, save it as default
                asort($this->iconSizes);
                $defaultSize = $this->explodeSizeTag(array_pop(array_keys($this->iconSizes)));
                $this->defaultWidth = $defaultSize['width'];
@@ -554,7 +553,7 @@ class t3lib_spritemanager_SpriteGenerator {
        /**
         * Transforms size tag into size array
         *
-        * @param string  a size tag at the cache arrays
+        * @param string $tag A size tag at the cache arrays
         * @return array
         */
        protected function explodeSizeTag($tag = '') {