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);
}
-
}