Merge branch '1.0.x'

Annotation/ApiDoc.php

@@ -31,6 +31,11 @@ class ApiDoc
      */
     private $description = null;
 
+    /**
+     * @var string
+     */
+    private $documentation = null;
+
     /**
      * @var Boolean
      */
@@ -92,6 +97,22 @@ class ApiDoc
         $this->description = $description;
     }
 
+    /**
+     * @return string|null
+     */
+    public function getDocumentation()
+    {
+        return $this->documentation;
+    }
+
+    /**
+     * @param string $documentation
+     */
+    public function setDocumentation($documentation)
+    {
+        $this->documentation = $documentation;
+    }
+
     /**
      * @return Boolean
      */

Extractor/ApiDocExtractor.php

@@ -193,6 +193,8 @@ class ApiDocExtractor
             }
         }
 
+        $annotation->setDocumentation($this->getDocCommentText($method));
+
         $paramDocs = array();
         foreach (explode("\n", $docblock) as $line) {
             if (preg_match('{^@param (.+)}', trim($line), $matches)) {
@@ -220,4 +222,19 @@ class ApiDocExtractor
 
         return $comment;
     }
+
+    protected function getDocCommentText(\Reflector $reflected)
+    {
+        $comment = $reflected->getDocComment();
+
+        // Remove PHPDoc
+        $comment = preg_replace('/^\s+\* @[\w0-9]+.*/msi', '', $comment);
+
+        // let's clean the doc block
+        $comment = str_replace('/**', '', $comment);
+        $comment = str_replace('*/', '', $comment);
+        $comment = preg_replace('/^\s*\* ?/m', '', $comment);
+
+        return trim($comment);
+    }
 }

Formatter/AbstractFormatter.php

@@ -138,6 +138,10 @@ abstract class AbstractFormatter implements FormatterInterface
             $data['description'] = $description;
         }
 
+        if ($documentation = $apiDoc->getDocumentation()) {
+            $data['documentation'] = $documentation;
+        }
+
         return $data;
     }
 }

Formatter/MarkdownFormatter.php

@@ -26,6 +26,13 @@ class MarkdownFormatter extends AbstractFormatter
 
         $markdown .= "\n\n";
 
+        if (isset($data['documentation']) && !empty($data['documentation'])) {
+            if (isset($data['description']) && 0 === strcmp($data['description'], $data['documentation'])) {
+                $markdown .= $data['documentation'];
+                $markdown .= "\n\n";
+            }
+        }
+
         if (isset($data['requirements']) && !empty($data['requirements'])) {
             $markdown .= "#### Requirements ####\n\n";
 

README.md

@@ -62,6 +62,10 @@ use Nelmio\ApiDocBundle\Annotation\ApiDoc;
 class YourController extends Controller
 {
     /**
+     * This the documentation description of your method, it will appear
+     * on a specific pane. It will read all the text until the first
+     * annotation.
+     *
      * @ApiDoc(
      *  resource=true,
      *  description="This is a description of your API method",

Resources/views/method.html.twig

@@ -23,6 +23,11 @@
 
       <div class="panes">
         <div class="pane content selected">
+        {% if data.documentation is defined and data.documentation is not empty %}
+            <h4>Documentation</h4>
+            <p>{{ data.documentation|markdown }}</p>
+        {% endif %}
+
         {% if data.requirements is defined  and data.requirements is not empty %}
             <h4>Requirements</h4>
             <table class="fullwidth">

Tests/Fixtures/app/AppKernel.php

@@ -50,6 +50,7 @@ class AppKernel extends Kernel
             new \Symfony\Bundle\TwigBundle\TwigBundle(),
             new \Nelmio\ApiDocBundle\NelmioApiDocBundle(),
             new \Nelmio\ApiDocBundle\Tests\Fixtures\NelmioApiDocTestBundle(),
+            new \Knp\Bundle\MarkdownBundle\KnpMarkdownBundle(),
         );
     }
 

Tests/Formatter/SimpleFormatterTest.php

@@ -186,6 +186,7 @@ class SimpleFormatterTest extends WebTestCase
                         'page' => array('type' => 'int', 'description' => '', 'value' => ''),
                     ),
                     'description' => 'This method is useful to test if the getDocComment works. And, it supports multilines until the first \'@\' char.',
+                    'documentation' => "This method is useful to test if the getDocComment works.\nAnd, it supports multilines until the first '@' char."
                 ),
                 4 =>
                 array(

composer.json

@@ -17,7 +17,8 @@
     "require": {
         "symfony/framework-bundle": "2.1.*",
         "symfony/twig-bundle": "2.1.*",
-        "symfony/form": "2.1.*"
+        "symfony/form": "2.1.*",
+        "knplabs/knp-markdown-bundle": "dev-master"
     },
     "require-dev": {
         "symfony/css-selector": "2.1.*",