[Validator] Improved inline documentation of the violation builder

src/Symfony/Component/Validator/ConstraintViolation.php

@@ -31,12 +31,12 @@ class ConstraintViolation implements ConstraintViolationInterface
     /**
      * @var array
      */
-    private $messageParameters;
+    private $parameters;
 
     /**
      * @var integer|null
      */
-    private $messagePluralization;
+    private $plural;
 
     /**
      * @var mixed
@@ -61,27 +61,26 @@ class ConstraintViolation implements ConstraintViolationInterface
     /**
      * Creates a new constraint violation.
      *
-     * @param string       $message               The violation message.
+     * @param string       $message         The violation message
-     * @param string       $messageTemplate       The raw violation message.
+     * @param string       $messageTemplate The raw violation message
-     * @param array        $messageParameters     The parameters to substitute
+     * @param array        $parameters      The parameters to substitute in the
-     *                                            in the raw message.
+     *                                      raw violation message
-     * @param mixed        $root                  The value originally passed
+     * @param mixed        $root            The value originally passed to the
-     *                                            to the validator.
+     *                                      validator
-     * @param string       $propertyPath          The property path from the
+     * @param string       $propertyPath    The property path from the root
-     *                                            root value to the invalid
+     *                                      value to the invalid value
-     *                                            value.
+     * @param mixed        $invalidValue    The invalid value that caused this
-     * @param mixed        $invalidValue          The invalid value causing the
+     *                                      violation
-     *                                            violation.
+     * @param integer|null $plural          The number for determining the plural
-     * @param integer|null $messagePluralization  The pluralization parameter.
+     *                                      form when translation the message
-     * @param mixed        $code                  The error code of the
+     * @param mixed        $code            The error code of the violation
-     *                                            violation, if any.
      */
-    public function __construct($message, $messageTemplate, array $messageParameters, $root, $propertyPath, $invalidValue, $messagePluralization = null, $code = null)
+    public function __construct($message, $messageTemplate, array $parameters, $root, $propertyPath, $invalidValue, $plural = null, $code = null)
     {
         $this->message = $message;
         $this->messageTemplate = $messageTemplate;
-        $this->messageParameters = $messageParameters;
+        $this->parameters = $parameters;
-        $this->messagePluralization = $messagePluralization;
+        $this->plural = $plural;
         $this->root = $root;
         $this->propertyPath = $propertyPath;
         $this->invalidValue = $invalidValue;
@@ -130,7 +129,15 @@ class ConstraintViolation implements ConstraintViolationInterface
      */
     public function getMessageParameters()
     {
-        return $this->messageParameters;
+        return $this->parameters;
+    }
+
+    /**
+     * Alias of {@link getMessageParameters()}.
+     */
+    public function getParameters()
+    {
+        return $this->parameters;
     }
 
     /**
@@ -138,7 +145,15 @@ class ConstraintViolation implements ConstraintViolationInterface
      */
     public function getMessagePluralization()
     {
-        return $this->messagePluralization;
+        return $this->plural;
+    }
+
+    /**
+     * Alias of {@link getMessagePluralization()}.
+     */
+    public function getPlural()
+    {
+        return $this->plural;
     }
 
     /**

src/Symfony/Component/Validator/Context/ExecutionContext.php

@@ -30,6 +30,9 @@ use Symfony\Component\Validator\Violation\ConstraintViolationBuilder;
  * @author Bernhard Schussek <bschussek@gmail.com>
  *
  * @see ExecutionContextInterface
+ *
+ * @internal You should not instantiate or use this class. Code against
+ *           {@link ExecutionContextInterface} instead.
  */
 class ExecutionContext implements ExecutionContextInterface
 {

src/Symfony/Component/Validator/Context/ExecutionContextFactory.php

@@ -20,6 +20,9 @@ use Symfony\Component\Validator\Validator\ValidatorInterface;
  *
  * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
+ *
+ * @internal You should not instantiate or use this class. Code against
+ *           {@link ExecutionContextFactoryInterface} instead.
  */
 class ExecutionContextFactory implements ExecutionContextFactoryInterface
 {

src/Symfony/Component/Validator/Tests/Validator/Abstract2Dot5ApiTest.php

@@ -538,7 +538,7 @@ abstract class Abstract2Dot5ApiTest extends AbstractValidatorTest
             $context->buildViolation('Message %param%')
                 ->setParameter('%param%', 'value')
                 ->setInvalidValue('Invalid value')
-                ->setPluralization(2)
+                ->setPlural(2)
                 ->setCode('Code')
                 ->addViolation();
         };

src/Symfony/Component/Validator/Violation/ConstraintViolationBuilder.php

@@ -17,29 +17,64 @@ use Symfony\Component\Validator\ConstraintViolationList;
 use Symfony\Component\Validator\Util\PropertyPath;
 
 /**
- * @since  %%NextVersion%%
+ * Default implementation of {@link ConstraintViolationBuilderInterface}.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
+ *
+ * @internal You should not instantiate or use this class. Code against
+ *           {@link ConstraintViolationBuilderInterface} instead.
  */
 class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
 {
+    /**
+     * @var ConstraintViolationList
+     */
     private $violations;
 
+    /**
+     * @var string
+     */
     private $message;
 
+    /**
+     * @var array
+     */
     private $parameters;
 
+    /**
+     * @var mixed
+     */
     private $root;
 
+    /**
+     * @var mixed
+     */
     private $invalidValue;
 
+    /**
+     * @var string
+     */
     private $propertyPath;
 
+    /**
+     * @var TranslatorInterface
+     */
     private $translator;
 
+    /**
+     * @var string|null
+     */
     private $translationDomain;
 
-    private $pluralization;
+    /**
+     * @var integer|null
+     */
+    private $plural;
 
+    /**
+     * @var mixed
+     */
     private $code;
 
     public function __construct(ConstraintViolationList $violations, $message, array $parameters, $root, $propertyPath, $invalidValue, TranslatorInterface $translator, $translationDomain = null)
@@ -54,13 +89,19 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
         $this->translationDomain = $translationDomain;
     }
 
-    public function atPath($subPath)
+    /**
+     * {@inheritdoc}
+     */
+    public function atPath($path)
     {
-        $this->propertyPath = PropertyPath::append($this->propertyPath, $subPath);
+        $this->propertyPath = PropertyPath::append($this->propertyPath, $path);
 
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setParameter($key, $value)
     {
         $this->parameters[$key] = $value;
@@ -68,6 +109,9 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setParameters(array $parameters)
     {
         $this->parameters = $parameters;
@@ -75,6 +119,9 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setTranslationDomain($translationDomain)
     {
         $this->translationDomain = $translationDomain;
@@ -82,6 +129,9 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setInvalidValue($invalidValue)
     {
         $this->invalidValue = $invalidValue;
@@ -89,13 +139,19 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
         return $this;
     }
 
-    public function setPluralization($pluralization)
+    /**
+     * {@inheritdoc}
+     */
+    public function setPlural($number)
     {
-        $this->pluralization = $pluralization;
+        $this->plural = $number;
 
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setCode($code)
     {
         $this->code = $code;
@@ -103,9 +159,12 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function addViolation()
     {
-        if (null === $this->pluralization) {
+        if (null === $this->plural) {
             $translatedMessage = $this->translator->trans(
                 $this->message,
                 $this->parameters,
@@ -115,7 +174,7 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
             try {
                 $translatedMessage = $this->translator->transChoice(
                     $this->message,
-                    $this->pluralization,
+                    $this->plural,
                     $this->parameters,
                     $this->translationDomain#
                 );
@@ -135,7 +194,7 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
             $this->root,
             $this->propertyPath,
             $this->invalidValue,
-            $this->pluralization,
+            $this->plural,
             $this->code
         ));
     }

src/Symfony/Component/Validator/Violation/ConstraintViolationBuilderInterface.php

@@ -12,24 +12,97 @@
 namespace Symfony\Component\Validator\Violation;
 
 /**
- * @since  %%NextVersion%%
+ * Builds {@link \Symfony\Component\Validator\ConstraintViolationInterface}
+ * objects.
+ *
+ * Use the various methods on this interface to configure the built violation.
+ * Finally, call {@link addViolation()} to add the violation to the current
+ * execution context.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 interface ConstraintViolationBuilderInterface
 {
-    public function atPath($subPath);
+    /**
+     * Stores the property path at which the violation should be generated.
+     *
+     * The passed path will be appended to the current property path of the
+     * execution context.
+     *
+     * @param string $path The property path
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     */
+    public function atPath($path);
 
+    /**
+     * Sets a parameter to be inserted into the violation message.
+     *
+     * @param string $key   The name of the parameter
+     * @param string $value The value to be inserted in the parameter's place
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     */
     public function setParameter($key, $value);
 
+    /**
+     * Sets all parameters to be inserted into the violation message.
+     *
+     * @param array $parameters An array with the parameter names as keys and
+     *                          the values to be inserted in their place as
+     *                          values
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     */
     public function setParameters(array $parameters);
 
+    /**
+     * Sets the translation domain which should be used for translating the
+     * violation message.
+     *
+     * @param string $translationDomain The translation domain
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     *
+     * @see \Symfony\Component\Translation\TranslatorInterface
+     */
     public function setTranslationDomain($translationDomain);
 
+    /**
+     * Sets the invalid value that caused this violation.
+     *
+     * @param mixed $invalidValue The invalid value
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     */
     public function setInvalidValue($invalidValue);
 
-    public function setPluralization($pluralization);
+    /**
+     * Sets the number which determines how the plural form of the violation
+     * message is chosen when it is translated.
+     *
+     * @param integer $number The number for determining the plural form
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     *
+     * @see \Symfony\Component\Translation\TranslatorInterface::transChoice()
+     */
+    public function setPlural($number);
 
+    /**
+     * Sets the violation code.
+     *
+     * @param mixed $code The violation code
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     *
+     * @internal This method is internal and should not be used by user code
+     */
     public function setCode($code);
 
+    /**
+     * Adds the violation to the current execution context.
+     */
     public function addViolation();
 }