added a note about the usage of Twig_Template methods

diff --git a/lib/Twig/Template.php b/lib/Twig/Template.php
index c21179f..cd1edcd 100644 (file)
--- a/lib/Twig/Template.php
+++ b/lib/Twig/Template.php
@@ -57,6 +57,9 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Returns the parent template.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @return Twig_TemplateInterface|false The parent template or false if there is no parent
      */
     public function getParent(array $context)
@@ -80,6 +83,9 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Displays a parent block.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @param string $name    The block name to display from the parent
      * @param array  $context The context
      * @param array  $blocks  The current set of blocks
@@ -98,6 +104,9 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Displays a block.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @param string $name    The block name to display
      * @param array  $context The context
      * @param array  $blocks  The current set of blocks
@@ -118,6 +127,9 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Renders a parent block.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @param string $name    The block name to render from the parent
      * @param array  $context The context
      * @param array  $blocks  The current set of blocks
@@ -135,6 +147,9 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Renders a block.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @param string $name    The block name to render
      * @param array  $context The context
      * @param array  $blocks  The current set of blocks
@@ -152,6 +167,16 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Returns whether a block exists or not.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
+     * This method does only return blocks defined in the current template
+     * or defined in "used" traits.
+     *
+     * It does not return blocks from parent templates as the parent
+     * template name can be dynamic, which is only known based on the
+     * current context.
+     *
      * @param string $name The block name
      *
      * @return Boolean true if the block exists, false otherwise
@@ -164,7 +189,12 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Returns all block names.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @return array An array of block names
+     *
+     * @see hasBlock
      */
     public function getBlockNames()
     {
@@ -174,7 +204,12 @@ abstract class Twig_Template implements Twig_TemplateInterface
     /**
      * Returns all blocks.
      *
+     * This method is for internal use only and should never be called
+     * directly.
+     *
      * @return array An array of blocks
+     *
+     * @see hasBlock
      */
     public function getBlocks()
     {