[ApiBundle] Added more comments

Annotation/ApiDoc.php

@@ -51,21 +51,33 @@ class ApiDoc
         $this->isResource = isset($data['resource']);
     }
 
+    /**
+     * @return array|null
+     */
     public function getFilters()
     {
         return $this->filters;
     }
 
+    /**
+     * @return string|null
+     */
     public function getFormType()
     {
         return $this->formType;
     }
 
+    /**
+     * @return string|null
+     */
     public function getDescription()
     {
         return $this->description;
     }
 
+    /**
+     * @return Boolean
+     */
     public function isResource()
     {
         return $this->isResource;

Command/DumpCommand.php

@@ -12,7 +12,7 @@ class DumpCommand extends ContainerAwareCommand
     /**
      * @var array
      */
-    protected $availableFormats = array('markdown', 'json');
+    protected $availableFormats = array('markdown', 'json', 'html');
 
     protected function configure()
     {
@@ -35,16 +35,20 @@ class DumpCommand extends ContainerAwareCommand
         if (!$input->hasOption('format') || in_array($format, array('json'))) {
             $formatter = $this->getContainer()->get('nelmio.api.formatter.simple_formatter');
         } else {
+            if (!in_array($format, $this->availableFormats)) {
+                throw new \RuntimeException(sprintf('Format "%s" not supported.', $format));
+            }
+
             $formatter = $this->getContainer()->get(sprintf('nelmio.api.formatter.%s_formatter', $format));
         }
 
         $extractedDoc = $this->getContainer()->get('nelmio.api.extractor.api_doc_extractor')->all();
-        $result = $formatter->format($extractedDoc);
+        $formattedDoc = $formatter->format($extractedDoc);
 
         if ('json' === $format) {
-            $output->writeln(json_encode($result));
+            $output->writeln(json_encode($formattedDoc));
         } else {
-            $output->writeln($result);
+            $output->writeln($formattedDoc);
         }
     }
 }

EventListener/RequestListener.php

@@ -11,8 +11,14 @@ use Symfony\Component\HttpKernel\Event\GetResponseEvent;
 
 class RequestListener
 {
+    /**
+     * @var \Nelmio\ApiBundle\Extractor\ApiDocExtractor
+     */
     protected $extractor;
 
+    /**
+     * @var \Nelmio\ApiBundle\Formatter\FormatterInterface
+     */
     protected $formatter;
 
     public function __construct(ApiDocExtractor $extractor, FormatterInterface $formatter)

Extractor/ApiDocExtractor.php

@@ -10,7 +10,7 @@ class ApiDocExtractor
     const ANNOTATION_CLASS = 'Nelmio\\ApiBundle\\Annotation\\ApiDoc';
 
     /**
-     * @var
+     * @var \ymfony\Component\Routing\RouterInterface
      */
     private $router;
 
@@ -25,6 +25,14 @@ class ApiDocExtractor
         $this->reader = $reader;
     }
 
+    /**
+     * Returns an array of data where each data is an array with the following keys:
+     *  - annotation
+     *  - route
+     *  - resource
+     *
+     * @return array
+     */
     public function all()
     {
         $array = array();
@@ -76,6 +84,15 @@ class ApiDocExtractor
         return $array;
     }
 
+    /**
+     * Returns an array containing two values with the following keys:
+     *  - annotation
+     *  - route
+     *
+     * @param string $controller
+     * @param Route $route
+     * @return array|null
+     */
     public function get($controller, $route)
     {
         preg_match('#(.+)::([\w]+)#', $controller, $matches);

Formatter/FormatterInterface.php

@@ -7,7 +7,20 @@ use Symfony\Component\Routing\Route;
 
 interface FormatterInterface
 {
+    /**
+     * Format a collection of documentation data.
+     *
+     * @param array $collection
+     * @return string|array
+     */
     function format(array $collection);
 
+    /**
+     * Format documentation data for one route.
+     *
+     * @param ApiDoc $apiDoc
+     * @param Route $route
+     * return string|array
+     */
     function formatOne(ApiDoc $apiDoc, Route $route);
 }

Parser/FormTypeParser.php

@@ -8,8 +8,14 @@ use Symfony\Component\Form\FormFactoryInterface;
 
 class FormTypeParser
 {
+    /**
+     * @var \Symfony\Component\Form\FormFactoryInterface
+     */
     protected $formFactory;
 
+    /**
+     * @var array
+     */
     protected $mapTypes = array(
         'text'      => 'string',
         'date'      => 'date',
@@ -26,6 +32,14 @@ class FormTypeParser
         $this->formFactory = $formFactory;
     }
 
+    /**
+     * Returns an array of data where each data is an array with the following keys:
+     *  - dataType
+     *  - required
+     *
+     * @param AbstractType $type
+     * @return array
+     */
     public function parse(AbstractType $type)
     {
         $builder = $this->formFactory->createBuilder($type);