From e862905708efa369af6f4fdbf3d31e8c99966e67 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien.potencier@gmail.com>
Date: Fri, 13 Jul 2012 08:31:08 +0200
Subject: [PATCH] clarified usage of the string and array loaders

---
 doc/api.rst                |   24 +++++++++++++++++++-----
 lib/Twig/Loader/String.php |    4 ++++
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index 8786c35..c2acba3 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -139,16 +139,30 @@ Here is a list of the built-in loaders Twig provides:
   ``$templateDir1`` and if they do not exist, it will fallback to look for
   them in the ``$templateDir2``.
 
-* ``Twig_Loader_String``: Loads templates from a string. It's a dummy loader
-  as you pass it the source code directly::
+* ``Twig_Loader_String``: Loads templates from strings. It's a dummy loader as
+  the template reference is the template source code::
 
         $loader = new Twig_Loader_String();
+        $twig = new Twig_Environment($loader);
+
+        echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));
+
+  This loader should only be used for unit testing as it has severe
+  limitations: several tags, like ``extends`` or ``include`` do not make sense
+  to use as the reference to the template is the template source code itself.
 
 * ``Twig_Loader_Array``: Loads a template from a PHP array. It's passed an
-  array of strings bound to template names. This loader is useful for unit
-  testing::
+  array of strings bound to template names::
+
+        $loader = new Twig_Loader_Array(array(
+            'index.html' => 'Hello {{ name }}!',
+        ));
+        $twig = new Twig_Environment($loader);
+
+        echo $twig->render('index.html', array('name' => 'Fabien'));
 
-        $loader = new Twig_Loader_Array($templates);
+  This loader is very useful for unit testing. It can also be used for small
+  projects where storing all templates in a single PHP file might make sense.
 
 .. tip::
 
diff --git a/lib/Twig/Loader/String.php b/lib/Twig/Loader/String.php
index bc792b1..a103bce 100644
--- a/lib/Twig/Loader/String.php
+++ b/lib/Twig/Loader/String.php
@@ -12,6 +12,10 @@
 /**
  * Loads a template from a string.
  *
+ * This loader should only be used for unit testing as it has many limitations
+ * (for instance, the include or extends tag does not make any sense for a string
+ * loader).
+ *
  * When using this loader with a cache mechanism, you should know that a new cache
  * key is generated each time a template content "changes" (the cache key being the
  * source code of the template). If you don't want to see your cache grows out of
-- 
1.7.2.5