From 924b2867222d3211807d1be0ba573909393d9dac Mon Sep 17 00:00:00 2001
From: David Buchmann <david.buchmann@liip.ch>
Date: Fri, 10 Jan 2014 13:24:08 +0100
Subject: [PATCH] document the menu prefetch option

---
 reference/configuration/menu.rst | 43 ++++++++++++++++++++++++--------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/reference/configuration/menu.rst b/reference/configuration/menu.rst
index e7996080..69783eaf 100644
--- a/reference/configuration/menu.rst
+++ b/reference/configuration/menu.rst
@@ -27,6 +27,7 @@ persistence configuration has the following configuration:
                     enabled:              false
                     menu_basepath:        /cms/menu
                     content_basepath:     ~
+                    prefetch:             10
                     manager_name:         ~
                     menu_document_class:  Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu
                     node_document_class:  Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode
@@ -46,6 +47,7 @@ persistence configuration has the following configuration:
                         enabled="false"
                         menu-basepath="/cms/menu"
                         content-basepath="null"
+                        prefetch="10"
                         manager-name="null"
                         menu-document-class="null"
                         node-document-class="null"
@@ -66,6 +68,7 @@ persistence configuration has the following configuration:
                     'enabled' => false,
                     'menu_basepath' => '/cms/menu',
                     'content_basepath' => null,
+                    'prefetch' => 10,
                     'manager_name' => null,
                     'menu_document_class' => null,
                     'node_document_class' => null,
@@ -82,11 +85,6 @@ enabled
 
 .. include:: partials/persistence_phpcr_enabled.rst.inc
 
-manager_name
-""""""""""""
-
-.. include:: partials/persistence_phpcr_manager_name.rst.inc
-
 menu_basepath
 """""""""""""
 
@@ -95,7 +93,7 @@ menu_basepath
 Specifies the path in the PHPCR-ODM document hierarchy under which the menu
 documents can be found.
 
-* This is the default location used by the 
+* This is the default location used by the
   :doc:`MenuProvider <../../bundles/menu/menu_factory>` to locate menus.
 * This is the default location for newly created menus in the Sonata admin
   class.
@@ -115,8 +113,31 @@ the content branch of the document hierarchy in forms.
 If the :doc:`CoreBundle <../../bundles/core/index>` is registered, this will default to
 the value of ``%cmf_core.persistence.phpcr.basepath%/content``
 
-menu_document
-"""""""""""""
+.. versionadded:: 1.1
+
+    The prefetch functionality was added in MenuBundle 1.1.
+
+prefetch
+""""""""
+
+**type**: ``integer`` **default**: ``10``
+
+When rendering a menu, the whole menu tree needs to be loaded. To reduce the
+number of database requests that PHPCR needs to make, this setting makes the
+tree loader prefetch all menu nodes in one call.
+
+``10`` should be enough for most cases, if you have deeper menu structures you
+might want to increase this.
+
+To disable menu prefetch completely, set this option to ``0``.
+
+manager_name
+""""""""""""
+
+.. include:: partials/persistence_phpcr_manager_name.rst.inc
+
+menu_document_class
+"""""""""""""""""""
 
 **type**: ``string`` **default**:
 ``Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\Menu``
@@ -125,8 +146,8 @@ Specifies the document class which should represent an entire menu.
 
 This setting is used by the admin class.
 
-node_document
-"""""""""""""
+node_document_class
+"""""""""""""""""""
 
 **type**: ``string`` **default**:
 ``Symfony\Cmf\Bundle\MenuBundle\Doctrine\Phpcr\MenuNode``
@@ -175,7 +196,7 @@ The ``voters`` section enables you to enable and configure *pre-defined* :doc:`v
     .. code-block:: yaml
 
         cmf_menu:
-            # ... 
+            # ...
             voters:
                 content_identity:
                     content_key:          ~