Merge pull request #39 from gordalina/1.0.x

Added ability to extract inline documentation from docblock

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();
+
+        // 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);
+    }
 }

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,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";
 

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