init without trunk

vendor/sensio/framework-extra-bundle/Resources/doc/annotations/view.rst

@@ -0,0 +1,100 @@
+@Template
+=========
+
+Usage
+-----
+
+The ``@Template`` annotation associates a controller with a template name::
+
+    use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
+
+    /**
+     * @Template("SensioBlogBundle:Post:show.html.twig")
+     */
+    public function showAction($id)
+    {
+        // get the Post
+        $post = ...;
+
+        return array('post' => $post);
+    }
+
+When using the ``@Template`` annotation, the controller should return an
+array of parameters to pass to the view instead of a ``Response`` object.
+
+.. note::
+
+    If you want to stream your template, you can make it with the following configuration::
+
+        /**
+         * @Template(isStreamable=true)
+         */
+        public function showAction($id)
+        {
+            // ...
+        }
+
+
+.. tip::
+   If the action returns a ``Response`` object, the ``@Template`` 
+   annotation is simply ignored.
+
+If the template is named after the controller and action names, which is the
+case for the above example, you can even omit the annotation value::
+
+    /**
+     * @Template
+     */
+    public function showAction($id)
+    {
+        // get the Post
+        $post = ...;
+
+        return array('post' => $post);
+    }
+
+.. note::
+
+    If you are using PHP as a templating system, you need to make it
+    explicit::
+
+        /**
+         * @Template(engine="php")
+         */
+        public function showAction($id)
+        {
+            // ...
+        }
+
+And if the only parameters to pass to the template are method arguments, you
+can use the ``vars`` attribute instead of returning an array. This is very
+useful in combination with the ``@ParamConverter`` :doc:`annotation
+<converters>`::
+
+    /**
+     * @ParamConverter("post", class="SensioBlogBundle:Post")
+     * @Template("SensioBlogBundle:Post:show.html.twig", vars={"post"})
+     */
+    public function showAction(Post $post)
+    {
+    }
+
+which, thanks to conventions, is equivalent to the following configuration::
+
+    /**
+     * @Template(vars={"post"})
+     */
+    public function showAction(Post $post)
+    {
+    }
+
+You can make it even more concise as all method arguments are automatically
+passed to the template if the method returns ``null`` and no ``vars``
+attribute is defined::
+
+    /**
+     * @Template
+     */
+    public function showAction(Post $post)
+    {
+    }