Added a way to comment each field of a Form Type

Form/Extension/DescriptionFieldTypeExtension.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\Form\Extension;
+
+use Symfony\Component\Form\AbstractTypeExtension;
+use Symfony\Component\Form\FormBuilder;
+use Symfony\Component\Form\FormInterface;
+use Symfony\Component\Form\FormView;
+
+class DescriptionFieldTypeExtension extends AbstractTypeExtension
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function buildForm(FormBuilder $builder, array $options)
+    {
+        $builder->setAttribute('description', $options['description']);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function buildView(FormView $view, FormInterface $form)
+    {
+        $view->set('description', $form->getAttribute('description'));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getDefaultOptions()
+    {
+        return array(
+            'description' => '',
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getExtendedType()
+    {
+        return 'field';
+    }
+}

Formatter/MarkdownFormatter.php

@@ -56,7 +56,12 @@ class MarkdownFormatter extends AbstractFormatter
             foreach ($data['parameters'] as $name => $parameter) {
                 $markdown .= sprintf("%s:\n\n", $name);
                 $markdown .= sprintf("  * type: %s\n", $parameter['dataType']);
-                $markdown .= sprintf("  * is_required: %s\n", $parameter['required'] ? 'true' : 'false');
+                $markdown .= sprintf("  * required: %s\n", $parameter['required'] ? 'true' : 'false');
+
+                if (isset($parameter['description']) && !empty($parameter['description'])) {
+                    $markdown .= sprintf("  * description: %s\n", $parameter['description']);
+                }
+
                 $markdown .= "\n";
             }
         }

Parser/FormTypeParser.php

@@ -45,6 +45,7 @@ class FormTypeParser
      * Returns an array of data where each data is an array with the following keys:
      *  - dataType
      *  - required
+     *  - description
      *
      * @param AbstractType $type
      * @return array
@@ -65,8 +66,9 @@ class FormTypeParser
             }
 
             $parameters[$name] = array(
-                'dataType'  => $bestType,
-                'required'  => $b->getRequired()
+                'dataType'      => $bestType,
+                'required'      => $b->getRequired(),
+                'description'   => $b->getAttribute('description'),
             );
         }
 

README.md

@@ -96,6 +96,27 @@ parameters, and you can document them as you want, but keep in mind to be consis
 If you set a `formType`, then the bundle automatically extracts parameters based on the given type,
 and determines for each parameter its data type, and if it's required or not.
 
+You can add an extra option named `description` on each field:
+
+``` php
+<?php
+
+class YourType extends AbstractType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function buildForm(FormBuilder $builder, array $options)
+    {
+        $builder->add('note', null, array(
+            'description' => 'this is a note',
+        ));
+
+        // ...
+    }
+}
+```
+
 The bundle will also get information from the routing definition (`requirements`, `pattern`, etc), so to get the
 best out of it you should define strict _method requirements etc.
 

Resources/config/services.xml

@@ -5,6 +5,7 @@
 
     <parameters>
         <parameter key="nelmio_api_doc.extractor.api_doc_extractor.class">Nelmio\ApiDocBundle\Extractor\ApiDocExtractor</parameter>
+        <parameter key="nelmio_api_doc.form.extension.description_field_type_extension.class">Nelmio\ApiDocBundle\Form\Extension\DescriptionFieldTypeExtension</parameter>
     </parameters>
 
     <services>
@@ -12,6 +13,9 @@
             <argument type="service" id="router" />
             <argument type="service" id="annotation_reader" />
         </service>
+        <service id="nelmio_api_doc.form.extension.description_field_type_extension" class="%nelmio_api_doc.form.extension.description_field_type_extension.class%">
+            <tag name="form.type_extension" alias="field" />
+        </service>
     </services>
 
 </container>

Resources/views/method.html.twig

@@ -69,6 +69,7 @@
                     <th>Parameter</th>
                     <th>Type</th>
                     <th>Required?</th>
+                    <th>Description</th>
                 </tr>
             </thead>
             <tbody>
@@ -77,6 +78,7 @@
                         <td>{{ name }}</td>
                         <td>{{ infos.dataType }}</td>
                         <td>{{ infos.required ? 'true' : 'false' }}</td>
+                        <td>{{ infos.description }}</td>
                     </tr>
                 {% endfor %}
             </tbody>