Multiblock args

composer.json

@@ -6,6 +6,7 @@
     "license" : "MIT",
     "require" : {
         "php" : ">=5.3.1",
+        "league/html-to-markdown" : "~4.8.2",
         "twig/twig" : "~1.2|2.0"
     },
     "require-dev" : {

src/Parser.php

@@ -2,6 +2,7 @@
 
 namespace PHPDocMD;
 
+use League\HTMLToMarkdown\HtmlConverter;
 use SimpleXMLElement;
 
 /**
@@ -27,12 +28,24 @@ class Parser
      */
     protected $classDefinitions;
 
+    /**
+     * The HTML to Markdown converter.
+     *
+     * @var League\HTMLToMarkdown\HtmlConverter
+     */
+    protected $htmlConverter;
+
     /**
      * @param string $structureXmlFile
      */
     function __construct($structureXmlFile)
     {
         $this->structureXmlFile = $structureXmlFile;
+
+        $this->htmlConverter = new HtmlConverter([
+            'hard_break' => true,
+            'strip_tags' => true,
+        ]);
     }
 
     /**
@@ -153,7 +166,7 @@ protected function parseMethods(SimpleXMLElement $class)
                     }
 
                     if ((string)$tag['description']) {
-                        $nArgument['description'] = (string)$tag['description'];
+                        $nArgument['description'] = $this->escapeHtmlToMarkdownBlocks((string)$tag['description']);
                     }
 
                     if ((string)$tag['variable']) {
@@ -351,4 +364,45 @@ protected function expandProperties($className)
 
         return $newProperties;
     }
+
+    /**
+     * Converts encoded HTML to Markdown and breaks multi Markdown blocks to
+     * string arrays of indented Markdown code.
+     *
+     * The former is required since PHPDocumentor encodes certain attributes to
+     * HTML while generating the XML structure.
+     *
+     * The latter is required to allow the Twig template to render blocks
+     * block-by-block. Currently, this method assumes that such blocks are under
+     * a top-level block: the block indentation it generates is hard-coded to 4
+     * spaces.
+     *
+     * @param string $escapedHtml
+     *        The escaped HTML, as encoded in structure.xml
+     *
+     * @return string|array
+     *         The Markdown code, as a string if it is a single block or an
+     *         array of strings containing indented blocks otherwise.
+     */
+    protected function escapeHtmlToMarkdownBlocks($escapedHtml)
+    {
+        $flags = ENT_QUOTES | ENT_HTML5;
+        $html = htmlspecialchars_decode($escapedHtml, ENT_QUOTES | ENT_HTML5);
+        $md = $this->htmlConverter->convert($html);
+        $blocks = explode("\n\n", $md);
+
+        if (count($blocks) == 1) {
+            return $blocks[0];
+        }
+
+        return array_map(function($block) {
+            $lines = explode("\n", $block);
+
+            $lines = array_map(function($line) {
+                return '    ' . $line;
+            }, $lines);
+
+            return implode("\n", $lines);
+        }, $blocks);
+    }
 }

templates/class.twig

@@ -42,7 +42,7 @@ Constants
 
     {{ constant.signature|raw }}
 
-{{ property.description|raw }}
+{{ constant.description|raw }}
 
 {% if constant.deprecated %}* **Warning:** this constant is **deprecated**. This means that this constant will likely be removed in a future version.
 {% endif %}
@@ -99,7 +99,13 @@ Methods
 {% if method.arguments %}
 #### Arguments
 {% for argument in method.arguments %}
-* {{ argument.name }} **{% if argument.type %}{{ argument.type|classLink }}{% else %}mixed{% endif %}**{% if argument.description %} - {{ argument.description }}{% endif %}
+* {{ argument.name }} **{% if argument.type %}{{ argument.type|classLink }}{% else %}mixed{% endif %}**{% if argument.description %}{% if argument.description is iterable %}
+
+
+{% for block_ in argument.description %}
+{{ block_|raw }}
+
+{% endfor %}{% else %} - {{ argument.description|raw }}{% endif %}{% endif %}
 
 {% endfor %}