[Config] cleanup

src/Symfony/Component/Config/Definition/BaseNode.php

@@ -56,7 +56,7 @@ abstract class BaseNode implements NodeInterface
     }
 
     /**
-     * Sets info message
+     * Sets info message.
      *
      * @param string $info The info text
      */
@@ -66,7 +66,7 @@ abstract class BaseNode implements NodeInterface
     }
 
     /**
-     * Returns info message
+     * Returns info message.
      *
      * @return string The info text
      */
@@ -78,7 +78,7 @@ abstract class BaseNode implements NodeInterface
     /**
      * Sets the example configuration for this node.
      *
-     * @param array $example
+     * @param string|array $example
      */
     public function setExample($example)
     {
@@ -88,7 +88,7 @@ abstract class BaseNode implements NodeInterface
     /**
      * Retrieves the example configuration for this node.
      *
-     * @return mixed The example
+     * @return string|array The example
      */
     public function getExample()
     {

src/Symfony/Component/Config/Definition/Builder/ArrayNodeDefinition.php

@@ -50,7 +50,7 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
     }
 
     /**
-     * Set a custom children builder
+     * Sets a custom children builder.
      *
      * @param NodeBuilder $builder A custom NodeBuilder
      */
@@ -60,7 +60,7 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
     }
 
     /**
-     * Returns a builder to add children nodes
+     * Returns a builder to add children nodes.
      *
      * @return NodeBuilder
      */
@@ -78,16 +78,16 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
      */
     public function prototype($type)
     {
-        $builder = $this->getNodeBuilder();
+        return $this->prototype = $this->getNodeBuilder()->node(null, $type)->setParent($this);
-        $this->prototype = $builder->node(null, $type);
-        $this->prototype->parent = $this;
-
-        return $this->prototype;
     }
 
     /**
      * Adds the default value if the node is not set in the configuration.
      *
+     * This method is applicable to concrete nodes only (not to prototype nodes).
+     * If this function has been called and the node is not set during the finalization
+     * phase, it's default value will be derived from its children default values.
+     *
      * @return ArrayNodeDefinition
      */
     public function addDefaultsIfNotSet()
@@ -100,6 +100,8 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
     /**
      * Requires the node to have at least one element.
      *
+     * This method is applicable to prototype nodes only.
+     *
      * @return ArrayNodeDefinition
      */
     public function requiresAtLeastOneElement()
@@ -139,7 +141,7 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
     }
 
     /**
-     * Set the attribute which value is to be used as key.
+     * Sets the attribute which value is to be used as key.
      *
      * This is useful when you have an indexed array that should be an
      * associative array. You can select an item from within the array
@@ -148,17 +150,19 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
      *
      *     array(
      *         array('id' => 'my_name', 'foo' => 'bar'),
-     *     )
+     *     );
      *
-     * becomes
+     *   becomes
      *
      *     array(
      *         'my_name' => array('foo' => 'bar'),
-     *     )
+     *     );
      *
      * If you'd like "'id' => 'my_name'" to still be present in the resulting
      * array, then you can set the second argument of this method to false.
      *
+     * This method is applicable to prototype nodes only.
+     *
      * @param string  $name          The name of the key
      * @param Boolean $removeKeyItem Whether or not the key item should be removed.
      *
@@ -216,12 +220,12 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
     }
 
     /**
-     * Append a node definition.
+     * Appends a node definition.
      *
      *     $node = new ArrayNodeDefinition()
      *         ->children()
-     *             ->scalarNode('foo')
+     *             ->scalarNode('foo')->end()
-     *             ->scalarNode('baz')
+     *             ->scalarNode('baz')->end()
      *         ->end()
      *         ->append($this->getBarNodeDefinition())
      *     ;
@@ -254,10 +258,30 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
      */
     protected function createNode()
     {
-        if (null == $this->prototype) {
+        if (null === $this->prototype) {
             $node = new ArrayNode($this->name, $this->parent);
+
+            foreach ($this->children as $child) {
+                $child->parent = $node;
+                $node->addChild($child->getNode());
+            }
         } else {
             $node = new PrototypedArrayNode($this->name, $this->parent);
+
+            if (null !== $this->key) {
+                $node->setKeyAttribute($this->key, $this->removeKeyItem);
+            }
+
+            if (true === $this->atLeastOne) {
+                $node->setMinNumberOfElements(1);
+            }
+
+            if ($this->default) {
+                $node->setDefaultValue($this->defaultValue);
+            }
+
+            $this->prototype->parent = $node;
+            $node->setPrototype($this->prototype->getNode());
         }
 
         $node->setAddIfNotSet($this->addDefaults);
@@ -283,28 +307,6 @@ class ArrayNodeDefinition extends NodeDefinition implements ParentNodeDefinition
             $node->setFinalValidationClosures($this->validation->rules);
         }
 
-        if (null == $this->prototype) {
-            foreach ($this->children as $child) {
-                $child->parent = $node;
-                $node->addChild($child->getNode());
-            }
-        } else {
-            if (null !== $this->key) {
-                $node->setKeyAttribute($this->key, $this->removeKeyItem);
-            }
-
-            if (true === $this->atLeastOne) {
-                $node->setMinNumberOfElements(1);
-            }
-
-            if (null !== $this->defaultValue) {
-                $node->setDefaultValue($this->defaultValue);
-            }
-
-            $this->prototype->parent = $node;
-            $node->setPrototype($this->prototype->getNode());
-        }
-
         return $node;
     }
 

src/Symfony/Component/Config/Definition/Builder/ExprBuilder.php

@@ -35,7 +35,7 @@ class ExprBuilder
     }
 
     /**
-     * Mark the expression as being always used.
+     * Marks the expression as being always used.
      *
      * @return ExprBuilder
      */

src/Symfony/Component/Config/Definition/Builder/NodeBuilder.php

@@ -36,7 +36,7 @@ class NodeBuilder implements NodeParentInterface
     }
 
     /**
-     * Set the parent node
+     * Set the parent node.
      *
      * @param ParentNodeDefinitionInterface $parent The parent node
      *
@@ -50,7 +50,7 @@ class NodeBuilder implements NodeParentInterface
     }
 
     /**
-     * Creates a child array node
+     * Creates a child array node.
      *
      * @param string $name The name of the node
      *
@@ -130,12 +130,14 @@ class NodeBuilder implements NodeParentInterface
     }
 
     /**
-     * Append a node definition.
+     * Appends a node definition.
+     *
+     * Usage:
      *
      *     $node = new ArrayNodeDefinition('name')
      *         ->children()
-     *             ->scalarNode('foo')
+     *             ->scalarNode('foo')->end()
-     *             ->scalarNode('baz')
+     *             ->scalarNode('baz')->end()
      *             ->append($this->getBarNodeDefinition())
      *         ->end()
      *     ;
@@ -160,7 +162,7 @@ class NodeBuilder implements NodeParentInterface
     }
 
     /**
-     * Add or override a node Type
+     * Adds or overrides a node Type.
      *
      * @param string $type The name of the type
      * @param string $class The fully qualified name the node definition class
@@ -175,7 +177,7 @@ class NodeBuilder implements NodeParentInterface
     }
 
     /**
-     * Returns the class name of the node definition
+     * Returns the class name of the node definition.
      *
      * @param string $type The node type
      *

src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php

@@ -52,7 +52,7 @@ abstract class NodeDefinition implements NodeParentInterface
     }
 
     /**
-     * Sets the parent node
+     * Sets the parent node.
      *
      * @param NodeParentInterface $parent The parent
      */
@@ -64,7 +64,7 @@ abstract class NodeDefinition implements NodeParentInterface
     }
 
     /**
-     * Sets info message
+     * Sets info message.
      *
      * @param string $info The info text
      *
@@ -78,9 +78,9 @@ abstract class NodeDefinition implements NodeParentInterface
     }
 
     /**
-     * Sets example configuration
+     * Sets example configuration.
      *
-     * @param example $example
+     * @param string|array $example
      *
      * @return NodeDefinition
      */
@@ -229,20 +229,6 @@ abstract class NodeDefinition implements NodeParentInterface
         return $this->defaultValue(false);
     }
 
-    /**
-     * Gets the builder for normalization rules.
-     *
-     * @return NormalizationBuilder
-     */
-    protected function normalization()
-    {
-        if (null === $this->normalization) {
-            $this->normalization = new NormalizationBuilder($this);
-        }
-
-        return $this->normalization;
-    }
-
     /**
      * Sets an expression to run before the normalization.
      *
@@ -265,20 +251,6 @@ abstract class NodeDefinition implements NodeParentInterface
         return $this;
     }
 
-    /**
-     * Gets the builder for validation rules.
-     *
-     * @return ValidationBuilder
-     */
-    protected function validation()
-    {
-        if (null === $this->validation) {
-            $this->validation = new ValidationBuilder($this);
-        }
-
-        return $this->validation;
-    }
-
     /**
      * Sets an expression to run for the validation.
      *
@@ -293,20 +265,6 @@ abstract class NodeDefinition implements NodeParentInterface
         return $this->validation()->rule();
     }
 
-    /**
-     * Gets the builder for merging rules.
-     *
-     * @return MergeBuilder
-     */
-    protected function merge()
-    {
-        if (null === $this->merge) {
-            $this->merge = new MergeBuilder($this);
-        }
-
-        return $this->merge;
-    }
-
     /**
      * Sets whether the node can be overwritten.
      *
@@ -321,6 +279,48 @@ abstract class NodeDefinition implements NodeParentInterface
         return $this;
     }
 
+    /**
+     * Gets the builder for validation rules.
+     *
+     * @return ValidationBuilder
+     */
+    protected function validation()
+    {
+        if (null === $this->validation) {
+            $this->validation = new ValidationBuilder($this);
+        }
+
+        return $this->validation;
+    }
+
+    /**
+     * Gets the builder for merging rules.
+     *
+     * @return MergeBuilder
+     */
+    protected function merge()
+    {
+        if (null === $this->merge) {
+            $this->merge = new MergeBuilder($this);
+        }
+
+        return $this->merge;
+    }
+
+    /**
+     * Gets the builder for normalization rules.
+     *
+     * @return NormalizationBuilder
+     */
+    protected function normalization()
+    {
+        if (null === $this->normalization) {
+            $this->normalization = new NormalizationBuilder($this);
+        }
+
+        return $this->normalization;
+    }
+
     /**
      * Instantiate and configure the node according to this definition
      *

src/Symfony/Component/Config/Definition/Builder/TreeBuilder.php

@@ -35,12 +35,9 @@ class TreeBuilder implements NodeParentInterface
      */
     public function root($name, $type = 'array', NodeBuilder $builder = null)
     {
-        $builder = null === $builder ? new NodeBuilder() : $builder;
+        $builder = $builder ?: new NodeBuilder();
 
-        $this->root = $builder->node($name, $type);
+        return $this->root = $builder->node($name, $type)->setParent($this);
-        $this->root->setParent($this);
-
-        return $this->root;
     }
 
     /**

src/Symfony/Component/Config/Definition/PrototypedArrayNode.php

@@ -39,6 +39,7 @@ class PrototypedArrayNode extends ArrayNode
         parent::__construct($name, $parent);
 
         $this->minNumberOfElements = 0;
+        $this->defaultValue = array();
     }
 
     /**
@@ -53,21 +54,25 @@ class PrototypedArrayNode extends ArrayNode
     }
 
     /**
-     * The name of the attribute which value should be used as key.
+     * Sets the attribute which value is to be used as key.
      *
-     * This is only relevant for XML configurations, and only in combination
+     * This is useful when you have an indexed array that should be an
-     * with a prototype based node.
+     * associative array. You can select an item from within the array
+     * to be the key of the particular item. For example, if "id" is the
+     * "key", then:
      *
-     * For example, if "id" is the keyAttribute, then:
+     *     array(
+     *         array('id' => 'my_name', 'foo' => 'bar'),
+     *     );
      *
-     *     array('id' => 'my_name', 'foo' => 'bar')
+     *  becomes
      *
-     * becomes
+     *      array(
+     *          'my_name' => array('foo' => 'bar'),
+     *      );
      *
-     *     'my_name' => array('foo' => 'bar')
+     * If you'd like "'id' => 'my_name'" to still be present in the resulting
-     *
+     * array, then you can set the second argument of this method to false.
-     * If $remove is false, the resulting array will still have the
-     * "'id' => 'my_name'" item in it.
      *
      * @param string  $attribute The name of the attribute which value is to be used as a key
      * @param Boolean $remove Whether or not to remove the key
@@ -121,7 +126,7 @@ class PrototypedArrayNode extends ArrayNode
      */
     public function getDefaultValue()
     {
-        return $this->defaultValue ?: array();
+        return $this->defaultValue;
     }
 
     /**
@@ -161,7 +166,7 @@ class PrototypedArrayNode extends ArrayNode
      *
      * @param mixed $value
      *
-     * @return mixed The finalised value
+     * @return mixed The finalized value
      *
      * @throws UnsetKeyException
      * @throws InvalidConfigurationException if the node doesn't have enough children