From fad22d1e60d866ea974718dee2b6d51febb8c34b Mon Sep 17 00:00:00 2001
From: Benjamin Morel <benjamin.morel@strictcoding.co.uk>
Date: Sun, 2 Dec 2012 12:37:56 +0000
Subject: [PATCH] Fixed documentation for ORM\Event and ORM\Id

---
 lib/Doctrine/ORM/Event/LifecycleEventArgs.php | 10 +++---
 .../ORM/Event/LoadClassMetadataEventArgs.php  |  9 +++--
 lib/Doctrine/ORM/Event/OnClearEventArgs.php   |  8 ++---
 lib/Doctrine/ORM/Event/PostFlushEventArgs.php |  2 +-
 lib/Doctrine/ORM/Event/PreFlushEventArgs.php  |  5 +++
 lib/Doctrine/ORM/Event/PreUpdateEventArgs.php | 35 ++++++++++++-------
 lib/Doctrine/ORM/Id/AbstractIdGenerator.php   |  2 ++
 lib/Doctrine/ORM/Id/AssignedGenerator.php     |  7 +++-
 lib/Doctrine/ORM/Id/IdentityGenerator.php     | 14 +++++---
 lib/Doctrine/ORM/Id/SequenceGenerator.php     | 16 +++++++--
 lib/Doctrine/ORM/Id/TableGenerator.php        | 20 +++++++++++
 lib/Doctrine/ORM/Id/UuidGenerator.php         |  9 +++--
 12 files changed, 96 insertions(+), 41 deletions(-)

diff --git a/lib/Doctrine/ORM/Event/LifecycleEventArgs.php b/lib/Doctrine/ORM/Event/LifecycleEventArgs.php
index 4346054b7..57aa51427 100644
--- a/lib/Doctrine/ORM/Event/LifecycleEventArgs.php
+++ b/lib/Doctrine/ORM/Event/LifecycleEventArgs.php
@@ -44,10 +44,10 @@ class LifecycleEventArgs extends EventArgs
     private $entity;
 
     /**
-     * Constructor
+     * Constructor.
      *
-     * @param object $entity
-     * @param \Doctrine\ORM\EntityManager $em
+     * @param object        $entity
+     * @param EntityManager $em
      */
     public function __construct($entity, EntityManager $em)
     {
@@ -56,7 +56,7 @@ class LifecycleEventArgs extends EventArgs
     }
 
     /**
-     * Retrieve associated Entity.
+     * Retrieves associated Entity.
      *
      * @return object
      */
@@ -66,7 +66,7 @@ class LifecycleEventArgs extends EventArgs
     }
 
     /**
-     * Retrieve associated EntityManager.
+     * Retrieves associated EntityManager.
      *
      * @return \Doctrine\ORM\EntityManager
      */
diff --git a/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php b/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php
index 4c2cb0748..8396f0d24 100644
--- a/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php
+++ b/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php
@@ -44,8 +44,8 @@ class LoadClassMetadataEventArgs extends EventArgs
     /**
      * Constructor.
      *
-     * @param \Doctrine\ORM\Mapping\ClassMetadataInfo $classMetadata
-     * @param \Doctrine\ORM\EntityManager $em
+     * @param ClassMetadataInfo $classMetadata
+     * @param EntityManager     $em
      */
     public function __construct(ClassMetadataInfo $classMetadata, EntityManager $em)
     {
@@ -54,7 +54,7 @@ class LoadClassMetadataEventArgs extends EventArgs
     }
 
     /**
-     * Retrieve associated ClassMetadata.
+     * Retrieves associated ClassMetadata.
      *
      * @return \Doctrine\ORM\Mapping\ClassMetadataInfo
      */
@@ -64,7 +64,7 @@ class LoadClassMetadataEventArgs extends EventArgs
     }
 
     /**
-     * Retrieve associated EntityManager.
+     * Retrieves associated EntityManager.
      *
      * @return \Doctrine\ORM\EntityManager
      */
@@ -73,4 +73,3 @@ class LoadClassMetadataEventArgs extends EventArgs
         return $this->em;
     }
 }
-
diff --git a/lib/Doctrine/ORM/Event/OnClearEventArgs.php b/lib/Doctrine/ORM/Event/OnClearEventArgs.php
index 309994f3d..23520ed2a 100644
--- a/lib/Doctrine/ORM/Event/OnClearEventArgs.php
+++ b/lib/Doctrine/ORM/Event/OnClearEventArgs.php
@@ -44,7 +44,7 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
      * Constructor.
      *
      * @param \Doctrine\ORM\EntityManager $em
-     * @param string $entityClass Optional entity class
+     * @param string|null                 $entityClass Optional entity class.
      */
     public function __construct($em, $entityClass = null)
     {
@@ -53,7 +53,7 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
     }
 
     /**
-     * Retrieve associated EntityManager.
+     * Retrieves associated EntityManager.
      *
      * @return \Doctrine\ORM\EntityManager
      */
@@ -65,7 +65,7 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
     /**
      * Name of the entity class that is cleared, or empty if all are cleared.
      *
-     * @return string
+     * @return string|null
      */
     public function getEntityClass()
     {
@@ -73,7 +73,7 @@ class OnClearEventArgs extends \Doctrine\Common\EventArgs
     }
 
     /**
-     * Check if event clears all entities.
+     * Checks if event clears all entities.
      *
      * @return bool
      */
diff --git a/lib/Doctrine/ORM/Event/PostFlushEventArgs.php b/lib/Doctrine/ORM/Event/PostFlushEventArgs.php
index 5f9735c0e..d12060082 100644
--- a/lib/Doctrine/ORM/Event/PostFlushEventArgs.php
+++ b/lib/Doctrine/ORM/Event/PostFlushEventArgs.php
@@ -47,7 +47,7 @@ class PostFlushEventArgs extends EventArgs
     }
 
     /**
-     * Retrieve associated EntityManager.
+     * Retrieves associated EntityManager.
      *
      * @return \Doctrine\ORM\EntityManager
      */
diff --git a/lib/Doctrine/ORM/Event/PreFlushEventArgs.php b/lib/Doctrine/ORM/Event/PreFlushEventArgs.php
index c59f5db70..02798e1a3 100644
--- a/lib/Doctrine/ORM/Event/PreFlushEventArgs.php
+++ b/lib/Doctrine/ORM/Event/PreFlushEventArgs.php
@@ -35,6 +35,11 @@ class PreFlushEventArgs extends \Doctrine\Common\EventArgs
      */
     private $_em;
 
+    /**
+     * Constructor.
+     *
+     * @param \Doctrine\ORM\EntityManager $em
+     */
     public function __construct($em)
     {
         $this->_em = $em;
diff --git a/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php b/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php
index 1bb0f1b77..0cae066af 100644
--- a/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php
+++ b/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php
@@ -40,9 +40,9 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     /**
      * Constructor.
      *
-     * @param object $entity
-     * @param \Doctrine\ORM\EntityManager $em
-     * @param array $changeSet
+     * @param object        $entity
+     * @param EntityManager $em
+     * @param array         $changeSet
      */
     public function __construct($entity, EntityManager $em, array &$changeSet)
     {
@@ -52,7 +52,7 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     }
 
     /**
-     * Retrieve entity changeset.
+     * Retrieves entity changeset.
      *
      * @return array
      */
@@ -62,7 +62,9 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     }
 
     /**
-     * Check if field has a changeset.
+     * Checks if field has a changeset.
+     *
+     * @param string $field
      *
      * @return boolean
      */
@@ -72,9 +74,10 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     }
 
     /**
-     * Get the old value of the changeset of the changed field.
+     * Gets the old value of the changeset of the changed field.
+     *
+     * @param string $field
      *
-     * @param  string $field
      * @return mixed
      */
     public function getOldValue($field)
@@ -85,9 +88,10 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     }
 
     /**
-     * Get the new value of the changeset of the changed field.
+     * Gets the new value of the changeset of the changed field.
+     *
+     * @param string $field
      *
-     * @param  string $field
      * @return mixed
      */
     public function getNewValue($field)
@@ -98,10 +102,12 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     }
 
     /**
-     * Set the new value of this field.
+     * Sets the new value of this field.
      *
      * @param string $field
-     * @param mixed $value
+     * @param mixed  $value
+     *
+     * @return void
      */
     public function setNewValue($field, $value)
     {
@@ -111,9 +117,13 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     }
 
     /**
-     * Assert the field exists in changeset.
+     * Asserts the field exists in changeset.
      *
      * @param string $field
+     *
+     * @return void
+     *
+     * @throws \InvalidArgumentException
      */
     private function assertValidField($field)
     {
@@ -126,4 +136,3 @@ class PreUpdateEventArgs extends LifecycleEventArgs
         }
     }
 }
-
diff --git a/lib/Doctrine/ORM/Id/AbstractIdGenerator.php b/lib/Doctrine/ORM/Id/AbstractIdGenerator.php
index 77f6b0022..b4161b29e 100644
--- a/lib/Doctrine/ORM/Id/AbstractIdGenerator.php
+++ b/lib/Doctrine/ORM/Id/AbstractIdGenerator.php
@@ -26,7 +26,9 @@ abstract class AbstractIdGenerator
     /**
      * Generates an identifier for an entity.
      *
+     * @param \Doctrine\ORM\EntityManager  $em
      * @param \Doctrine\ORM\Mapping\Entity $entity
+     *
      * @return mixed
      */
     abstract public function generate(EntityManager $em, $entity);
diff --git a/lib/Doctrine/ORM/Id/AssignedGenerator.php b/lib/Doctrine/ORM/Id/AssignedGenerator.php
index 0597c3bc6..853ff3bbd 100644
--- a/lib/Doctrine/ORM/Id/AssignedGenerator.php
+++ b/lib/Doctrine/ORM/Id/AssignedGenerator.php
@@ -36,8 +36,13 @@ class AssignedGenerator extends AbstractIdGenerator
     /**
      * Returns the identifier assigned to the given entity.
      *
-     * @param object $entity
+     * @param EntityManager $em
+     * @param object        $entity
+     *
      * @return mixed
+     *
+     * @throws \Doctrine\ORM\ORMException
+     *
      * @override
      */
     public function generate(EntityManager $em, $entity)
diff --git a/lib/Doctrine/ORM/Id/IdentityGenerator.php b/lib/Doctrine/ORM/Id/IdentityGenerator.php
index ff2cd01b1..014bb44b4 100644
--- a/lib/Doctrine/ORM/Id/IdentityGenerator.php
+++ b/lib/Doctrine/ORM/Id/IdentityGenerator.php
@@ -28,13 +28,19 @@ use Doctrine\ORM\EntityManager;
  */
 class IdentityGenerator extends AbstractIdGenerator
 {
-    /** @var string The name of the sequence to pass to lastInsertId(), if any. */
+    /**
+     * The name of the sequence to pass to lastInsertId(), if any.
+     *
+     * @var string
+     */
     private $_seqName;
 
     /**
-     * @param string $seqName The name of the sequence to pass to lastInsertId()
-     *                        to obtain the last generated identifier within the current
-     *                        database session/connection, if any.
+     * Constructor.
+     *
+     * @param string|null $seqName The name of the sequence to pass to lastInsertId()
+     *                             to obtain the last generated identifier within the current
+     *                             database session/connection, if any.
      */
     public function __construct($seqName = null)
     {
diff --git a/lib/Doctrine/ORM/Id/SequenceGenerator.php b/lib/Doctrine/ORM/Id/SequenceGenerator.php
index d230e3c6d..5d7e305da 100644
--- a/lib/Doctrine/ORM/Id/SequenceGenerator.php
+++ b/lib/Doctrine/ORM/Id/SequenceGenerator.php
@@ -38,8 +38,7 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
     /**
      * Initializes a new sequence generator.
      *
-     * @param \Doctrine\ORM\EntityManager $em The EntityManager to use.
-     * @param string $sequenceName The name of the sequence.
+     * @param string  $sequenceName   The name of the sequence.
      * @param integer $allocationSize The allocation size of the sequence.
      */
     public function __construct($sequenceName, $allocationSize)
@@ -51,8 +50,11 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
     /**
      * Generates an ID for the given entity.
      *
-     * @param object $entity
+     * @param EntityManager $em
+     * @param object        $entity
+     *
      * @return integer|float The generated value.
+     *
      * @override
      */
     public function generate(EntityManager $em, $entity)
@@ -89,6 +91,9 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
         return $this->_nextValue;
     }
 
+    /**
+     * @return string
+     */
     public function serialize()
     {
         return serialize(array(
@@ -97,6 +102,11 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
         ));
     }
 
+    /**
+     * @param string $serialized
+     *
+     * @return void
+     */
     public function unserialize($serialized)
     {
         $array = unserialize($serialized);
diff --git a/lib/Doctrine/ORM/Id/TableGenerator.php b/lib/Doctrine/ORM/Id/TableGenerator.php
index 7e84b0a6b..33aa3b8c0 100644
--- a/lib/Doctrine/ORM/Id/TableGenerator.php
+++ b/lib/Doctrine/ORM/Id/TableGenerator.php
@@ -32,12 +32,29 @@ use Doctrine\ORM\EntityManager;
  */
 class TableGenerator extends AbstractIdGenerator
 {
+    /**
+     * @var string
+     */
     private $_tableName;
+
+    /**
+     * @var string
+     */
     private $_sequenceName;
+
+    /**
+     * @var int
+     */
     private $_allocationSize;
+
     private $_nextValue;
     private $_maxValue;
 
+    /**
+     * @param string $tableName
+     * @param string $sequenceName
+     * @param int    $allocationSize
+     */
     public function __construct($tableName, $sequenceName = 'default', $allocationSize = 10)
     {
         $this->_tableName = $tableName;
@@ -45,6 +62,9 @@ class TableGenerator extends AbstractIdGenerator
         $this->_allocationSize = $allocationSize;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function generate(EntityManager $em, $entity)
     {
         if ($this->_maxValue === null || $this->_nextValue == $this->_maxValue) {
diff --git a/lib/Doctrine/ORM/Id/UuidGenerator.php b/lib/Doctrine/ORM/Id/UuidGenerator.php
index 230c518fe..901af806a 100644
--- a/lib/Doctrine/ORM/Id/UuidGenerator.php
+++ b/lib/Doctrine/ORM/Id/UuidGenerator.php
@@ -19,7 +19,6 @@
 
 namespace Doctrine\ORM\Id;
 
-use Serializable;
 use Doctrine\ORM\EntityManager;
 
 /**
@@ -30,13 +29,14 @@ use Doctrine\ORM\EntityManager;
  */
 class UuidGenerator extends AbstractIdGenerator
 {
-    
     /**
      * Generates an ID for the given entity.
      *
-     * @param Doctrine\ORM\EntityManager $em The EntityManager to user
-     * @param object $entity
+     * @param EntityManager $em     The EntityManager to use.
+     * @param object        $entity
+     *
      * @return string The generated value.
+     *
      * @override
      */
     public function generate(EntityManager $em, $entity)
@@ -45,5 +45,4 @@ class UuidGenerator extends AbstractIdGenerator
         $sql = 'SELECT ' . $conn->getDatabasePlatform()->getGuidExpression();
         return $conn->query($sql)->fetchColumn(0);
     }
-    
 }