[Validator] Improved inline documentation of the validators

src/Symfony/Component/Validator/Validator/ContextualValidator.php

@@ -24,7 +24,9 @@ use Symfony\Component\Validator\NodeTraverser\NodeTraverserInterface;
 use Symfony\Component\Validator\Util\PropertyPath;
 
 /**
- * @since  %%NextVersion%%
+ * Default implementation of {@link ContextualValidatorInterface}.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class ContextualValidator implements ContextualValidatorInterface
@@ -44,6 +46,15 @@ class ContextualValidator implements ContextualValidatorInterface
      */
     private $metadataFactory;
 
+    /**
+     * Creates a validator for the given context.
+     *
+     * @param ExecutionContextInterface $context         The execution context
+     * @param NodeTraverserInterface    $nodeTraverser   The node traverser
+     * @param MetadataFactoryInterface  $metadataFactory The factory for fetching
+     *                                                   the metadata of validated
+     *                                                   objects
+     */
     public function __construct(ExecutionContextInterface $context, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory)
     {
         $this->context = $context;
@@ -53,13 +64,19 @@ class ContextualValidator implements ContextualValidatorInterface
         $this->metadataFactory = $metadataFactory;
     }
 
-    public function atPath($subPath)
+    /**
+     * {@inheritdoc}
+     */
+    public function atPath($path)
     {
-        $this->defaultPropertyPath = $this->context->getPropertyPath($subPath);
+        $this->defaultPropertyPath = $this->context->getPropertyPath($path);
 
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validate($value, $constraints = null, $groups = null)
     {
         if (null === $constraints) {
@@ -84,6 +101,9 @@ class ContextualValidator implements ContextualValidatorInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validateProperty($object, $propertyName, $groups = null)
     {
         $classMetadata = $this->metadataFactory->getMetadataFor($object);
@@ -118,6 +138,9 @@ class ContextualValidator implements ContextualValidatorInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validatePropertyValue($object, $propertyName, $value, $groups = null)
     {
         $classMetadata = $this->metadataFactory->getMetadataFor($object);
@@ -151,6 +174,21 @@ class ContextualValidator implements ContextualValidatorInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getViolations()
+    {
+        return $this->context->getViolations();
+    }
+
+    /**
+     * Normalizes the given group or list of groups to an array.
+     *
+     * @param mixed $groups The groups to normalize
+     *
+     * @return array A group array
+     */
     protected function normalizeGroups($groups)
     {
         if (is_array($groups)) {
@@ -159,9 +197,4 @@ class ContextualValidator implements ContextualValidatorInterface
 
         return array($groups);
     }
-
-    public function getViolations()
-    {
-        return $this->context->getViolations();
-    }
 }

src/Symfony/Component/Validator/Validator/ContextualValidatorInterface.php

@@ -15,17 +15,24 @@ use Symfony\Component\Validator\Constraint;
 use Symfony\Component\Validator\ConstraintViolationListInterface;
 
 /**
- * @since  %%NextVersion%%
+ * A validator in a specific execution context.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 interface ContextualValidatorInterface
 {
     /**
-     * @param string $subPath
+     * Appends the given path to the property path of the context.
+     *
+     * If called multiple times, the path will always be reset to the context's
+     * original path with the given path appended to it.
+     *
+     * @param string $path The path to append
      *
      * @return ContextualValidatorInterface This validator
      */
-    public function atPath($subPath);
+    public function atPath($path);
 
     /**
      * Validates a value against a constraint or a list of constraints.
@@ -33,46 +40,50 @@ interface ContextualValidatorInterface
      * If no constraint is passed, the constraint
      * {@link \Symfony\Component\Validator\Constraints\Valid} is assumed.
      *
-     * @param mixed                   $value       The value to validate.
+     * @param mixed                   $value       The value to validate
-     * @param Constraint|Constraint[] $constraints The constraint(s) to validate against.
+     * @param Constraint|Constraint[] $constraints The constraint(s) to validate
-     * @param array|null              $groups      The validation groups to validate.
+     *                                             against
+     * @param array|null              $groups      The validation groups to
+     *                                             validate. If none is given,
+     *                                             "Default" is assumed
      *
      * @return ContextualValidatorInterface This validator
      */
     public function validate($value, $constraints = null, $groups = null);
 
     /**
-     * Validates a property of a value against its current value.
+     * Validates a property of an object against the constraints specified
+     * for this property.
      *
-     * The accepted values depend on the {@link MetadataFactoryInterface}
+     * @param object     $object       The object
-     * implementation.
+     * @param string     $propertyName The name of the validated property
-     *
+     * @param array|null $groups       The validation groups to validate. If
-     * @param mixed      $object       The value containing the property.
+     *                                 none is given, "Default" is assumed
-     * @param string     $propertyName The name of the property to validate.
-     * @param array|null $groups       The validation groups to validate.
      *
      * @return ContextualValidatorInterface This validator
      */
     public function validateProperty($object, $propertyName, $groups = null);
 
     /**
-     * Validate a property of a value against a potential value.
+     * Validates a value against the constraints specified for an object's
+     * property.
      *
-     * The accepted values depend on the {@link MetadataFactoryInterface}
+     * @param object     $object       The object
-     * implementation.
+     * @param string     $propertyName The name of the property
-     *
+     * @param mixed      $value        The value to validate against the
-     * @param string     $object       The value containing the property.
+     *                                 property's constraints
-     * @param string     $propertyName The name of the property to validate
+     * @param array|null $groups       The validation groups to validate. If
-     * @param string     $value        The value to validate against the
+     *                                 none is given, "Default" is assumed
-     *                                 constraints of the property.
-     * @param array|null $groups       The validation groups to validate.
      *
      * @return ContextualValidatorInterface This validator
      */
     public function validatePropertyValue($object, $propertyName, $value, $groups = null);
 
     /**
-     * @return ConstraintViolationListInterface
+     * Returns the violations that have been generated so far in the context
+     * of the validator.
+     *
+     * @return ConstraintViolationListInterface The constraint violations
      */
     public function getViolations();
 }

src/Symfony/Component/Validator/Validator/LegacyValidator.php

@@ -17,9 +17,14 @@ use Symfony\Component\Validator\Constraints\Valid;
 use Symfony\Component\Validator\ValidatorInterface as LegacyValidatorInterface;
 
 /**
+ * A validator that supports both the API of Symfony < 2.5 and Symfony 2.5+.
+ *
  * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  *
+ * @see \Symfony\Component\Validator\ValidatorInterface
+ * @see \Symfony\Component\Validator\Validator\ValidatorInterface
+ *
  * @deprecated Implemented for backwards compatibility with Symfony < 2.5.
  *             To be removed in Symfony 3.0.
  */

src/Symfony/Component/Validator/Validator/Validator.php

@@ -17,7 +17,9 @@ use Symfony\Component\Validator\NodeTraverser\NodeTraverserInterface;
 use Symfony\Component\Validator\MetadataFactoryInterface;
 
 /**
- * @since  %%NextVersion%%
+ * Default implementation of {@link ValidatorInterface}.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class Validator implements ValidatorInterface
@@ -37,6 +39,16 @@ class Validator implements ValidatorInterface
      */
     protected $metadataFactory;
 
+    /**
+     * Creates a new validator.
+     *
+     * @param ExecutionContextFactoryInterface $contextFactory  The factory for
+     *                                                          creating new contexts
+     * @param NodeTraverserInterface           $nodeTraverser   The node traverser
+     * @param MetadataFactoryInterface         $metadataFactory The factory for
+     *                                                          fetching the metadata
+     *                                                          of validated objects
+     */
     public function __construct(ExecutionContextFactoryInterface $contextFactory, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory)
     {
         $this->contextFactory = $contextFactory;
@@ -84,6 +96,9 @@ class Validator implements ValidatorInterface
         return $this->metadataFactory->hasMetadataFor($object);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validate($value, $constraints = null, $groups = null)
     {
         return $this->startContext($value)
@@ -91,6 +106,9 @@ class Validator implements ValidatorInterface
             ->getViolations();
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validateProperty($object, $propertyName, $groups = null)
     {
         return $this->startContext($object)
@@ -98,6 +116,9 @@ class Validator implements ValidatorInterface
             ->getViolations();
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validatePropertyValue($object, $propertyName, $value, $groups = null)
     {
         return $this->startContext($object)

src/Symfony/Component/Validator/Validator/ValidatorInterface.php

@@ -16,7 +16,9 @@ use Symfony\Component\Validator\ConstraintViolationListInterface;
 use Symfony\Component\Validator\Context\ExecutionContextInterface;
 
 /**
- * @since  %%NextVersion%%
+ * Validates PHP values against constraints.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 interface ValidatorInterface
@@ -27,60 +29,91 @@ interface ValidatorInterface
      * If no constraint is passed, the constraint
      * {@link \Symfony\Component\Validator\Constraints\Valid} is assumed.
      *
-     * @param mixed                   $value       The value to validate.
+     * @param mixed                   $value       The value to validate
-     * @param Constraint|Constraint[] $constraints The constraint(s) to validate against.
+     * @param Constraint|Constraint[] $constraints The constraint(s) to validate
-     * @param array|null              $groups      The validation groups to validate.
+     *                                             against
+     * @param array|null              $groups      The validation groups to
+     *                                             validate. If none is given,
+     *                                             "Default" is assumed
      *
-     * @return ConstraintViolationListInterface A list of constraint violations. If the
+     * @return ConstraintViolationListInterface A list of constraint violations.
-     *                                          list is empty, validation succeeded.
+     *                                          If the list is empty, validation
+     *                                          succeeded
      */
     public function validate($value, $constraints = null, $groups = null);
 
     /**
-     * Validates a property of a value against its current value.
+     * Validates a property of an object against the constraints specified
+     * for this property.
      *
-     * The accepted values depend on the {@link MetadataFactoryInterface}
+     * @param object     $object       The object
-     * implementation.
+     * @param string     $propertyName The name of the validated property
+     * @param array|null $groups       The validation groups to validate. If
+     *                                 none is given, "Default" is assumed
      *
-     * @param mixed      $object The value containing the property.
+     * @return ConstraintViolationListInterface A list of constraint violations.
-     * @param string     $propertyName        The name of the property to validate.
+     *                                          If the list is empty, validation
-     * @param array|null $groups          The validation groups to validate.
+     *                                          succeeded
-     *
-     * @return ConstraintViolationListInterface A list of constraint violations. If the
-     *                                          list is empty, validation succeeded.
      */
     public function validateProperty($object, $propertyName, $groups = null);
 
     /**
-     * Validate a property of a value against a potential value.
+     * Validates a value against the constraints specified for an object's
+     * property.
      *
-     * The accepted values depend on the {@link MetadataFactoryInterface}
+     * @param object     $object       The object
-     * implementation.
+     * @param string     $propertyName The name of the property
+     * @param mixed      $value        The value to validate against the
+     *                                 property's constraints
+     * @param array|null $groups       The validation groups to validate. If
+     *                                 none is given, "Default" is assumed
      *
-     * @param string     $object The value containing the property.
+     * @return ConstraintViolationListInterface A list of constraint violations.
-     * @param string     $propertyName        The name of the property to validate
+     *                                          If the list is empty, validation
-     * @param string     $value           The value to validate against the
+     *                                          succeeded
-     *                                    constraints of the property.
-     * @param array|null $groups          The validation groups to validate.
-     *
-     * @return ConstraintViolationListInterface A list of constraint violations. If the
-     *                                          list is empty, validation succeeded.
      */
     public function validatePropertyValue($object, $propertyName, $value, $groups = null);
 
     /**
-     * @return ContextualValidatorInterface
+     * Starts a new validation context and returns a validator for that context.
+     *
+     * The returned validator collects all violations generated within its
+     * context. You can access these violations with the
+     * {@link ContextualValidatorInterface::getViolations()} method.
+     *
+     * @return ContextualValidatorInterface The validator for the new context
      */
     public function startContext();
 
     /**
-     * @param ExecutionContextInterface $context
+     * Returns a validator in the given execution context.
      *
-     * @return ContextualValidatorInterface
+     * The returned validator adds all generated violations to the given
+     * context.
+     *
+     * @param ExecutionContextInterface $context The execution context
+     *
+     * @return ContextualValidatorInterface The validator for that context
      */
     public function inContext(ExecutionContextInterface $context);
 
+    /**
+     * Returns the metadata for an object.
+     *
+     * @param object $object The object
+     *
+     * @return \Symfony\Component\Validator\Mapping\MetadataInterface The metadata
+     *
+     * @throws \Symfony\Component\Validator\Exception\NoSuchMetadataException If no metadata exists
+     */
     public function getMetadataFor($object);
 
+    /**
+     * Returns whether the validator has metadata for an object.
+     *
+     * @param object $object The object
+     *
+     * @return Boolean Whether metadata exists for that object
+     */
     public function hasMetadataFor($object);
 }