From 2524356cfdccd03f4dff15fa1b1866d3e73e0caa Mon Sep 17 00:00:00 2001
From: Johannes <schmittjoh@gmail.com>
Date: Sat, 6 Oct 2012 17:19:47 +0300
Subject: [PATCH] added some doc about optional sections

refs symfony/symfony#5688
---
 components/config/definition.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/components/config/definition.rst b/components/config/definition.rst
index 00b2737ab4e..b7b33b90f52 100644
--- a/components/config/definition.rst
+++ b/components/config/definition.rst
@@ -212,6 +212,29 @@ has a certain value:
         ->end()
     ;
 
+Optional Sections
+-----------------
+If you have entire sections which are optional and can be enabled/disabled,
+you can take advantage of the shortcut ``canBeEnabled``, or ``canBeDisabled``::
+
+    $arrayNode
+        ->canBeEnabled()
+    ;
+
+    // is equivalent to
+
+    $arrayNode
+        ->treatFalseLike(array('enabled' => false))
+        ->treatTrueLike(array('enabled' => true))
+        ->treatNullLike(array('enabled' => true))
+        ->children()
+            ->booleanNode('enabled')
+                ->defaultFalse()
+    ;
+
+``canBeDisabled`` looks about the same with the difference that the section 
+would be enabled by default.
+
 Merging options
 ---------------