From 2b02733ee9091795e5abbb7eb0c5897ac2cc2a8a Mon Sep 17 00:00:00 2001
From: Samuel Gordalina <samuel.gordalina@gmail.com>
Date: Fri, 13 Jul 2012 13:32:53 +0100
Subject: [PATCH 1/7] Added ability to extract inline documentation from
 docblock

---
 Annotation/ApiDoc.php            | 21 +++++++++++++++++++++
 Extractor/ApiDocExtractor.php    | 17 +++++++++++++++++
 Formatter/AbstractFormatter.php  |  4 ++++
 Formatter/MarkdownFormatter.php  |  8 ++++++++
 Resources/views/method.html.twig |  5 +++++
 5 files changed, 55 insertions(+)

diff --git a/Annotation/ApiDoc.php b/Annotation/ApiDoc.php
index 1d69036..9f015d3 100644
--- a/Annotation/ApiDoc.php
+++ b/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
      */
diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php
index 42ef1ef..ae5775e 100644
--- a/Extractor/ApiDocExtractor.php
+++ b/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();
+
+        // let's clean the doc block
+        $comment = str_replace('/**', '', $comment);
+        $comment = str_replace('*/', '', $comment);
+        $comment = preg_replace('/^\s*\* ?/m', '', $comment);
+
+        // Remove everything (and including) first annotation
+        $comment = preg_replace('/\n?\s*@[^\s]+.+/ms', '', $comment);
+
+        return trim($comment);
+    }
 }
diff --git a/Formatter/AbstractFormatter.php b/Formatter/AbstractFormatter.php
index bb05506..7b6abf6 100644
--- a/Formatter/AbstractFormatter.php
+++ b/Formatter/AbstractFormatter.php
@@ -138,6 +138,10 @@ abstract class AbstractFormatter implements FormatterInterface
             $data['description'] = $description;
         }
 
+        if ($documentation = $apiDoc->getDocumentation()) {
+            $data['documentation'] = $documentation;
+        }
+
         return $data;
     }
 }
diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php
index 3cb42da..a51da88 100644
--- a/Formatter/MarkdownFormatter.php
+++ b/Formatter/MarkdownFormatter.php
@@ -26,6 +26,14 @@ class MarkdownFormatter extends AbstractFormatter
 
         $markdown .= "\n\n";
 
+        if (isset($data['documentation']) && !empty($data['documentation'])) {
+            $markdown .= "#### Documentation ####\n\n";
+
+            foreach (explode("\n", $data['documentation']) as $line) {
+                $markdown .= "\t" . $line . "\n";
+            }
+        }
+
         if (isset($data['requirements']) && !empty($data['requirements'])) {
             $markdown .= "#### Requirements ####\n\n";
 
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index 69fd08a..a2a23e3 100644
--- a/Resources/views/method.html.twig
+++ b/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>
+            <pre>{{ data.documentation }}</pre>
+        {% endif %}
+
         {% if data.requirements is defined  and data.requirements is not empty %}
             <h4>Requirements</h4>
             <table class="fullwidth">

From 07e6a19dd40b986c64bc8b1f9477d79c30a0046b Mon Sep 17 00:00:00 2001
From: Samuel Gordalina <samuel.gordalina@gmail.com>
Date: Fri, 13 Jul 2012 14:07:40 +0100
Subject: [PATCH 2/7] Updated code to pass the tests

---
 Extractor/ApiDocExtractor.php             | 2 +-
 Formatter/MarkdownFormatter.php           | 4 +++-
 Tests/Formatter/MarkdownFormatterTest.php | 5 +++++
 Tests/Formatter/SimpleFormatterTest.php   | 1 +
 4 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php
index ae5775e..be3b82b 100644
--- a/Extractor/ApiDocExtractor.php
+++ b/Extractor/ApiDocExtractor.php
@@ -233,7 +233,7 @@ class ApiDocExtractor
         $comment = preg_replace('/^\s*\* ?/m', '', $comment);
 
         // Remove everything (and including) first annotation
-        $comment = preg_replace('/\n?\s*@[^\s]+.+/ms', '', $comment);
+        $comment = preg_replace('/@[\w0-9]+\(.*/msi', '', $comment);
 
         return trim($comment);
     }
diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php
index a51da88..5358a00 100644
--- a/Formatter/MarkdownFormatter.php
+++ b/Formatter/MarkdownFormatter.php
@@ -30,8 +30,10 @@ class MarkdownFormatter extends AbstractFormatter
             $markdown .= "#### Documentation ####\n\n";
 
             foreach (explode("\n", $data['documentation']) as $line) {
-                $markdown .= "\t" . $line . "\n";
+                $markdown .= "    " . $line . "\n";
             }
+
+            $markdown .= "\n";
         }
 
         if (isset($data['requirements']) && !empty($data['requirements'])) {
diff --git a/Tests/Formatter/MarkdownFormatterTest.php b/Tests/Formatter/MarkdownFormatterTest.php
index a2ae4f3..2e18a5a 100644
--- a/Tests/Formatter/MarkdownFormatterTest.php
+++ b/Tests/Formatter/MarkdownFormatterTest.php
@@ -126,6 +126,11 @@ _Action without HTTP verb_
 
 _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.
+    And, it supports multilines until the first '@' char.
+
 #### Requirements ####
 
 **id**
diff --git a/Tests/Formatter/SimpleFormatterTest.php b/Tests/Formatter/SimpleFormatterTest.php
index 73d4ffa..b472096 100644
--- a/Tests/Formatter/SimpleFormatterTest.php
+++ b/Tests/Formatter/SimpleFormatterTest.php
@@ -168,6 +168,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."
                 ),
                 3 =>
                 array(

From dccebe0439b86038541c0debc6ca238af60982da Mon Sep 17 00:00:00 2001
From: Samuel Gordalina <samuel.gordalina@gmail.com>
Date: Fri, 13 Jul 2012 14:07:56 +0100
Subject: [PATCH 3/7] Add documentation in README

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index c92d0ad..e28453e 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,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",

From a0a9170d1cc7a9d4df449a515723b97c8e863d08 Mon Sep 17 00:00:00 2001
From: William DURAND <william.durand1@gmail.com>
Date: Fri, 13 Jul 2012 14:54:38 +0200
Subject: [PATCH 4/7] Add knplabs/knp-markdown-bundle

---
 composer.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/composer.json b/composer.json
index d691e7a..8f0524c 100644
--- a/composer.json
+++ b/composer.json
@@ -15,7 +15,8 @@
         }
     ],
     "require": {
-        "symfony/symfony": "2.0.*"
+        "symfony/symfony": "2.0.*",
+        "knplabs/knp-markdown-bundle": "dev-master"
     },
     "autoload": {
         "psr-0": { "Nelmio\\ApiDocBundle": "" }

From 3ec87522b2dd3d44efdd5ed20a61df7a145ba6df Mon Sep 17 00:00:00 2001
From: William DURAND <william.durand1@gmail.com>
Date: Fri, 13 Jul 2012 15:01:09 +0200
Subject: [PATCH 5/7] Add markdown transformation in HTML output, fix Markdown
 formatter

---
 Formatter/MarkdownFormatter.php  | 9 ++-------
 Resources/views/method.html.twig | 2 +-
 2 files changed, 3 insertions(+), 8 deletions(-)

diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php
index 5358a00..de9ec24 100644
--- a/Formatter/MarkdownFormatter.php
+++ b/Formatter/MarkdownFormatter.php
@@ -27,13 +27,8 @@ class MarkdownFormatter extends AbstractFormatter
         $markdown .= "\n\n";
 
         if (isset($data['documentation']) && !empty($data['documentation'])) {
-            $markdown .= "#### Documentation ####\n\n";
-
-            foreach (explode("\n", $data['documentation']) as $line) {
-                $markdown .= "    " . $line . "\n";
-            }
-
-            $markdown .= "\n";
+            $markdown .= $data['documentation'];
+            $markdown .= "\n\n";
         }
 
         if (isset($data['requirements']) && !empty($data['requirements'])) {
diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig
index a2a23e3..b09f2d8 100644
--- a/Resources/views/method.html.twig
+++ b/Resources/views/method.html.twig
@@ -25,7 +25,7 @@
         <div class="pane content selected">
         {% if data.documentation is defined and data.documentation is not empty %}
             <h4>Documentation</h4>
-            <pre>{{ data.documentation }}</pre>
+            <p>{{ data.documentation|markdown }}</p>
         {% endif %}
 
         {% if data.requirements is defined  and data.requirements is not empty %}

From 4b1990b68812ac796caf5b3b5ebda561e021d754 Mon Sep 17 00:00:00 2001
From: William DURAND <william.durand1@gmail.com>
Date: Fri, 13 Jul 2012 15:13:38 +0200
Subject: [PATCH 6/7] Fix stuff

---
 Tests/Fixtures/app/AppKernel.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Tests/Fixtures/app/AppKernel.php b/Tests/Fixtures/app/AppKernel.php
index b8c28b7..1673326 100644
--- a/Tests/Fixtures/app/AppKernel.php
+++ b/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(),
         );
     }
 

From fce0f5d5a6f173905cfa99c2438fefa57048b6f4 Mon Sep 17 00:00:00 2001
From: William DURAND <william.durand1@gmail.com>
Date: Fri, 13 Jul 2012 15:26:36 +0200
Subject: [PATCH 7/7] Fix extractor, markdown formatter, and tests

---
 Extractor/ApiDocExtractor.php             | 6 +++---
 Formatter/MarkdownFormatter.php           | 6 ++++--
 Tests/Formatter/MarkdownFormatterTest.php | 5 -----
 3 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php
index be3b82b..cddfe40 100644
--- a/Extractor/ApiDocExtractor.php
+++ b/Extractor/ApiDocExtractor.php
@@ -227,14 +227,14 @@ class ApiDocExtractor
     {
         $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);
 
-        // Remove everything (and including) first annotation
-        $comment = preg_replace('/@[\w0-9]+\(.*/msi', '', $comment);
-
         return trim($comment);
     }
 }
diff --git a/Formatter/MarkdownFormatter.php b/Formatter/MarkdownFormatter.php
index de9ec24..cc4270e 100644
--- a/Formatter/MarkdownFormatter.php
+++ b/Formatter/MarkdownFormatter.php
@@ -27,8 +27,10 @@ class MarkdownFormatter extends AbstractFormatter
         $markdown .= "\n\n";
 
         if (isset($data['documentation']) && !empty($data['documentation'])) {
-            $markdown .= $data['documentation'];
-            $markdown .= "\n\n";
+            if (isset($data['description']) && 0 === strcmp($data['description'], $data['documentation'])) {
+                $markdown .= $data['documentation'];
+                $markdown .= "\n\n";
+            }
         }
 
         if (isset($data['requirements']) && !empty($data['requirements'])) {
diff --git a/Tests/Formatter/MarkdownFormatterTest.php b/Tests/Formatter/MarkdownFormatterTest.php
index 2e18a5a..a2ae4f3 100644
--- a/Tests/Formatter/MarkdownFormatterTest.php
+++ b/Tests/Formatter/MarkdownFormatterTest.php
@@ -126,11 +126,6 @@ _Action without HTTP verb_
 
 _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.
-    And, it supports multilines until the first '@' char.
-
 #### Requirements ####
 
 **id**