Write tests for DescriptionFactory and adjust components for minor bugs that were found

Author: mvriel

src/DocBlock/DescriptionFactory.php

@@ -14,6 +14,23 @@
 
 use phpDocumentor\Reflection\Types\Context;
 
+/**
+ * Creates a new Description object given a body of text.
+ *
+ * Descriptions in phpDocumentor are somewhat complex entities as they can contain one or more tags inside their
+ * body that can be replaced with a readable output. The replacing is done by passing a Formatter object to the
+ * Description object's `render` method.
+ *
+ * In addition to the above does a Description support two types of escape sequences:
+ *
+ * 1. `{@}` to escape the `@` character to prevent it from being interpreted as part of a tag, i.e. `{{@}link}`
+ * 2. `{}` to escape the `}` character, this can be used if you want to use the `}` character in the description
+ *    of an inline tag.
+ *
+ * If a body consists of multiple lines then this factory will also remove any superfluous whitespace at the beginning
+ * of each line while maintaining any indentation that is used. This will prevent formatting parsers from tripping
+ * over unexpected spaces as can be observed with tag descriptions.
+ */
 class DescriptionFactory
 {
     /** @var TagFactory */
@@ -45,11 +62,16 @@ public function create($contents, Context $context = null)
     }
 
     /**
-     * @param $contents
-     * @return array
+     * Strips the contents from superfluous whitespace and splits the description into a series of tokens.
+     *
+     * @param string $contents
+     *
+     * @return string[] A series of tokens of which the description text is composed.
      */
     private function lex($contents)
     {
+        $contents = $this->removeSuperfluousStartingWhitespace($contents);
+
         // performance optimalization; if there is no inline tag, don't bother splitting it up.
         if (strpos($contents, '{@') === false) {
             return [$contents];
@@ -98,7 +120,8 @@ private function parse($tokens, Context $context)
     {
         $count = count($tokens);
         $tagCount = 0;
-        $tags = [];
+        $tags  = [];
+
         for ($i = 1; $i < $count; $i += 2) {
             $tags[] = $this->tagFactory->create($tokens[$i], $context);
             $tokens[$i] = '%' . ++$tagCount . '$s';
@@ -114,4 +137,55 @@ private function parse($tokens, Context $context)
         return [implode('', $tokens), $tags];
     }
 
+    /**
+     * Removes the superfluous from a multi-line description.
+     *
+     * When a description has more than one line then it can happen that the second and subsequent lines have an
+     * additional indentation. This is commonly in use with tags like this:
+     *
+     *     {@}since 1.1.0 This is an example
+     *         description where we have an
+     *         indentation in the second and
+     *         subsequent lines.
+     *
+     * If we do not normalize the indentation then we have superfluous whitespace on the second and subsequent
+     * lines and this may cause rendering issues when, for example, using a Markdown converter.
+     *
+     * @param string $contents
+     *
+     * @return string
+     */
+    private function removeSuperfluousStartingWhitespace($contents)
+    {
+        $lines = explode("\n", $contents);
+
+        // if there is only one line then we don't have lines with superfluous whitespace and
+        // can use the contents as-is
+        if (count($lines) <= 1) {
+            return $contents;
+        }
+
+        // determine how many whitespace characters need to be stripped
+        $startingSpaceCount = 9999999;
+        for ($i = 1; $i < count($lines); $i++) {
+            // lines with a no length do not count as they are not indented at all
+            if (strlen(trim($lines[$i])) === 0) {
+                continue;
+            }
+
+            // determine the number of prefixing spaces by checking the difference in line length before and after
+            // an ltrim
+            $startingSpaceCount = min($startingSpaceCount, strlen($lines[$i]) - strlen(ltrim($lines[$i])));
+        }
+
+        // strip the number of spaces from each line
+        if ($startingSpaceCount > 0) {
+            for ($i = 1; $i < count($lines); $i++) {
+                $lines[$i] = substr($lines[$i], $startingSpaceCount);
+            }
+        }
+
+        return implode("\n", $lines);
+    }
+
 }

src/DocBlock/Serializer.php

@@ -127,7 +127,8 @@ private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLeng
     private function addTagBlock(DocBlock $docblock, $wrapLength, $indent, $comment)
     {
         foreach ($docblock->getTags() as $tag) {
-            $tagText = (string)$tag;
+            $formatter = new DocBlock\Tags\Formatter\PassthroughFormatter();
+            $tagText   = $formatter->format($tag);
             if ($wrapLength !== null) {
                 $tagText = wordwrap($tagText, $wrapLength);
             }

src/DocBlock/Tags/Example.php

@@ -1,11 +1,11 @@
 <?php
 /**
- * phpDocumentor
+ * This file is part of phpDocumentor.
  *
- * PHP Version 5.3
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
  *
- * @author    Vasil Rangelov <[email protected]>
- * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
  * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
@@ -15,25 +15,20 @@
 use phpDocumentor\Reflection\DocBlock\Tag;
 
 /**
- * Reflection class for a @example tag in a Docblock.
- *
- * @author  Vasil Rangelov <[email protected]>
- * @license http://www.opensource.org/licenses/mit-license.php MIT
- * @link    http://phpdoc.org
+ * Reflection class for a {@}example tag in a Docblock.
  */
-class Example extends Source
+final class Example extends BaseTag
 {
     /**
-     * @var string Path to a file to use as an example.
-     *     May also be an absolute URI.
+     * @var string Path to a file to use as an example. May also be an absolute URI.
      */
-    protected $filePath = '';
+    private $filePath = '';
 
     /**
-     * @var bool Whether the file path component represents an URI.
-     *     This determines how the file portion appears at {@link getContent()}.
+     * @var bool Whether the file path component represents an URI. This determines how the file portion
+     *     appears at {@link getContent()}.
      */
-    protected $isURI = false;
+    private $isURI = false;
 
     /**
      * {@inheritdoc}
@@ -57,40 +52,35 @@ public function getContent()
     /**
      * {@inheritdoc}
      */
-    public function setContent($content)
+    public static function create($body)
     {
-        Tag::setContent($content);
-        if (preg_match(
-            '/^
-                # File component
-                (?:
-                    # File path in quotes
-                    \"([^\"]+)\"
-                    |
-                    # File URI
-                    (\S+)
-                )
-                # Remaining content (parsed by SourceTag)
-                (?:\s+(.*))?
-            $/sux',
-            $this->description,
-            $matches
-        )) {
-            if ('' !== $matches[1]) {
-                $this->setFilePath($matches[1]);
-            } else {
-                $this->setFileURI($matches[2]);
-            }
+        // File component: File path in quotes or File URI / Source information
+        if (! preg_match('/^(?:\"([^\"]+)\"|(\S+))(?:\s+(.*))?$/sux', $body, $matches)) {
+            return null;
+        }
 
-            if (isset($matches[3])) {
-                parent::setContent($matches[3]);
-            } else {
-                $this->setDescription('');
+        $filePath = null;
+        $fileUri  = null;
+        if ('' !== $matches[1]) {
+            $filePath = $matches[1];
+        } else {
+            $fileUri = $matches[2];
+        }
+
+        $startingLine = 1;
+        $lineCount    = null;
+        $description  = null;
+
+        // Starting line / Number of lines / Description
+        if (preg_match('/^([1-9]\d*)\s*(?:((?1))\s+)?(.*)$/sux', $matches[3], $matches)) {
+            $startingLine = (int)$matches[1];
+            if (isset($matches[2]) && $matches[2] !== '') {
+                $lineCount = (int)$matches[2];
             }
-            $this->description = $content;
+            $description = $matches[3];
         }
 
-        return $this;
+        return new static($filePath, $fileUri, $startingLine, $lineCount, $description);
     }
 
     /**

src/DocBlock/Tags/Formatter/PassthroughFormatter.php

@@ -26,6 +26,6 @@ class PassthroughFormatter implements Formatter
      */
     public function format(Tag $tag)
     {
-        return (string)$tag;
+        return '@' . $tag->getName() . ' ' . (string)$tag;
     }
 }

src/DocBlock/Tags/Generic.php

@@ -68,7 +68,7 @@ public static function create(
      */
     public function __toString()
     {
-        return '@' . $this->getName() . ($this->description ? ' ' . $this->description->render() : '');
+        return ($this->description ? $this->description->render() : '');
     }
 
     /**