[Validator] Adding a significant amount of PHPDoc to the Validator co…

…mponent.

src/Symfony/Component/Validator/Constraint.php

@@ -30,6 +30,9 @@ abstract class Constraint
 {
     const DEFAULT_GROUP = 'Default';
 
+    /**
+     * @var array
+     */
     public $groups = array(self::DEFAULT_GROUP);
 
     /**

src/Symfony/Component/Validator/ConstraintValidator.php

@@ -17,18 +17,27 @@ abstract class ConstraintValidator implements ConstraintValidatorInterface
     private $messageTemplate;
     private $messageParameters;
 
+    /**
+     * {@inheritDoc}
+     */
     public function initialize(ValidationContext $context)
     {
         $this->context = $context;
         $this->messageTemplate = '';
         $this->messageParameters = array();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getMessageTemplate()
     {
         return $this->messageTemplate;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getMessageParameters()
     {
         return $this->messageParameters;

src/Symfony/Component/Validator/ConstraintValidatorFactory.php

@@ -14,10 +14,20 @@
 use Symfony\Component\Validator\ConstraintValidatorFactoryInterface;
 use Symfony\Component\Validator\Constraint;
 
+/**
+ * Default implementation of the ConstraintValidatorFactoryInterface.
+ *
+ * This enforces the convention that the validatedBy() method on any
+ * Constrain will return the class name of the ConstraintValidator that
+ * should validate the Constraint.
+ */
 class ConstraintValidatorFactory implements ConstraintValidatorFactoryInterface
 {
     protected $validators = array();
 
+    /**
+     * {@inheritDoc}
+     */
     public function getInstance(Constraint $constraint)
     {
         $className = $constraint->validatedBy();

src/Symfony/Component/Validator/ConstraintValidatorFactoryInterface.php

@@ -13,7 +13,18 @@
 
 use Symfony\Component\Validator\Constraint;
 
+/**
+ * Specifies an object able to return the correct ConstraintValidatorInterface
+ * instance given a Constrain object.
+ */
 interface ConstraintValidatorFactoryInterface
 {
+    /**
+     * Given a Constrain, this returns the ConstraintValidatorInterface
+     * object that should be used to verify its validity.
+     *
+     * @param Constraint $constraint The source constraint
+     * @return ConstraintValidatorInterface
+     */
     function getInstance(Constraint $constraint);
 }

src/Symfony/Component/Validator/ConstraintValidatorInterface.php

@@ -13,11 +13,27 @@
 
 interface ConstraintValidatorInterface
 {
+    /**
+     * Initialize the constraint validator.
+     *
+     * @param ValidationContext $context The current validation context
+     */
     function initialize(ValidationContext $context);
 
+    /**
+     * @param  mixed $value The value that should be validated
+     * @param Constraint $constraint The constrain for the validation
+     * @return boolean Whether or not the value is valid
+     */
     function isValid($value, Constraint $constraint);
 
+    /**
+     * @return string
+     */
     function getMessageTemplate();
 
+    /**
+     * @return array
+     */
     function getMessageParameters();
 }

src/Symfony/Component/Validator/ConstraintViolation.php

@@ -11,6 +11,9 @@
  * with this source code in the file LICENSE.
  */
 
+/**
+ * Represents a single violation of a constraint.
+ */
 class ConstraintViolation
 {
     protected $messageTemplate;
@@ -28,16 +31,27 @@ public function __construct($messageTemplate, array $messageParameters, $root, $
         $this->invalidValue = $invalidValue;
     }
 
+    /**
+     * @return string
+     */
     public function getMessageTemplate()
     {
         return $this->messageTemplate;
     }
 
+    /**
+     * @return array
+     */
     public function getMessageParameters()
     {
         return $this->messageParameters;
     }
 
+    /**
+     * Returns the violation message.
+     *
+     * @return string
+     */
     public function getMessage()
     {
         return str_replace(array_keys($this->messageParameters), array_values($this->messageParameters), $this->messageTemplate);

src/Symfony/Component/Validator/ConstraintViolationList.php

@@ -11,10 +11,16 @@
  * with this source code in the file LICENSE.
  */
 
+/**
+ * An array-acting object that holds many ConstrainViolation instances.
+ */
 class ConstraintViolationList implements \IteratorAggregate, \Countable
 {
     protected $violations = array();
 
+    /**
+     * @return string
+     */
     public function __toString()
     {
         $string = '';
@@ -32,23 +38,39 @@ public function __toString()
         return $string;
     }
 
+    /**
+     * Add a ConstraintViolation to this list.
+     *
+     * @param ConstraintViolation $violation
+     */
     public function add(ConstraintViolation $violation)
     {
         $this->violations[] = $violation;
     }
 
+    /**
+     * Merge an existing ConstraintViolationList into this list.
+     *
+     * @param ConstraintViolationList $violations
+     */
     public function addAll(ConstraintViolationList $violations)
     {
         foreach ($violations->violations as $violation) {
             $this->violations[] = $violation;
         }
     }
 
+    /**
+     * @see IteratorAggregate
+     */
     public function getIterator()
     {
         return new \ArrayIterator($this->violations);
     }
 
+    /**
+     * @see Countable
+     */
     public function count()
     {
         return count($this->violations);

src/Symfony/Component/Validator/GraphWalker.php

@@ -20,6 +20,13 @@
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 use Symfony\Component\Validator\Mapping\MemberMetadata;
 
+/**
+ * Responsible for walking over and initializing validation on different
+ * types of items.
+ *
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ */
 class GraphWalker
 {
     protected $context;
@@ -33,11 +40,23 @@ public function __construct($root, ClassMetadataFactoryInterface $metadataFactor
         $this->metadataFactory = $metadataFactory;
     }
 
+    /**
+     * @return ConstraintViolationList
+     */
     public function getViolations()
     {
         return $this->context->getViolations();
     }
 
+    /**
+     * Initialize validation on the given object using the given metadata
+     * instance and validation group.
+     *
+     * @param ClassMetadata $metadata
+     * @param  object $object The object to validate
+     * @param  string $group The validator group to use for validation
+     * @param  string $propertyPath
+     */
     public function walkClass(ClassMetadata $metadata, $object, $group, $propertyPath)
     {
         $this->context->setCurrentClass($metadata->getClassName());

src/Symfony/Component/Validator/Mapping/ClassMetadata.php

@@ -16,6 +16,12 @@
 use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
 use Symfony\Component\Validator\Exception\GroupDefinitionException;
 
+/**
+ * Represents all the configured constraints on a given class.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ */
 class ClassMetadata extends ElementMetadata
 {
     public $name;
@@ -70,12 +76,12 @@ public function getClassName()
      *
      * For each class, the group "Default" is an alias for the group
      * "<ClassName>", where <ClassName> is the non-namespaced name of the
-     * class. All constraints implicitely or explicitely assigned to group
+     * class. All constraints implicitly or explicitly assigned to group
      * "Default" belong to both of these groups, unless the class defines
      * a group sequence.
      *
      * If a class defines a group sequence, validating the class in "Default"
-     * will validate the group sequence. The constraints assinged to "Default"
+     * will validate the group sequence. The constraints assigned to "Default"
      * can still be validated by validating the class in "<ClassName>".
      *
      * @return string  The name of the default group
@@ -202,6 +208,7 @@ protected function addMemberMetadata(MemberMetadata $metadata)
      * Returns all metadatas of members describing the given property
      *
      * @param string $property The name of the property
+     * @array of MemberMetadata
      */
     public function getMemberMetadatas($property)
     {

src/Symfony/Component/Validator/ValidationContext.php

@@ -13,6 +13,15 @@
 
 use Symfony\Component\Validator\Mapping\ClassMetadataFactoryInterface;
 
+/**
+ * The central object representing a single validation process.
+ *
+ * This object is used by the GraphWalker to initialize validation of different
+ * items and keep track of the violations.
+ *
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ */
 class ValidationContext
 {
     protected $root;
@@ -52,6 +61,9 @@ public function addViolation($message, array $params, $invalidValue)
         ));
     }
 
+    /**
+     * @return ConstraintViolationList
+     */
     public function getViolations()
     {
         return $this->violations;
@@ -102,11 +114,17 @@ public function getGroup()
         return $this->group;
     }
 
+    /**
+     * @return GraphWalker
+     */
     public function getGraphWalker()
     {
         return $this->graphWalker;
     }
 
+    /**
+     * @return ClassMetadataFactoryInterface
+     */
     public function getClassMetadataFactory()
     {
         return $this->metadataFactory;

src/Symfony/Component/Validator/Validator.php

@@ -15,6 +15,15 @@
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 use Symfony\Component\Validator\Mapping\ClassMetadataFactoryInterface;
 
+/**
+ * The default implementation of the ValidatorInterface.
+ *
+ * This service can be used to validate objects, properties and raw values
+ * against constraints.
+ *
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ */
 class Validator implements ValidatorInterface
 {
     protected $metadataFactory;
@@ -29,6 +38,9 @@ public function __construct(
         $this->validatorFactory = $validatorFactory;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function validate($object, $groups = null)
     {
         $metadata = $this->metadataFactory->getClassMetadata(get_class($object));
@@ -40,6 +52,9 @@ public function validate($object, $groups = null)
         return $this->validateGraph($object, $walk, $groups);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function validateProperty($object, $property, $groups = null)
     {
         $metadata = $this->metadataFactory->getClassMetadata(get_class($object));
@@ -51,6 +66,9 @@ public function validateProperty($object, $property, $groups = null)
         return $this->validateGraph($object, $walk, $groups);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function validatePropertyValue($class, $property, $value, $groups = null)
     {
         $metadata = $this->metadataFactory->getClassMetadata($class);
@@ -62,6 +80,9 @@ public function validatePropertyValue($class, $property, $value, $groups = null)
         return $this->validateGraph($class, $walk, $groups);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function validateValue($value, Constraint $constraint, $groups = null)
     {
         $walk = function(GraphWalker $walker, $group) use ($constraint, $value) {