[Validator] Improved inline documentation of the violation builder

symfony · fabpot · Mar 31, 2014 · Feb 12, 2014 · Feb 17, 2014 · Feb 17, 2014
commit 987313d315f1083e3e5a7fd6f25b91e93cbcccaa
diff --git a/src/Symfony/Component/Validator/ConstraintViolation.php b/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       $messageTemplate       The raw violation message.
-     * @param array        $messageParameters     The parameters to substitute
-     *                                            in the raw message.
-     * @param mixed        $root                  The value originally passed
-     *                                            to the validator.
-     * @param string       $propertyPath          The property path from the
-     *                                            root value to the invalid
-     *                                            value.
-     * @param mixed        $invalidValue          The invalid value causing the
-     *                                            violation.
-     * @param integer|null $messagePluralization  The pluralization parameter.
-     * @param mixed        $code                  The error code of the
-     *                                            violation, if any.
-     */
-    public function __construct($message, $messageTemplate, array $messageParameters, $root, $propertyPath, $invalidValue, $messagePluralization = null, $code = null)
+     * @param string       $message         The violation message
+     * @param string       $messageTemplate The raw violation message
+     * @param array        $parameters      The parameters to substitute in the
+     *                                      raw violation message
+     * @param mixed        $root            The value originally passed to the
+     *                                      validator
+     * @param string       $propertyPath    The property path from the root
+     *                                      value to the invalid value
+     * @param mixed        $invalidValue    The invalid value that caused this
+     *                                      violation
+     * @param integer|null $plural          The number for determining the plural
+     *                                      form when translation the message
+     * @param mixed        $code            The error code of the violation
+     */
+    public function __construct($message, $messageTemplate, array $parameters, $root, $propertyPath, $invalidValue, $plural = null, $code = null)
     {
         $this->message = $message;
         $this->messageTemplate = $messageTemplate;
-        $this->messageParameters = $messageParameters;
-        $this->messagePluralization = $messagePluralization;
+        $this->parameters = $parameters;
+        $this->plural = $plural;
         $this->root = $root;
         $this->propertyPath = $propertyPath;
         $this->invalidValue = $invalidValue;
@@ -130,15 +129,31 @@ public function getMessageTemplate()
      */
     public function getMessageParameters()
     {
-        return $this->messageParameters;
+        return $this->parameters;
+    }
+
+    /**
+     * Alias of {@link getMessageParameters()}.
+     */
+    public function getParameters()
+    {
+        return $this->parameters;
     }
 
     /**
      * {@inheritDoc}
      */
     public function getMessagePluralization()
     {
-        return $this->messagePluralization;
+        return $this->plural;
+    }
+
+    /**
+     * Alias of {@link getMessagePluralization()}.
+     */
+    public function getPlural()
+    {
+        return $this->plural;
     }
 
     /**

diff --git a/src/Symfony/Component/Validator/Context/ExecutionContext.php b/src/Symfony/Component/Validator/Context/ExecutionContext.php
@@ -30,6 +30,9 @@
  * @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
 {

diff --git a/src/Symfony/Component/Validator/Context/ExecutionContextFactory.php b/src/Symfony/Component/Validator/Context/ExecutionContextFactory.php
@@ -20,6 +20,9 @@
  *
  * @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
 {

diff --git a/src/Symfony/Component/Validator/Tests/Validator/Abstract2Dot5ApiTest.php b/src/Symfony/Component/Validator/Tests/Validator/Abstract2Dot5ApiTest.php
@@ -538,7 +538,7 @@ public function testAddCustomizedViolation()
             $context->buildViolation('Message %param%')
                 ->setParameter('%param%', 'value')
                 ->setInvalidValue('Invalid value')
-                ->setPluralization(2)
+                ->setPlural(2)
                 ->setCode('Code')
                 ->addViolation();
         };

diff --git a/src/Symfony/Component/Validator/Violation/ConstraintViolationBuilder.php b/src/Symfony/Component/Validator/Violation/ConstraintViolationBuilder.php
@@ -17,29 +17,64 @@
 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,58 +89,82 @@ public function __construct(ConstraintViolationList $violations, $message, array
         $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;
 
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setParameters(array $parameters)
     {
         $this->parameters = $parameters;
 
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setTranslationDomain($translationDomain)
     {
         $this->translationDomain = $translationDomain;
 
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setInvalidValue($invalidValue)
     {
         $this->invalidValue = $invalidValue;
 
         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;
 
         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 @@ public function addViolation()
             try {
                 $translatedMessage = $this->translator->transChoice(
                     $this->message,
-                    $this->pluralization,
+                    $this->plural,
                     $this->parameters,
                     $this->translationDomain#
                 );
@@ -135,7 +194,7 @@ public function addViolation()
             $this->root,
             $this->propertyPath,
             $this->invalidValue,
-            $this->pluralization,
+            $this->plural,
             $this->code
         ));
     }

diff --git a/src/Symfony/Component/Validator/Violation/ConstraintViolationBuilderInterface.php b/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();
 }