[Validator] Completed test coverage and documentation of the Node classes

src/Symfony/Component/Validator/Node/ClassNode.php

@@ -11,10 +11,13 @@
 
 namespace Symfony\Component\Validator\Node;
 
+use Symfony\Component\Validator\Exception\UnexpectedTypeException;
 use Symfony\Component\Validator\Mapping\ClassMetadataInterface;
 
 /**
- * @since  %%NextVersion%%
+ * Represents an object and its class metadata in the validation graph.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class ClassNode extends Node
@@ -24,19 +27,34 @@ class ClassNode extends Node
      */
     public $metadata;
 
-    public function __construct($value, ClassMetadataInterface $metadata, $propertyPath, array $groups, array $cascadedGroups)
+    /**
+     * Creates a new class node.
+     *
+     * @param object                 $object         The validated object
+     * @param ClassMetadataInterface $metadata       The class metadata of that
+     *                                               object
+     * @param string                 $propertyPath   The property path leading
+     *                                               to this node
+     * @param string[]               $groups         The groups in which this
+     *                                               node should be validated
+     * @param string[]               $cascadedGroups The groups in which
+     *                                               cascaded objects should be
+     *                                               validated
+     *
+     * @throws UnexpectedTypeException If the given value is not an object
+     */
+    public function __construct($object, ClassMetadataInterface $metadata, $propertyPath, array $groups, array $cascadedGroups)
     {
-        if (!is_object($value)) {
+        if (!is_object($object)) {
-            // error
+            throw new UnexpectedTypeException($object, 'object');
         }
 
         parent::__construct(
-            $value,
+            $object,
             $metadata,
             $propertyPath,
             $groups,
             $cascadedGroups
         );
     }
-
 }

src/Symfony/Component/Validator/Node/GenericNode.php

@@ -12,7 +12,14 @@
 namespace Symfony\Component\Validator\Node;
 
 /**
- * @since  %%NextVersion%%
+ * Represents a value that has neither class metadata nor property metadata
+ * attached to it.
+ *
+ * Together with {@link \Symfony\Component\Validator\Mapping\GenericMetadata},
+ * this node type can be used to validate a value against some given
+ * constraints.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class GenericNode extends Node

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

@@ -14,21 +14,60 @@ namespace Symfony\Component\Validator\Node;
 use Symfony\Component\Validator\Mapping\MetadataInterface;
 
 /**
- * @since  %%NextVersion%%
+ * A node in the validated graph.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 abstract class Node
 {
+    /**
+     * The validated value.
+     *
+     * @var mixed
+     */
     public $value;
 
+    /**
+     * The metadata specifying how the value should be validated.
+     *
+     * @var MetadataInterface
+     */
     public $metadata;
 
+    /**
+     * The property path leading to this node.
+     *
+     * @var string
+     */
     public $propertyPath;
 
+    /**
+     * The groups in which the value should be validated.
+     *
+     * @var string[]
+     */
     public $groups;
 
+    /**
+     * The groups in which cascaded values should be validated.
+     *
+     * @var string[]
+     */
     public $cascadedGroups;
 
+    /**
+     * Creates a new property node.
+     *
+     * @param mixed             $value          The property value
+     * @param MetadataInterface $metadata       The property's metadata
+     * @param string            $propertyPath   The property path leading to
+     *                                          this node
+     * @param string[]          $groups         The groups in which this node
+     *                                          should be validated
+     * @param string[]          $cascadedGroups The groups in which cascaded
+     *                                          objects should be validated
+     */
     public function __construct($value, MetadataInterface $metadata, $propertyPath, array $groups, array $cascadedGroups)
     {
         $this->value = $value;

src/Symfony/Component/Validator/Node/PropertyNode.php

@@ -14,7 +14,20 @@ namespace Symfony\Component\Validator\Node;
 use Symfony\Component\Validator\Mapping\PropertyMetadataInterface;
 
 /**
- * @since  %%NextVersion%%
+ * Represents the value of a property and its associated metadata.
+ *
+ * If the property contains an object and should be cascaded, a new
+ * {@link ClassNode} instance will be created for that object.
+ *
+ * Example:
+ *
+ *     (Article:ClassNode)
+ *                \
+ *        (author:PropertyNode)
+ *                  \
+ *            (Author:ClassNode)
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class PropertyNode extends Node
@@ -24,6 +37,19 @@ class PropertyNode extends Node
      */
     public $metadata;
 
+    /**
+     * Creates a new property node.
+     *
+     * @param mixed                     $value          The property value
+     * @param PropertyMetadataInterface $metadata       The property's metadata
+     * @param string                    $propertyPath   The property path leading
+     *                                                  to this node
+     * @param string[]                  $groups         The groups in which this
+     *                                                  node should be validated
+     * @param string[]                  $cascadedGroups The groups in which
+     *                                                  cascaded objects should
+     *                                                  be validated
+     */
     public function __construct($value, PropertyMetadataInterface $metadata, $propertyPath, array $groups, array $cascadedGroups)
     {
         parent::__construct(

src/Symfony/Component/Validator/Tests/Node/ClassNodeTest.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator\Tests\Node;
+
+use Symfony\Component\Validator\Node\ClassNode;
+
+/**
+ * @since  2.5
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class ClassNodeTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @expectedException \Symfony\Component\Validator\Exception\UnexpectedTypeException
+     */
+    public function testConstructorExpectsObject()
+    {
+        $metadata = $this->getMock('Symfony\Component\Validator\Mapping\ClassMetadataInterface');
+
+        new ClassNode('foobar', $metadata, '', array(), array());
+    }
+}