[TASK] Clean up phpDoc comments in t3lib classes
authorWouter Wolters <typo3@wouterwolters.nl>
Thu, 31 May 2012 19:05:52 +0000 (21:05 +0200)
committerGeorg Ringer <mail@ringerge.org>
Fri, 1 Jun 2012 13:50:33 +0000 (15:50 +0200)
Clean up phpDoc comments for the following classes:

* t3lib/collection/AbstractRecordCollection.php
* t3lib/collection/RecordCollectionRepository.php
* t3lib/collection/StaticRecordCollection.php
* t3lib/collection/interfaces/interface.t3lib_collection_collection.php
* t3lib/collection/interfaces/interface.t3lib_collection_editable.php
* t3lib/collection/interfaces/interface.t3lib_collection_nameable.php
* t3lib/collection/interfaces/interface.t3lib_collection_persistable.php
* t3lib/collection/interfaces/
  interface.t3lib_collection_recordcollection.php
* t3lib/collection/interfaces/interface.t3lib_collection_sortable.php
* t3lib/contextmenu/class.t3lib_contextmenu_abstractdataprovider.php
* t3lib/contextmenu/extdirect/
  class.t3lib_contextmenu_extdirect_contextmenu.php
* t3lib/contextmenu/pagetree/extdirect/
  class.t3lib_contextmenu_pagetree_extdirect_contextmenu.php
* t3lib/contextmenu/renderer/
  class.t3lib_contextmenu_renderer_abstract.php
* t3lib/db/class.t3lib_db_preparedstatement.php

Clean up provides:

* Provide correct parameter names in phpDoc
* Provide correct data types in phpDoc
* CGLify phpDoc (remove tabs)

Change-Id: I88a02a918318894bc83656a2af6f11768fe9d917
Resolves: #37659
Releases: 6.0
Reviewed-on: http://review.typo3.org/11776
Reviewed-by: Georg Ringer
Tested-by: Georg Ringer
14 files changed:
t3lib/collection/AbstractRecordCollection.php
t3lib/collection/RecordCollectionRepository.php
t3lib/collection/StaticRecordCollection.php
t3lib/collection/interfaces/interface.t3lib_collection_collection.php
t3lib/collection/interfaces/interface.t3lib_collection_editable.php
t3lib/collection/interfaces/interface.t3lib_collection_nameable.php
t3lib/collection/interfaces/interface.t3lib_collection_persistable.php
t3lib/collection/interfaces/interface.t3lib_collection_recordcollection.php
t3lib/collection/interfaces/interface.t3lib_collection_sortable.php
t3lib/contextmenu/class.t3lib_contextmenu_abstractdataprovider.php
t3lib/contextmenu/extdirect/class.t3lib_contextmenu_extdirect_contextmenu.php
t3lib/contextmenu/pagetree/extdirect/class.t3lib_contextmenu_pagetree_extdirect_contextmenu.php
t3lib/contextmenu/renderer/class.t3lib_contextmenu_renderer_abstract.php
t3lib/db/class.t3lib_db_preparedstatement.php

index 68f5a85..6204e87 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Abstract implementation of a RecordCollection
  *
@@ -39,7 +38,6 @@
  * The AbstractRecordCollection uses SplDoublyLinkedList for internal storage
  *
  * @author Steffen Ritter <typo3@steffen-ritter.net>
- * @abstract
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -61,7 +59,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        /**
         * Uid of the storage
         *
-        * @var int
+        * @var integer
         */
        protected $uid = 0;
 
@@ -101,7 +99,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Return the current element
         *
         * @link http://php.net/manual/en/iterator.current.php
@@ -112,7 +110,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Move forward to next element
         *
         * @link http://php.net/manual/en/iterator.next.php
@@ -123,12 +121,11 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Return the key of the current element
         *
         * @link http://php.net/manual/en/iterator.key.php
-        * @return integer
-        * 0 on failure.
+        * @return integer 0 on failure.
         */
        public function key() {
                $currentRecord = $this->storage->current();
@@ -136,7 +133,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Checks if current position is valid
         *
         * @link http://php.net/manual/en/iterator.valid.php
@@ -148,7 +145,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Rewind the Iterator to the first element
         *
         * @link http://php.net/manual/en/iterator.rewind.php
@@ -159,7 +156,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * String representation of object
         *
         * @link http://php.net/manual/en/serializable.serialize.php
@@ -173,13 +170,11 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Constructs the object
         *
         * @link http://php.net/manual/en/serializable.unserialize.php
-        * @param string $serialized <p>
-        * The string representation of the object.
-        * </p>
+        * @param string $serialized The string representation of the object
         * @return mixed the original value unserialized.
         */
        public function unserialize($serialized) {
@@ -188,13 +183,11 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        }
 
        /**
-        * (PHP 5 &gt;= 5.1.0)<br/>
+        * (PHP 5 >= 5.1.0)
         * Count elements of an object
         *
         * @link http://php.net/manual/en/countable.count.php
-        * @return int The custom count as an integer.
-        * </p>
-        * <p>
+        * @return integer The custom count as an integer.
         * The return value is cast to an integer.
         */
        public function count() {
@@ -213,7 +206,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        /**
         * Getter for the UID
         *
-        * @return int
+        * @return integer
         */
        public function getUid() {
                return $this->uid;
@@ -288,8 +281,8 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
         * the item at $currentPosition will be moved to
         * $newPosition. Ommiting $newPosition will move to top.
         *
-        * @param int $currentPosition
-        * @param int $newPosition
+        * @param integer $currentPosition
+        * @param integer $newPosition
         * @return void
         */
        public function moveItemAt($currentPosition, $newPosition = 0) {
@@ -297,7 +290,6 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
                throw new RuntimeException('This method is not yet supported.', 1322545626);
        }
 
-
        /**
         * Returns the uid of the collection
         *
@@ -310,14 +302,13 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
        /**
         * Sets the identifier of the collection
         *
-        * @param int $id
+        * @param integer $id
         * @return void
         */
        public function setIdentifier($id) {
                $this->uid = intval($id);
        }
 
-
        /**
         * Loads the collections with the given id from persistence
         *
@@ -325,7 +316,6 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
         * identifier (what ever static data is defined) is loaded.
         * Entries can be load on first access.
         *
-        * @static
         * @param integer $id Id of database record to be loaded
         * @param boolean $fillItems Populates the entries directly on load, might be bad for memory on large collections
         * @return t3lib_collection_Collection
@@ -346,9 +336,8 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
         * Creates a new collection objects and reconstitutes the
         * given database record to the new object.
         *
-        * @static
         * @param array $collectionRecord Database record
-        * @param bool $fillItems Populates the entries directly on load, might be bad for memory on large collections
+        * @param boolean $fillItems Populates the entries directly on load, might be bad for memory on large collections
         * @return t3lib_collection_Collection
         */
        public static function create(array $collectionRecord, $fillItems = FALSE) {
@@ -374,7 +363,7 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
                                $uid => $this->getPersistableDataArray()
                        )
                );
-                       // new records always must have a pid
+                       // New records always must have a pid
                if ($this->getIdentifier() == 0) {
                        $data[trim(static::$storageTableName)][$uid]['pid'] = 0;
                }
@@ -390,9 +379,8 @@ abstract class t3lib_collection_AbstractRecordCollection implements t3lib_collec
         * Returns an array of the persistable properties and contents
         * which are processable by TCEmain.
         *
-        * for internal usage in persist only.
+        * For internal usage in persist only.
         *
-        * @abstract
         * @return array
         */
        abstract protected function getPersistableDataArray();
index a357577..634e448 100644 (file)
@@ -131,6 +131,7 @@ class t3lib_collection_RecordCollectionRepository {
         * Deletes a record collection by uid.
         *
         * @param integer $uid uid to be deleted
+        * @return void
         */
        public function deleteByUid($uid) {
                $this->getDatabase()->exec_UPDATEquery(
index ebb0316..3d0e14c 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Implementation of a RecordCollection for static TCA-Records
  *
@@ -38,9 +37,8 @@ class t3lib_collection_StaticRecordCollection extends t3lib_collection_AbstractR
         * Creates a new collection objects and reconstitutes the
         * given database record to the new object.
         *
-        * @static
         * @param array $collectionRecord Database record
-        * @param bool $fillItems Populates the entries directly on load, might be bad for memory on large collections
+        * @param boolean $fillItems Populates the entries directly on load, might be bad for memory on large collections
         * @return t3lib_collection_StaticRecordCollection
         */
        public static function create(array $collectionRecord, $fillItems = FALSE) {
@@ -162,7 +160,6 @@ class t3lib_collection_StaticRecordCollection extends t3lib_collection_AbstractR
         *
         * collection will be empty afterwards
         *
-        * @abstract
         * @return void
         */
        public function removeAll() {
index 2513a67..196b40f 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Marker interface for collection classes
  *
index 717bcb6..f40c2b9 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Interface for collection classes which es enabled to be modified
  *
@@ -38,7 +37,6 @@ interface t3lib_collection_Editable {
        /**
         * Adds on entry to the collection
         *
-        * @abstract
         * @param mixed $data
         * @return void
         */
@@ -47,7 +45,6 @@ interface t3lib_collection_Editable {
        /**
         * Adds a set of entries to the collection
         *
-        * @abstract
         * @param t3lib_collection_Collection $other
         * @return void
         */
@@ -58,7 +55,6 @@ interface t3lib_collection_Editable {
         *
         * Note: not the given "index"
         *
-        * @abstract
         * @param mixed $data
         * @return void
         */
@@ -69,7 +65,6 @@ interface t3lib_collection_Editable {
         *
         * collection will be empty afterwards
         *
-        * @abstract
         * @return void
         */
        public function removeAll();
index 6ff82a6..21bc4ee 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Marker interface for a collection class with title and description
  *
@@ -43,7 +42,6 @@ interface t3lib_collection_Nameable {
        /**
         * Setter for the title
         *
-        * @abstract
         * @param string $title
         * @return void
         */
@@ -52,7 +50,6 @@ interface t3lib_collection_Nameable {
        /**
         * Setter for the description
         *
-        * @abstract
         * @param string $description
         * @return void
         */
@@ -61,7 +58,6 @@ interface t3lib_collection_Nameable {
        /**
         * Getter for the title
         *
-        * @abstract
         * @return string
         */
        public function getTitle();
@@ -69,7 +65,6 @@ interface t3lib_collection_Nameable {
        /**
         * Getter for the description
         *
-        * @abstract
         * @return void
         */
        public function getDescription();
index 24d05a2..9857fb3 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Interface for collection class being persistable
  *
@@ -47,16 +46,14 @@ interface t3lib_collection_Persistable {
         * session stored, registry stored or other collections might
         * use a string as well
         *
-        * @abstract
-        * @return int|string
+        * @return integer|string
         */
        public function getIdentifier();
 
        /**
         * Sets the identifier of the collection
         *
-        * @abstract
-        * @param int|string $id
+        * @param integer|string $id
         * @return void
         */
        public function setIdentifier($id);
@@ -68,9 +65,7 @@ interface t3lib_collection_Persistable {
         * identifier (what ever static data is defined) is loaded.
         * Entries can be load on first access.
         *
-        * @static
-        * @abstract
-        * @param int|string $id
+        * @param integer|string $id
         * @param boolean $fillItems Populates the entries directly on load, might be bad for memory on large collections
         * @return t3lib_collection_Collection
         */
@@ -79,7 +74,6 @@ interface t3lib_collection_Persistable {
        /**
         * Persists current collection state to underlying storage
         *
-        * @abstract
         * @return void
         */
        public function persist();
@@ -94,7 +88,6 @@ interface t3lib_collection_Persistable {
         * ($fillItems = false) this function is to be used for loading the contents
         * afterwards.
         *
-        * @abstract
         * @return void
         */
        public function loadContents();
index efd1fc3..aec4361 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Collection for handling records from a single database-table.
  *
@@ -38,7 +37,6 @@ interface t3lib_collection_RecordCollection extends t3lib_collection_Collection,
        /**
         * Setter for the name of the data-source table
         *
-        * @abstract
         * @param string $tableName
         * @return void
         */
@@ -47,7 +45,6 @@ interface t3lib_collection_RecordCollection extends t3lib_collection_Collection,
        /**
         * Setter for the name of the data-source table
         *
-        * @abstract
         * @return string
         */
        public function getItemTableName();
index e026762..1551d9f 100644 (file)
@@ -25,7 +25,6 @@
  *  This copyright notice MUST APPEAR in all copies of the script!
  ***************************************************************/
 
-
 /**
  * Interface for collection class being sortable
  *
@@ -47,7 +46,6 @@ interface t3lib_collection_Sortable {
         * The comparison function given as must return an integer less than, equal to, or greater than
         * zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
         *
-        * @abstract
         * @param $callbackFunction
         * @see http://www.php.net/manual/en/function.usort.php
         * @return void
@@ -60,9 +58,8 @@ interface t3lib_collection_Sortable {
         * The item at $currentPosition will be moved to
         * $newPosition. Ommiting $newPosition will move to top.
         *
-        * @abstract
-        * @param int $currentPosition
-        * @param int $newPosition
+        * @param integer $currentPosition
+        * @param integer $newPosition
         * @return void
         */
        public function moveItemAt($currentPosition, $newPosition = 0);
index 1a6be04..ff99651 100644 (file)
@@ -104,7 +104,7 @@ abstract class t3lib_contextmenu_AbstractDataProvider {
                        return TRUE;
                }
 
-                       // parse condition string
+                       // Parse condition string
                $conditions = array();
                preg_match_all('/(.+?)(>=|<=|!=|=|>|<)(.+?)(\|\||&&|$)/is', $displayCondition, $conditions);
 
@@ -112,20 +112,20 @@ abstract class t3lib_contextmenu_AbstractDataProvider {
                $chainType = '';
                $amountOfConditions = count($conditions[0]);
                for ($i = 0; $i < $amountOfConditions; ++$i) {
-                               // check method for existence
+                               // Check method for existence
                        $method = trim($conditions[1][$i]);
                        list($method, $index) = explode('|', $method);
                        if (!method_exists($node, $method)) {
                                continue;
                        }
 
-                               // fetch compare value
+                               // Fetch compare value
                        $returnValue = call_user_func(array($node, $method));
                        if (is_array($returnValue)) {
                                $returnValue = $returnValue[$index];
                        }
 
-                               // compare fetched and expected values
+                               // Compare fetched and expected values
                        $operator = trim($conditions[2][$i]);
                        $expected = trim($conditions[3][$i]);
                        if ($operator === '=') {
@@ -145,7 +145,7 @@ abstract class t3lib_contextmenu_AbstractDataProvider {
                                $lastResult = FALSE;
                        }
 
-                               // chain last result and the current if requested
+                               // Chain last result and the current if requested
                        if ($chainType === '||') {
                                $lastResult = ($lastResult || $returnValue);
                        } elseif ($chainType === '&&') {
@@ -154,7 +154,7 @@ abstract class t3lib_contextmenu_AbstractDataProvider {
                                $lastResult = $returnValue;
                        }
 
-                               // save chain type for the next condition
+                               // Save chain type for the next condition
                        $chainType = trim($conditions[4][$i]);
                }
 
@@ -166,7 +166,7 @@ abstract class t3lib_contextmenu_AbstractDataProvider {
         *
         * @param array $actions
         * @param t3lib_tree_Node $node
-        * @param int $level
+        * @param integer $level
         * @return t3lib_contextmenu_ActionCollection
         */
        protected function getNextContextMenuLevel(array $actions, t3lib_tree_Node $node, $level = 0) {
index c15e040..73f5f2d 100644 (file)
@@ -47,7 +47,7 @@ abstract class t3lib_contextmenu_extdirect_ContextMenu extends t3lib_contextmenu
         * of the node should be given, because we need this information
         * to create the ndoe.
         *
-        * @param stdClass $nodeInfo
+        * @param stdClass $nodeData
         * @return array
         */
        public function getActionsForNodeArray($nodeData) {
index 0c50437..c0ef277 100644 (file)
@@ -47,7 +47,7 @@ class t3lib_contextmenu_pagetree_extdirect_ContextMenu extends t3lib_contextmenu
        /**
         * Returns the actions for the given node information's
         *
-        * @param stdClass $node
+        * @param stdClass $nodeData
         * @return array
         */
        public function getActionsForNodeArray($nodeData) {
index 4287ee3..f1498c4 100644 (file)
@@ -37,7 +37,7 @@ abstract class t3lib_contextmenu_renderer_Abstract {
         * Renders an action recursive or just a single one
         *
         * @param t3lib_contextmenu_Action $action
-        * @param bool $recursive
+        * @param boolean $recursive
         * @return mixed
         */
        abstract public function renderAction(t3lib_contextmenu_Action $action, $recursive = FALSE);
@@ -46,7 +46,7 @@ abstract class t3lib_contextmenu_renderer_Abstract {
         * Renders an action collection recursive or just a single one
         *
         * @param t3lib_contextmenu_ActionCollection $actionCollection
-        * @param bool $recursive
+        * @param boolean $recursive
         * @return mixed
         */
        abstract public function renderActionCollection(
@@ -57,7 +57,7 @@ abstract class t3lib_contextmenu_renderer_Abstract {
         * Renders a context menu recursive or just a single one
         *
         * @param t3lib_contextmenu_AbstractContextMenu $contextMenu
-        * @param bool $recursive
+        * @param boolean $recursive
         * @return mixed
         */
        abstract public function renderContextMenu(
index 0652fcd..c8d8a09 100644 (file)
@@ -39,7 +39,7 @@
  * $statement->free();
  * </code>
  *
- * @author     Xavier Perseguers <typo3@perseguers.ch>
+ * @author Xavier Perseguers <typo3@perseguers.ch>
  * @package TYPO3
  * @subpackage t3lib
  */
@@ -143,7 +143,7 @@ class t3lib_db_PreparedStatement {
         * This constructor may only be used by t3lib_DB.
         *
         * @param string $query SQL query to be executed
-        * @param string FROM table, used to call $GLOBALS['TYPO3_DB']->fullQuoteStr().
+        * @param string $table FROM table, used to call $GLOBALS['TYPO3_DB']->fullQuoteStr().
         * @param array $precompiledQueryParts Components of the query to be executed
         * @access private
         */
@@ -486,10 +486,10 @@ class t3lib_db_PreparedStatement {
        /**
         * Replace the markers with unpredictable token markers.
         *
-        * @throws InvalidArgumentException
         * @param string $query
         * @param array $parameterValues
         * @return string
+        * @throws InvalidArgumentException
         */
        protected function tokenizeQueryParameterMarkers($query, array $parameterValues) {
                $unnamedParameterCount = 0;
@@ -498,8 +498,8 @@ class t3lib_db_PreparedStatement {
                                if (!preg_match('/^:[\w]+$/', $key)) {
                                        throw new InvalidArgumentException('Parameter names must start with ":" followed by an arbitrary number of alphanumerical characters.', 1282348825);
                                }
-                               // Replace the marker (not preceeded by a word character or a ':' but
-                               // followed by a word boundary)
+                                       // Replace the marker (not preceeded by a word character or a ':' but
+                                       // followed by a word boundary)
                                $query = preg_replace('/(?<![\w:])' . $key . '\b/', $this->parameterWrapToken . $key . $this->parameterWrapToken, $query);
                        } else {
                                $unnamedParameterCount++;