From 9ca61df9234afe72a7bf02a7e48646dfa74f6041 Mon Sep 17 00:00:00 2001
From: Bernhard Schussek <bschussek@gmail.com>
Date: Fri, 21 Feb 2014 16:40:31 +0100
Subject: [PATCH] [Validator] Improved inline documentation of
 CascadingStrategy and TraversalStrategy

---
 .../Validator/Mapping/CascadingStrategy.php   | 32 +++++++++++++++++--
 .../Validator/Mapping/TraversalStrategy.php   | 32 +++++++++++++++++--
 .../NonRecursiveNodeTraverser.php             |  2 ++
 3 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/src/Symfony/Component/Validator/Mapping/CascadingStrategy.php b/src/Symfony/Component/Validator/Mapping/CascadingStrategy.php
index 1218c2d484..ff2853f4e0 100644
--- a/src/Symfony/Component/Validator/Mapping/CascadingStrategy.php
+++ b/src/Symfony/Component/Validator/Mapping/CascadingStrategy.php
@@ -12,15 +12,41 @@
 namespace Symfony\Component\Validator\Mapping;
 
 /**
- * @since  %%NextVersion%%
+ * Specifies whether an object should be cascaded.
+ *
+ * Cascading is relevant for any node type but class nodes. If such a node
+ * contains an object of value, and if cascading is enabled, then the node
+ * traverser will try to find class metadata for that object and validate the
+ * object against that metadata.
+ *
+ * If no metadata is found for a cascaded object, and if that object implements
+ * {@link \Traversable}, the node traverser will iterate over the object and
+ * cascade each object or collection contained within, unless iteration is
+ * prohibited by the specified {@link TraversalStrategy}.
+ *
+ * Although the constants currently represent a boolean switch, they are
+ * implemented as bit mask in order to allow future extensions.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
+ *
+ * @see TraversalStrategy
  */
 class CascadingStrategy
 {
-    const NONE = 0;
+    /**
+     * Specifies that a node should not be cascaded.
+     */
+    const NONE = 1;
 
-    const CASCADE = 1;
+    /**
+     * Specifies that a node should be cascaded.
+     */
+    const CASCADE = 2;
 
+    /**
+     * Not instantiable.
+     */
     private function __construct()
     {
     }
diff --git a/src/Symfony/Component/Validator/Mapping/TraversalStrategy.php b/src/Symfony/Component/Validator/Mapping/TraversalStrategy.php
index 22b7f53455..7d74be1625 100644
--- a/src/Symfony/Component/Validator/Mapping/TraversalStrategy.php
+++ b/src/Symfony/Component/Validator/Mapping/TraversalStrategy.php
@@ -12,22 +12,50 @@
 namespace Symfony\Component\Validator\Mapping;
 
 /**
- * @since  %%NextVersion%%
+ * Specifies whether and how a traversable object should be traversed.
+ *
+ * If the node traverser traverses a node whose value is an instance of
+ * {@link \Traversable}, and if that node is either a class node or if
+ * cascading is enabled, then the node's traversal strategy will be checked.
+ * Depending on the requested traversal strategy, the node traverser will
+ * iterate over the object and cascade each object or collection returned by
+ * the iterator.
+ *
+ * The traversal strategy is ignored for arrays. Arrays are always iterated.
+ *
+ * @since  2.1
  * @author Bernhard Schussek <bschussek@gmail.com>
+ *
+ * @see CascadingStrategy
  */
 class TraversalStrategy
 {
     /**
-     * @var integer
+     * Specifies that a node's value should be iterated only if it is an
+     * instance of {@link \Traversable}.
      */
     const IMPLICIT = 1;
 
+    /**
+     * Specifies that a node's value should never be iterated.
+     */
     const NONE = 2;
 
+    /**
+     * Specifies that a node's value should always be iterated. If the value is
+     * not an instance of {@link \Traversable}, an exception should be thrown.
+     */
     const TRAVERSE = 4;
 
+    /**
+     * Specifies that nested instances of {@link \Traversable} should never be
+     * iterated. Can be combined with {@link IMPLICIT} or {@link TRAVERSE}.
+     */
     const STOP_RECURSION = 8;
 
+    /**
+     * Not instantiable.
+     */
     private function __construct()
     {
     }
diff --git a/src/Symfony/Component/Validator/NodeTraverser/NonRecursiveNodeTraverser.php b/src/Symfony/Component/Validator/NodeTraverser/NonRecursiveNodeTraverser.php
index 811849929b..5c904f01d4 100644
--- a/src/Symfony/Component/Validator/NodeTraverser/NonRecursiveNodeTraverser.php
+++ b/src/Symfony/Component/Validator/NodeTraverser/NonRecursiveNodeTraverser.php
@@ -55,6 +55,8 @@ use Symfony\Component\Validator\NodeVisitor\NodeVisitorInterface;
  * @author Bernhard Schussek <bschussek@gmail.com>
  *
  * @see NodeTraverserInterface
+ * @see CascadingStrategy
+ * @see TraversalStrategy
  */
 class NonRecursiveNodeTraverser implements NodeTraverserInterface
 {