Fix extractor, markdown formatter, and tests

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);
     }
 }

Formatter/MarkdownFormatter.php

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

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**