[2.0] Added more missing docblocks. Implemented a double-inclusion listener prevention in EventManager

lib/Doctrine/Common/ClassLoader.php

@@ -46,14 +46,29 @@ namespace Doctrine\Common;
  */
 class ClassLoader
 {
-    private
+    /**
-        $_namespaceSeparator = '\\',
+     * @var string Namespace separator
-        $_fileExtension = '.php',
+     */
-        $_checkFileExists = false,
+    private $_namespaceSeparator = '\\';
-        $_basePaths = array();
+    
+    /**
+     * @var string File extension used for classes
+     */
+    private $_fileExtension = '.php';
+    
+    /**
+     * @var boolean Flag to inspect if file exists in codebase before include it
+     */
+    private $_checkFileExists = false;
+    
+    /**
+     * @var array Hashmap of base paths that Autoloader will look into
+     */
+    private $_basePaths = array();
 
     /**
      * Constructor registers the autoloader automatically
+     *
      */
     public function __construct()
     {
@@ -118,19 +133,17 @@ class ClassLoader
         }
 
         $prefix = substr($className, 0, strpos($className, $this->_namespaceSeparator));
-        $class = '';
         
-        if (isset($this->_basePaths[$prefix])) {
+        // If we have a custom path for namespace, use it
-            $class .= $this->_basePaths[$prefix] . DIRECTORY_SEPARATOR;
+        $class = ((isset($this->_basePaths[$prefix])) ? $this->_basePaths[$prefix] . DIRECTORY_SEPARATOR : '')
-        }
+               . str_replace($this->_namespaceSeparator, DIRECTORY_SEPARATOR, $className) . $this->_fileExtension;
-
-        $class .= str_replace($this->_namespaceSeparator, DIRECTORY_SEPARATOR, $className)
-                . $this->_fileExtension;
 
+        // Assure file exists in codebase before require if flag is active
         if ($this->_checkFileExists) {
-            if (!$fh = @fopen($class, 'r', true)) {
+            if (($fh = @fopen($class, 'r', true)) === false) {
                 return false;
             }
+            
             @fclose($fh);
         }
 

lib/Doctrine/Common/Collections/ArrayCollection.php

@@ -27,8 +27,13 @@ use \Closure, \ArrayIterator;
  * An ArrayCollection is a Collection implementation that uses a regular PHP array
  * internally.
  *
- * @author Roman S. Borschel <roman@code-factory.org>
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
  * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 class ArrayCollection implements Collection
 {
@@ -94,6 +99,8 @@ class ArrayCollection implements Collection
     
     /**
      * Moves the internal iterator position to the next element.
+     *
+     * @return mixed
      */
     public function next()
     {
@@ -102,6 +109,8 @@ class ArrayCollection implements Collection
     
     /**
      * Gets the element of the collection at the current internal iterator position.
+     *
+     * @return mixed
      */
     public function current()
     {
@@ -119,8 +128,10 @@ class ArrayCollection implements Collection
         if (isset($this->_elements[$key])) {
             $removed = $this->_elements[$key];
             unset($this->_elements[$key]);
+            
             return $removed;
         }
+        
         return null;
     }
 
@@ -133,17 +144,20 @@ class ArrayCollection implements Collection
     public function removeElement($element)
     {
         $key = array_search($element, $this->_elements, true);
+        
         if ($key !== false) {
             $removed = $this->_elements[$key];
             unset($this->_elements[$key]);
+            
             return $removed;
         }
+        
         return null;
     }
 
-    /* ArrayAccess implementation */
-
     /**
+     * ArrayAccess implementation of offsetExists()
+     *
      * @see containsKey()
      */
     public function offsetExists($offset)
@@ -152,6 +166,8 @@ class ArrayCollection implements Collection
     }
 
     /**
+     * ArrayAccess implementation of offsetGet()
+     *
      * @see get()
      */
     public function offsetGet($offset)
@@ -160,6 +176,8 @@ class ArrayCollection implements Collection
     }
 
     /**
+     * ArrayAccess implementation of offsetGet()
+     *
      * @see add()
      * @see set()
      */
@@ -172,6 +190,8 @@ class ArrayCollection implements Collection
     }
 
     /**
+     * ArrayAccess implementation of offsetUnset()
+     *
      * @see remove()
      */
     public function offsetUnset($offset)
@@ -179,8 +199,6 @@ class ArrayCollection implements Collection
         return $this->remove($offset);
     }
 
-    /* END ArrayAccess implementation */
-
     /**
      * Checks whether the collection contains a specific key/index.
      *
@@ -333,6 +351,7 @@ class ArrayCollection implements Collection
      * a new collection with the elements returned by the function.
      *
      * @param Closure $func
+     * @return Collection
      */
     public function map(Closure $func)
     {
@@ -365,6 +384,7 @@ class ArrayCollection implements Collection
                 return false;
             }
         }
+        
         return true;
     }
 
@@ -392,6 +412,7 @@ class ArrayCollection implements Collection
 
     /**
      * Returns a string representation of this object.
+     *
      */
     public function __toString()
     {
@@ -400,6 +421,7 @@ class ArrayCollection implements Collection
 
     /**
      * Clears the collection.
+     *
      */
     public function clear()
     {

lib/Doctrine/Common/Collections/Collection.php

@@ -1,4 +1,23 @@
 <?php
+/*
+ *  $Id$
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
 
 namespace Doctrine\Common\Collections;
 
@@ -20,8 +39,13 @@ namespace Doctrine\Common\Collections;
  * position unless you explicitly positioned it before. Prefer iteration with
  * external iterators.
  * 
- * @author Roman Borschel <roman@code-factory.org>
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
  * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 interface Collection extends \Countable, \IteratorAggregate, \ArrayAccess
 {
@@ -35,6 +59,7 @@ interface Collection extends \Countable, \IteratorAggregate, \ArrayAccess
     
     /**
      * Clears the collection.
+     *
      */
     function clear();
     
@@ -136,16 +161,19 @@ interface Collection extends \Countable, \IteratorAggregate, \ArrayAccess
     
     /**
      * Gets the key/index of the element at the current iterator position.
+     *
      */
     function key();
     
     /**
      * Gets the element of the collection at the current iterator position.
+     *
      */
     function current();
     
     /**
      * Moves the internal iterator position to the next element.
+     *
      */
     function next();
 }

lib/Doctrine/Common/DoctrineException.php

@@ -1,48 +1,115 @@
 <?php
+/*
+ *  $Id$
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the LGPL. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
  
 namespace Doctrine\Common;
 
+/** 
+ * Base Exception class of Doctrine
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
+ * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ */
 class DoctrineException extends \Exception
 {
+    /**
+     * @var array Lazy initialized array of error messages
+     * @static
+     */
     private static $_messages = array();
 
+    /**
+     * Initializes a new DoctrineException.
+     *
+     * @param string $message
+     * @param Exception $cause Optional Exception
+     */
     public function __construct($message = "", \Exception $cause = null)
     {
-        parent::__construct($message, 0, $cause);
+        $code = ($cause instanceof Exception) ? $cause->getCode() : 0;
+        
+        parent::__construct($message, $code, $cause);
     }
     
+    /**
+     * Throws a DoctrineException reporting not implemented method in a given class
+     *
+     * @static
+     * @param string $method Method name
+     * @param string $class  Class name
+     * @throws DoctrineException
+     */
     public static function notImplemented($method, $class)
     {
         return new self("The method '$method' is not implemented in class '$class'.");
     }
 
-    public static function __callStatic($method, $arguments)
+    /**
+     * Implementation of __callStatic magic method.
+     *
+     * Received a method name and arguments. It lookups a $_messages HashMap 
+     * for matching Class#Method key and executes the returned string value
+     * translating the placeholders with arguments passed.
+     *
+     * @static
+     * @param string $method Method name
+     * @param array $arguments Optional arguments to be translated in placeholders
+     * @throws DoctrineException
+     */
+    public static function __callStatic($method, $arguments = array())
     {
         $class = get_called_class();
         $messageKey = substr($class, strrpos($class, '\\') + 1) . "#$method";
 
         $end = end($arguments);
         $innerException = null;
+        
         if ($end instanceof \Exception) {
             $innerException = $end;
             unset($arguments[count($arguments) - 1]);
         }
 
-        if ($message = self::getExceptionMessage($messageKey)) {
+        if (($message = self::getExceptionMessage($messageKey)) !== false) {
             $message = sprintf($message, $arguments);
         } else {
+            $dumper  = function ($value) { return var_export($value, true); };
             $message = strtolower(preg_replace('~(?<=\\w)([A-Z])~', '_$1', $method));
-            $message  = ucfirst(str_replace('_', ' ', $message));
+            $message = ucfirst(str_replace('_', ' ', $message))
-            $args = array();
+                     . ' (' . implode(', ', array_map($dumper, $arguments)) . ')';
-            foreach ($arguments as $argument) {
-                $args[] = var_export($argument, true);
-            }
-            $message .= ' (' . implode(', ', $args) . ')';
         }
         
         return new $class($message, $innerException);
     }
 
+    /**
+     * Retrieves error string given a message key for lookup 
+     *
+     * @static
+     * @param string $messageKey
+     * @return string|false Returns the error string if found; FALSE otherwise
+     */
     public static function getExceptionMessage($messageKey)
     {
         if ( ! self::$_messages) {
@@ -56,9 +123,11 @@ class DoctrineException extends \Exception
                         "The query contains more than one result."
             );
         }
+        
         if (isset(self::$_messages[$messageKey])) {
             return self::$_messages[$messageKey];
         }
+        
         return false;
     }
 }

lib/Doctrine/Common/EventArgs.php

@@ -28,20 +28,26 @@ namespace Doctrine\Common;
  * information to an event handler when an event is raised. The single empty EventArgs
  * instance can be obtained through {@link getEmptyInstance()}.
  *
- * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>
- * @author      Roman Borschel
  * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
  * @link    www.doctrine-project.org
  * @since   2.0
- * @version     $Revision$
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 class EventArgs
 {
+    /**
+     * @var EventArgs Single instance of EventArgs
+     * @static
+     */
     private static $_emptyEventArgsInstance;
     
     /**
      * Gets the single, empty EventArgs instance.
      * 
+     * @static
      * @return EventArgs
      */
     public static function getEmptyInstance()
@@ -49,6 +55,7 @@ class EventArgs
         if ( ! self::$_emptyEventArgsInstance) {
             self::$_emptyEventArgsInstance = new EventArgs;
         }
+        
         return self::$_emptyEventArgsInstance;
     }
 }  

lib/Doctrine/Common/EventManager.php

@@ -28,9 +28,13 @@ use Doctrine\Common\Events\Event;
  * Listeners are registered on the manager and events are dispatched through the
  * manager.
  * 
- * @author Roman Borschel <roman@code-factory.org>
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @link    www.doctrine-project.org
  * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 class EventManager
 {
@@ -55,6 +59,7 @@ class EventManager
     {
         if (isset($this->_listeners[$eventName])) {
             $eventArgs = $eventArgs === null ? EventArgs::getEmptyInstance() : $eventArgs;
+            
             foreach ($this->_listeners[$eventName] as $listener) {
                 $listener->$eventName($eventArgs);
             }
@@ -65,7 +70,7 @@ class EventManager
      * Gets the listeners of a specific event or all listeners.
      *
      * @param string $event The name of the event.
-     * @return The event listeners for the specified event, or all event listeners.
+     * @return array The event listeners for the specified event, or all event listeners.
      */
     public function getListeners($event = null)
     {
@@ -91,9 +96,13 @@ class EventManager
      */
     public function addEventListener($events, $listener)
     {
-        // TODO: maybe check for duplicate registrations?
+        // Picks the hash code related to that listener
+        $hash = spl_object_hash($listener);
+        
         foreach ((array) $events as $event) {
-            $this->_listeners[$event][] = $listener;
+            // Overrides listener if a previous one was associated already
+            // Prevents duplicate listeners on same event (same instance only)
+            $this->_listeners[$event][$hash] = $listener;
         }
     }
     
@@ -105,9 +114,13 @@ class EventManager
      */
     public function removeEventListener($events, $listener)
     {
+        // Picks the hash code related to that listener
+        $hash = spl_object_hash($listener);
+        
         foreach ((array) $events as $event) {
-            if (($key = array_search($listener, $this->_listeners[$event], true)) !== false) {
+            // Check if actually have this listener associated
-                unset($this->_listeners[$event][$key]);
+            if (isset($this->_listeners[$event][$hash])) {
+                unset($this->_listeners[$event][$hash]);
             }
         }
     }

lib/Doctrine/Common/EventSubscriber.php

@@ -27,13 +27,20 @@ namespace Doctrine\Common;
  * getSubscribedEvents() and registers the subscriber as a listener for all
  * returned events.
  *
- * @author      Roman Borschel <roman@code-factory.org>
  * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
- * @link        www.phpdoctrine.org
+ * @link    www.doctrine-project.org
  * @since   2.0
- * @version     $Revision: 4653 $
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 interface EventSubscriber
 {
+    /**
+     * Returns an array of events that this subscriber listens 
+     *
+     * @return array
+     */
     public function getSubscribedEvents();
 }

lib/Doctrine/Common/Lexer.php

@@ -35,19 +35,17 @@ namespace Doctrine\Common;
 abstract class Lexer
 {
     /**
-     * Array of scanned tokens.
+     * @var array Array of scanned tokens
-     *
-     * @var array
      */
     private $_tokens = array();
 
     /**
-     * @todo Doc
+     * @var integer Current lexer position in input string
      */
     private $_position = 0;
 
     /**
-     * @todo Doc
+     * @var integer Current peek of current lexer position
      */
     private $_peek = 0;
 
@@ -129,15 +127,12 @@ abstract class Lexer
      */
     public function moveNext()
     {
-        $this->token = $this->lookahead;
         $this->_peek = 0;
-        if (isset($this->_tokens[$this->_position])) {
+        $this->token = $this->lookahead;
-            $this->lookahead = $this->_tokens[$this->_position++];
+        $this->lookahead = (isset($this->_tokens[$this->_position]))
-            return true;
+            ? $this->_tokens[$this->_position++] : null;
-        } else {
+        
-            $this->lookahead = null;
+        return $this->lookahead !== null;
-            return false;
-        }
     }
     
     /**
@@ -153,13 +148,15 @@ abstract class Lexer
     }
     
     /**
-     * @todo Doc
+     * Checks if given value is identical to the given token
+     *
+     * @param mixed $value
+     * @param integer $token
+     * @return boolean
      */
     public function isA($value, $token)
     {
-        $type = $this->_getType($value);
+        return $this->_getType($value) === $token;
-
-        return $type === $token;
     }
 
     /**
@@ -206,11 +203,9 @@ abstract class Lexer
         $matches = preg_split($regex, $input, -1, $flags);
 
         foreach ($matches as $match) {
-            $value = $match[0];
-            $type = $this->_getType($value);
             $this->_tokens[] = array(
-                'value' => $value,
+                'value' => $match[0],
-                'type'  => $type,
+                'type'  => $this->_getType($match[0]),
                 'position' => $match[1]
             );
         }

lib/Doctrine/Common/NotifyPropertyChanged.php

@@ -25,8 +25,13 @@ namespace Doctrine\Common;
  * Contract for classes that provide the service of notifying listeners of
  * changes to their properties.
  *
- * @author Roman Borschel <roman@code-factory.org>
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
  * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 interface NotifyPropertyChanged
 {

lib/Doctrine/Common/PropertyChangedListener.php

@@ -25,11 +25,20 @@ namespace Doctrine\Common;
  * Contract for classes that are potential listeners of a <tt>NotifyPropertyChanged</tt>
  * implementor.
  *
- * @author Roman Borschel <roman@code-factory.org>
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
  * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
  */
 interface PropertyChangedListener
 {
+    /**
+     * @todo Document this function
+     *
+     */
     function propertyChanged($sender, $propertyName, $oldValue, $newValue);
 }
 

lib/Doctrine/Common/Util/Debug.php

@@ -23,30 +23,46 @@ namespace Doctrine\Common\Util;
 
 /**
  * Static class containing most used debug methods.
- * @author Giorgio Sironi <piccoloprincipeazzurro@gmail.com>
+ *
+ * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
+ * @link    www.doctrine-project.org
  * @since   2.0
+ * @version $Revision: 3938 $
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ * @author  Giorgio Sironi <piccoloprincipeazzurro@gmail.com>
  */
 final class Debug
 {
+    /**
+     * Private constructor (prevents from instantiation)
+     *
+     */
     private function __construct() {}
 
     /**
      * Prints a dump of the public, protected and private properties of $var.
      * To print a meaningful dump, whose depth is limited, requires xdebug 
      * php extension.
+     *
+     * @static
      * @link http://xdebug.org/
      * @param mixed $var
-     * @param integer $maxDepth     maximum nesting level for object properties
+     * @param integer $maxDepth Maximum nesting level for object properties
      */
     public static function dump($var, $maxDepth = 2)
     {
         ini_set('html_errors', 'On');
         ini_set('xdebug.var_display_max_depth', $maxDepth);
+        
         ob_start();
         var_dump($var);
         $dump = ob_get_contents();
         ob_end_clean();
+        
         echo strip_tags(html_entity_decode($dump));
+        
         ini_set('html_errors', 'Off');
     }
 }