Outsourced the parsing of the classic phpDoc into a extra handler.

This makes it possible to overwrite route-requirements/description through a own handler.
Otherwise it's impossible e.g. to overwrite a `@param string $page` annotation via a own handler.

Extractor/ApiDocExtractor.php

@@ -253,20 +253,6 @@ class ApiDocExtractor
         // route
         $annotation->setRoute($route);
 
-        // description
-        if (null === $annotation->getDescription()) {
-            $comments = explode("\n", $annotation->getDocumentation());
-            // just set the first line
-            $comment = trim($comments[0]);
-            $comment = preg_replace("#\n+#", ' ', $comment);
-            $comment = preg_replace('#\s+#', ' ', $comment);
-            $comment = preg_replace('#[_`*]+#', '', $comment);
-
-            if ('@' !== substr($comment, 0, 1)) {
-                $annotation->setDescription($comment);
-            }
-        }
-
         // input (populates 'parameters' for the formatters)
         if (null !== $input = $annotation->getInput()) {
             $parameters = array();
@@ -317,59 +303,6 @@ class ApiDocExtractor
             $annotation->setResponse($response);
         }
 
-        // requirements
-        $requirements = array();
-        foreach ($route->getRequirements() as $name => $value) {
-            if ('_method' !== $name) {
-                $requirements[$name] = array(
-                    'requirement'   => $value,
-                    'dataType'      => '',
-                    'description'   => '',
-                );
-            }
-            if ('_scheme' == $name) {
-                $https = ('https' == $value);
-                $annotation->setHttps($https);
-            }
-        }
-
-        $paramDocs = array();
-        foreach (explode("\n", $this->commentExtractor->getDocComment($method)) as $line) {
-            if (preg_match('{^@param (.+)}', trim($line), $matches)) {
-                $paramDocs[] = $matches[1];
-            }
-            if (preg_match('{^@deprecated\b(.*)}', trim($line), $matches)) {
-                $annotation->setDeprecated(true);
-            }
-            if (preg_match('{^@link\b(.*)}', trim($line), $matches)) {
-                $annotation->setLink($matches[1]);
-            }
-        }
-
-        $regexp = '{(\w*) *\$%s\b *(.*)}i';
-        foreach ($route->compile()->getVariables() as $var) {
-            $found = false;
-            foreach ($paramDocs as $paramDoc) {
-                if (preg_match(sprintf($regexp, preg_quote($var)), $paramDoc, $matches)) {
-                    $requirements[$var]['dataType']    = isset($matches[1]) ? $matches[1] : '';
-                    $requirements[$var]['description'] = $matches[2];
-
-                    if (!isset($requirements[$var]['requirement'])) {
-                        $requirements[$var]['requirement'] = '';
-                    }
-
-                    $found = true;
-                    break;
-                }
-            }
-
-            if (!isset($requirements[$var]) && false === $found) {
-                $requirements[$var] = array('requirement' => '', 'dataType' => '', 'description' => '');
-            }
-        }
-
-        $annotation->setRequirements($requirements);
-
         return $annotation;
     }
 

Extractor/Handler/PhpDocHandler.php

@@ -0,0 +1,100 @@
+<?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\Extractor\Handler;
+
+use Nelmio\ApiDocBundle\Extractor\HandlerInterface;
+use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Symfony\Component\Routing\Route;
+use Nelmio\ApiDocBundle\Util\DocCommentExtractor;
+
+class PhpDocHandler implements HandlerInterface
+{
+    /**
+     * @var DocCommentExtractor
+     */
+    protected $commentExtractor;
+
+    public function __construct(DocCommentExtractor $commentExtractor)
+    {
+        $this->commentExtractor = $commentExtractor;
+    }
+
+    public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method)
+    {
+        // description
+        if (null === $annotation->getDescription()) {
+            $comments = explode("\n", $annotation->getDocumentation());
+            // just set the first line
+            $comment = trim($comments[0]);
+            $comment = preg_replace("#\n+#", ' ', $comment);
+            $comment = preg_replace('#\s+#', ' ', $comment);
+            $comment = preg_replace('#[_`*]+#', '', $comment);
+
+            if ('@' !== substr($comment, 0, 1)) {
+                $annotation->setDescription($comment);
+            }
+        }
+
+        // requirements
+        $requirements = $annotation->getRequirements();
+        foreach ($route->getRequirements() as $name => $value) {
+            if (!isset($requirements[$name]) && '_method' !== $name) {
+                $requirements[$name] = array(
+                    'requirement' => $value,
+                    'dataType' => '',
+                    'description' => '',
+                );
+            }
+            if ('_scheme' == $name) {
+                $https = ('https' == $value);
+                $annotation->setHttps($https);
+            }
+        }
+
+        $paramDocs = array();
+        foreach (explode("\n", $this->commentExtractor->getDocComment($method)) as $line) {
+            if (preg_match('{^@param (.+)}', trim($line), $matches)) {
+                $paramDocs[] = $matches[1];
+            }
+            if (preg_match('{^@deprecated\b(.*)}', trim($line), $matches)) {
+                $annotation->setDeprecated(true);
+            }
+            if (preg_match('{^@link\b(.*)}', trim($line), $matches)) {
+                $annotation->setLink($matches[1]);
+            }
+        }
+
+        $regexp = '{(\w*) *\$%s\b *(.*)}i';
+        foreach ($route->compile()->getVariables() as $var) {
+            $found = false;
+            foreach ($paramDocs as $paramDoc) {
+                if (preg_match(sprintf($regexp, preg_quote($var)), $paramDoc, $matches)) {
+                    $requirements[$var]['dataType'] = isset($matches[1]) ? $matches[1] : '';
+                    $requirements[$var]['description'] = $matches[2];
+
+                    if (!isset($requirements[$var]['requirement'])) {
+                        $requirements[$var]['requirement'] = '';
+                    }
+
+                    $found = true;
+                    break;
+                }
+            }
+
+            if (!isset($requirements[$var]) && false === $found) {
+                $requirements[$var] = array('requirement' => '', 'dataType' => '', 'description' => '');
+            }
+        }
+
+        $annotation->setRequirements($requirements);
+    }
+}

Resources/config/services.xml

@@ -12,6 +12,7 @@
         <parameter key="nelmio_api_doc.extractor.handler.fos_rest.class">Nelmio\ApiDocBundle\Extractor\Handler\FosRestHandler</parameter>
         <parameter key="nelmio_api_doc.extractor.handler.jms_security.class">Nelmio\ApiDocBundle\Extractor\Handler\JmsSecurityExtraHandler</parameter>
         <parameter key="nelmio_api_doc.extractor.handler.sensio_framework_extra.class">Nelmio\ApiDocBundle\Extractor\Handler\SensioFrameworkExtraHandler</parameter>
+        <parameter key="nelmio_api_doc.extractor.handler.phpdoc.class">Nelmio\ApiDocBundle\Extractor\Handler\PhpDocHandler</parameter>
     </parameters>
 
     <services>
@@ -46,6 +47,11 @@
         <service id="nelmio_api_doc.extractor.handler.sensio_framework_extra" class="%nelmio_api_doc.extractor.handler.sensio_framework_extra.class%" public="false">
             <tag name="nelmio_api_doc.extractor.handler"/>
         </service>
+
+        <service id="nelmio_api_doc.extractor.handler.phpdoc" class="%nelmio_api_doc.extractor.handler.phpdoc.class%" public="false">
+            <argument type="service" id="nelmio_api_doc.doc_comment_extractor" />
+            <tag name="nelmio_api_doc.extractor.handler"/>
+        </service>
     </services>
 
 </container>