Merge pull request #870 from lcobucci/master

Documenting interface methods (based on entity manager)

lib/Doctrine/ORM/EntityManager.php

@@ -162,9 +162,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets the database connection object used by the EntityManager.
+     * {@inheritDoc}
-     *
-     * @return \Doctrine\DBAL\Connection
      */
     public function getConnection()
     {
@@ -182,18 +180,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
+     * {@inheritDoc}
-     *
-     * Example:
-     *
-     * <code>
-     *     $qb = $em->createQueryBuilder();
-     *     $expr = $em->getExpressionBuilder();
-     *     $qb->select('u')->from('User', 'u')
-     *         ->where($expr->orX($expr->eq('u.id', 1), $expr->eq('u.id', 2)));
-     * </code>
-     *
-     * @return \Doctrine\ORM\Query\Expr
      */
     public function getExpressionBuilder()
     {
@@ -205,9 +192,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Starts a transaction on the underlying database connection.
+     * {@inheritDoc}
-     *
-     * @return void
      */
     public function beginTransaction()
     {
@@ -215,18 +200,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Executes a function in a transaction.
+     * {@inheritDoc}
-     *
-     * The function gets passed this EntityManager instance as an (optional) parameter.
-     *
-     * {@link flush} is invoked prior to transaction commit.
-     *
-     * If an exception occurs during execution of the function or flushing or transaction commit,
-     * the transaction is rolled back, the EntityManager closed and the exception re-thrown.
-     *
-     * @param callable $func The function to execute transactionally.
-     *
-     * @return mixed The non-empty value returned from the closure or true instead.
      */
     public function transactional($func)
     {
@@ -252,9 +226,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Commits a transaction on the underlying database connection.
+     * {@inheritDoc}
-     *
-     * @return void
      */
     public function commit()
     {
@@ -262,9 +234,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Performs a rollback on the underlying database connection.
+     * {@inheritDoc}
-     *
-     * @return void
      */
     public function rollback()
     {
@@ -293,11 +263,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Creates a new Query object.
+     * {@inheritDoc}
-     *
-     * @param string $dql The DQL string.
-     *
-     * @return \Doctrine\ORM\Query
      */
     public function createQuery($dql = '')
     {
@@ -311,11 +277,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Creates a Query from a named query.
+     * {@inheritDoc}
-     *
-     * @param string $name
-     *
-     * @return \Doctrine\ORM\Query
      */
     public function createNamedQuery($name)
     {
@@ -323,12 +285,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Creates a native SQL query.
+     * {@inheritDoc}
-     *
-     * @param string           $sql
-     * @param ResultSetMapping $rsm The ResultSetMapping to use.
-     *
-     * @return NativeQuery
      */
     public function createNativeQuery($sql, ResultSetMapping $rsm)
     {
@@ -341,11 +298,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Creates a NativeQuery from a named native query.
+     * {@inheritDoc}
-     *
-     * @param string $name
-     *
-     * @return \Doctrine\ORM\NativeQuery
      */
     public function createNamedNativeQuery($name)
     {
@@ -355,9 +308,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Create a QueryBuilder instance
+     * {@inheritDoc}
-     *
-     * @return QueryBuilder
      */
     public function createQueryBuilder()
     {
@@ -477,15 +428,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets a reference to the entity identified by the given type and identifier
+     * {@inheritDoc}
-     * without actually loading it, if the entity is not yet loaded.
-     *
-     * @param string $entityName The name of the entity type.
-     * @param mixed  $id         The entity identifier.
-     *
-     * @return object The entity reference.
-     *
-     * @throws ORMException
      */
     public function getReference($entityName, $id)
     {
@@ -526,24 +469,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets a partial reference to the entity identified by the given type and identifier
+     * {@inheritDoc}
-     * without actually loading it, if the entity is not yet loaded.
-     *
-     * The returned reference may be a partial object if the entity is not yet loaded/managed.
-     * If it is a partial object it will not initialize the rest of the entity state on access.
-     * Thus you can only ever safely access the identifier of an entity obtained through
-     * this method.
-     *
-     * The use-cases for partial references involve maintaining bidirectional associations
-     * without loading one side of the association or to update an entity without loading it.
-     * Note, however, that in the latter case the original (persistent) entity data will
-     * never be visible to the application (especially not event listeners) as it will
-     * never be loaded in the first place.
-     *
-     * @param string $entityName The name of the entity type.
-     * @param mixed  $identifier The entity identifier.
-     *
-     * @return object The (partial) entity reference.
      */
     public function getPartialReference($entityName, $identifier)
     {
@@ -582,11 +508,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Closes the EntityManager. All entities that are currently managed
+     * {@inheritDoc}
-     * by this EntityManager become detached. The EntityManager may no longer
-     * be used after it is closed.
-     *
-     * @return void
      */
     public function close()
     {
@@ -710,14 +632,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Creates a copy of the given entity. Can create a shallow or a deep copy.
+     * {@inheritDoc}
-     *
-     * @param object  $entity The entity to copy.
-     * @param boolean $deep   FALSE for a shallow copy, TRUE for a deep copy.
-     *
-     * @return object The new entity.
-     *
-     * @throws \BadMethodCallException
      *
      * @todo Implementation need. This is necessary since $e2 = clone $e1; throws an E_FATAL when access anything on $e:
      * Fatal error: Maximum function nesting level of '100' reached, aborting!
@@ -728,16 +643,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Acquire a lock on the given entity.
+     * {@inheritDoc}
-     *
-     * @param object   $entity
-     * @param int      $lockMode
-     * @param int|null $lockVersion
-     *
-     * @return void
-     *
-     * @throws OptimisticLockException
-     * @throws PessimisticLockException
      */
     public function lock($entity, $lockMode, $lockVersion = null)
     {
@@ -771,9 +677,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets the EventManager used by the EntityManager.
+     * {@inheritDoc}
-     *
-     * @return \Doctrine\Common\EventManager
      */
     public function getEventManager()
     {
@@ -781,9 +685,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets the Configuration used by the EntityManager.
+     * {@inheritDoc}
-     *
-     * @return \Doctrine\ORM\Configuration
      */
     public function getConfiguration()
     {
@@ -805,9 +707,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Check if the Entity manager is open or closed.
+     * {@inheritDoc}
-     *
-     * @return bool
      */
     public function isOpen()
     {
@@ -815,9 +715,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets the UnitOfWork used by the EntityManager to coordinate operations.
+     * {@inheritDoc}
-     *
-     * @return \Doctrine\ORM\UnitOfWork
      */
     public function getUnitOfWork()
     {
@@ -825,16 +723,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets a hydrator for the given hydration mode.
+     * {@inheritDoc}
-     *
-     * This method caches the hydrator instances which is used for all queries that don't
-     * selectively iterate over the result.
-     *
-     * @deprecated
-     *
-     * @param int $hydrationMode
-     *
-     * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
      */
     public function getHydrator($hydrationMode)
     {
@@ -842,13 +731,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Create a new instance for the given hydration mode.
+     * {@inheritDoc}
-     *
-     * @param int $hydrationMode
-     *
-     * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
-     *
-     * @throws ORMException
      */
     public function newHydrator($hydrationMode)
     {
@@ -878,9 +761,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets the proxy factory used by the EntityManager to create entity proxies.
+     * {@inheritDoc}
-     *
-     * @return ProxyFactory
      */
     public function getProxyFactory()
     {
@@ -888,13 +769,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Helper method to initialize a lazy loading proxy or persistent collection.
+     * {@inheritDoc}
-     *
-     * This method is a no-op for other objects
-     *
-     * @param object $obj
-     *
-     * @return void
      */
     public function initializeObject($obj)
     {
@@ -940,9 +815,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Gets the enabled filters.
+     * {@inheritDoc}
-     *
-     * @return FilterCollection The active filter collection.
      */
     public function getFilters()
     {
@@ -954,9 +827,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Checks whether the state of the filter collection is clean.
+     * {@inheritDoc}
-     *
-     * @return boolean True, if the filter collection is clean.
      */
     public function isFiltersStateClean()
     {
@@ -964,9 +835,7 @@ use Doctrine\Common\Util\ClassUtils;
     }
 
     /**
-     * Checks whether the Entity Manager has filters.
+     * {@inheritDoc}
-     *
-     * @return boolean True, if the EM has a filter collection.
      */
     public function hasFilters()
     {

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -20,7 +20,6 @@
 namespace Doctrine\ORM;
 
 use Doctrine\Common\Persistence\ObjectManager;
-use Doctrine\DBAL\LockMode;
 use Doctrine\ORM\Query\ResultSetMapping;
 
 /**
@@ -31,30 +30,258 @@ use Doctrine\ORM\Query\ResultSetMapping;
  */
 interface EntityManagerInterface extends ObjectManager
 {
+    /**
+     * Gets the database connection object used by the EntityManager.
+     *
+     * @return \Doctrine\DBAL\Connection
+     */
     public function getConnection();
+
+    /**
+     * Gets an ExpressionBuilder used for object-oriented construction of query expressions.
+     *
+     * Example:
+     *
+     * <code>
+     *     $qb = $em->createQueryBuilder();
+     *     $expr = $em->getExpressionBuilder();
+     *     $qb->select('u')->from('User', 'u')
+     *         ->where($expr->orX($expr->eq('u.id', 1), $expr->eq('u.id', 2)));
+     * </code>
+     *
+     * @return \Doctrine\ORM\Query\Expr
+     */
     public function getExpressionBuilder();
+
+    /**
+     * Starts a transaction on the underlying database connection.
+     *
+     * @return void
+     */
     public function beginTransaction();
+
+    /**
+     * Executes a function in a transaction.
+     *
+     * The function gets passed this EntityManager instance as an (optional) parameter.
+     *
+     * {@link flush} is invoked prior to transaction commit.
+     *
+     * If an exception occurs during execution of the function or flushing or transaction commit,
+     * the transaction is rolled back, the EntityManager closed and the exception re-thrown.
+     *
+     * @param callable $func The function to execute transactionally.
+     *
+     * @return mixed The non-empty value returned from the closure or true instead.
+     */
     public function transactional($func);
+
+    /**
+     * Commits a transaction on the underlying database connection.
+     *
+     * @return void
+     */
     public function commit();
+
+    /**
+     * Performs a rollback on the underlying database connection.
+     *
+     * @return void
+     */
     public function rollback();
+
+    /**
+     * Creates a new Query object.
+     *
+     * @param string $dql The DQL string.
+     *
+     * @return Query
+     */
     public function createQuery($dql = '');
+
+    /**
+     * Creates a Query from a named query.
+     *
+     * @param string $name
+     *
+     * @return Query
+     */
     public function createNamedQuery($name);
+
+    /**
+     * Creates a native SQL query.
+     *
+     * @param string           $sql
+     * @param ResultSetMapping $rsm The ResultSetMapping to use.
+     *
+     * @return NativeQuery
+     */
     public function createNativeQuery($sql, ResultSetMapping $rsm);
+
+    /**
+     * Creates a NativeQuery from a named native query.
+     *
+     * @param string $name
+     *
+     * @return NativeQuery
+     */
     public function createNamedNativeQuery($name);
+
+    /**
+     * Create a QueryBuilder instance
+     *
+     * @return QueryBuilder
+     */
     public function createQueryBuilder();
+
+    /**
+     * Gets a reference to the entity identified by the given type and identifier
+     * without actually loading it, if the entity is not yet loaded.
+     *
+     * @param string $entityName The name of the entity type.
+     * @param mixed  $id         The entity identifier.
+     *
+     * @return object The entity reference.
+     *
+     * @throws ORMException
+     */
     public function getReference($entityName, $id);
+
+    /**
+     * Gets a partial reference to the entity identified by the given type and identifier
+     * without actually loading it, if the entity is not yet loaded.
+     *
+     * The returned reference may be a partial object if the entity is not yet loaded/managed.
+     * If it is a partial object it will not initialize the rest of the entity state on access.
+     * Thus you can only ever safely access the identifier of an entity obtained through
+     * this method.
+     *
+     * The use-cases for partial references involve maintaining bidirectional associations
+     * without loading one side of the association or to update an entity without loading it.
+     * Note, however, that in the latter case the original (persistent) entity data will
+     * never be visible to the application (especially not event listeners) as it will
+     * never be loaded in the first place.
+     *
+     * @param string $entityName The name of the entity type.
+     * @param mixed  $identifier The entity identifier.
+     *
+     * @return object The (partial) entity reference.
+     */
     public function getPartialReference($entityName, $identifier);
+
+    /**
+     * Closes the EntityManager. All entities that are currently managed
+     * by this EntityManager become detached. The EntityManager may no longer
+     * be used after it is closed.
+     *
+     * @return void
+     */
     public function close();
+
+    /**
+     * Creates a copy of the given entity. Can create a shallow or a deep copy.
+     *
+     * @param object  $entity The entity to copy.
+     * @param boolean $deep   FALSE for a shallow copy, TRUE for a deep copy.
+     *
+     * @return object The new entity.
+     *
+     * @throws \BadMethodCallException
+     */
     public function copy($entity, $deep = false);
+
+    /**
+     * Acquire a lock on the given entity.
+     *
+     * @param object   $entity
+     * @param int      $lockMode
+     * @param int|null $lockVersion
+     *
+     * @return void
+     *
+     * @throws OptimisticLockException
+     * @throws PessimisticLockException
+     */
     public function lock($entity, $lockMode, $lockVersion = null);
+
+    /**
+     * Gets the EventManager used by the EntityManager.
+     *
+     * @return \Doctrine\Common\EventManager
+     */
     public function getEventManager();
+
+    /**
+     * Gets the Configuration used by the EntityManager.
+     *
+     * @return Configuration
+     */
     public function getConfiguration();
+
+    /**
+     * Check if the Entity manager is open or closed.
+     *
+     * @return bool
+     */
     public function isOpen();
+
+    /**
+     * Gets the UnitOfWork used by the EntityManager to coordinate operations.
+     *
+     * @return UnitOfWork
+     */
     public function getUnitOfWork();
+
+    /**
+    * Gets a hydrator for the given hydration mode.
+    *
+    * This method caches the hydrator instances which is used for all queries that don't
+    * selectively iterate over the result.
+    *
+    * @deprecated
+    *
+    * @param int $hydrationMode
+    *
+    * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
+    */
     public function getHydrator($hydrationMode);
+
+    /**
+     * Create a new instance for the given hydration mode.
+     *
+     * @param int $hydrationMode
+     *
+     * @return \Doctrine\ORM\Internal\Hydration\AbstractHydrator
+     *
+     * @throws ORMException
+     */
     public function newHydrator($hydrationMode);
+
+    /**
+     * Gets the proxy factory used by the EntityManager to create entity proxies.
+     *
+     * @return \Doctrine\ORM\Proxy\ProxyFactory
+     */
     public function getProxyFactory();
+
+    /**
+     * Gets the enabled filters.
+     *
+     * @return \Doctrine\ORM\Query\FilterCollection The active filter collection.
+     */
     public function getFilters();
+
+    /**
+     * Checks whether the state of the filter collection is clean.
+     *
+     * @return boolean True, if the filter collection is clean.
+     */
     public function isFiltersStateClean();
+
+    /**
+     * Checks whether the Entity Manager has filters.
+     *
+     * @return boolean True, if the EM has a filter collection.
+     */
     public function hasFilters();
 }