[FrameworkBundle][Form] Add some phpDoc for the FormHelper class

src/Symfony/Bundle/FrameworkBundle/Templating/Helper/FormHelper.php

@@ -70,11 +70,40 @@ class FormHelper extends Helper
         return $html;
     }
 
+    /**
+     * Renders the HTML enctype in the form tag, if necessary.
+     *
+     * Example usage in Twig templates:
+     *
+     *     <form action="..." method="post" <?php echo $view['form']->enctype() ?>>
+     *
+     * @param FormView $view  The view for which to render the encoding type
+     *
+     * @return string The html markup
+     */
     public function enctype(FormView $view)
     {
         return $this->renderSection($view, 'enctype');
     }
 
+    /**
+     * Renders the HTML for a given view.
+     *
+     * Example usage in Twig:
+     *
+     *     <?php view['form']->widget() ?>
+     *
+     * You can pass options during the call:
+     *
+     *     <?php view['form']->widget(array('attr' => array('class' => 'foo'))) ?>
+     *
+     *     <?php view['form']->widget(array('separator' => '+++++)) ?>
+     *
+     * @param FormView $view      The view for which to render the widget
+     * @param array    $variables Additional variables passed to the template
+     *
+     * @return string The html markup
+     */
     public function widget(FormView $view, array $variables = array())
     {
         return trim($this->renderSection($view, 'widget', $variables));
@@ -83,16 +112,25 @@ class FormHelper extends Helper
     /**
      * Renders the entire form field "row".
      *
-     * @param FormView $view
-     * @param array    $variables
+     * @param FormView $view      The view for which to render the row
+     * @param array    $variables Additional variables passed to the template
      *
-     * @return string
+     * @return string The html markup
      */
     public function row(FormView $view, array $variables = array())
     {
         return $this->renderSection($view, 'row', $variables);
     }
 
+    /**
+     * Renders the label of the given view.
+     *
+     * @param FormView $view      The view for which to render the label
+     * @param string   $label     The label
+     * @param array    $variables Additional variables passed to the template
+     *
+     * @return string The html markup
+     */
     public function label(FormView $view, $label = null, array $variables = array())
     {
         if ($label !== null) {
@@ -102,16 +140,48 @@ class FormHelper extends Helper
         return $this->renderSection($view, 'label', $variables);
     }
 
+    /**
+     * Renders the errors of the given view.
+     *
+     * @param FormView $view The view to render the errors for
+     *
+     * @return string The html markup
+     */
     public function errors(FormView $view)
     {
         return $this->renderSection($view, 'errors');
     }
 
+    /**
+     * Renders views which have not already been rendered.
+     *
+     * @param FormView $view      The parent view
+     * @param array    $variables An array of variables
+     *
+     * @return string The html markup
+     */
     public function rest(FormView $view, array $variables = array())
     {
         return $this->renderSection($view, 'rest', $variables);
     }
 
+    /**
+     * Renders a template.
+     *
+     * 1. This function first looks for a block named "_<view id>_<section>",
+     * 2. if such a block is not found the function will look for a block named
+     *    "<type name>_<section>",
+     * 3. the type name is recursively replaced by the parent type name until a
+     *    corresponding block is found
+     *
+     * @param FormView  $view       The form view
+     * @param string    $section    The section to render (i.e. 'row', 'widget', 'label', ...)
+     * @param array     $variables  Additional variables
+     *
+     * @return string The html markup
+     *
+     * @throws FormException if no template block exists to render the given section of the view
+     */
     protected function renderSection(FormView $view, $section, array $variables = array())
     {
         $mainTemplate = in_array($section, array('row', 'widget'));
@@ -164,13 +234,20 @@ class FormHelper extends Helper
         return $html;
     }
 
-    protected function lookupTemplate($templateName)
+    /**
+     * Returns the name of the template to use to render the block
+     *
+     * @param string $blockName The name of the block
+     *
+     * @return string|Boolean The template logical name or false when no template is found
+     */
+    protected function lookupTemplate($blockName)
     {
-        if (isset(self::$cache[$templateName])) {
-            return self::$cache[$templateName];
+        if (isset(self::$cache[$blockName])) {
+            return self::$cache[$blockName];
         }
 
-        $template = $templateName.'.html.php';
+        $template = $blockName.'.html.php';
 /*
         if ($this->templateDir) {
             $template = $this->templateDir.':'.$template;
@@ -181,7 +258,7 @@ class FormHelper extends Helper
             $template = false;
         }
 
-        self::$cache[$templateName] = $template;
+        self::$cache[$blockName] = $template;
 
         return $template;
     }