Fixes implementation of Example tag

src/DocBlock/Tags/Example.php

@@ -12,7 +12,9 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
+use phpDocumentor\Reflection\DocBlock\Description;
 use phpDocumentor\Reflection\DocBlock\Tag;
+use Webmozart\Assert\Assert;
 
 /**
  * Reflection class for a {@}example tag in a Docblock.
@@ -22,7 +24,7 @@ final class Example extends BaseTag
     /**
      * @var string Path to a file to use as an example. May also be an absolute URI.
      */
-    private $filePath = '';
+    private $filePath;
 
     /**
      * @var bool Whether the file path component represents an URI. This determines how the file portion
@@ -30,6 +32,32 @@ final class Example extends BaseTag
      */
     private $isURI = false;
 
+    /**
+     * @var
+     */
+    private $startingLine;
+
+    /**
+     * @var
+     */
+    private $lineCount;
+
+    public function __construct($filePath, $isURI, $startingLine, $lineCount, $description)
+    {
+        Assert::notEmpty($filePath);
+        Assert::integer($startingLine);
+        Assert::greaterThanEq($startingLine, 0);
+
+        $this->filePath = $filePath;
+        $this->startingLine = $startingLine;
+        $this->lineCount = $lineCount;
+        if ($description !== null) {
+            $this->description = trim($description);
+        }
+
+        $this->isURI = $isURI;
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -43,7 +71,7 @@ final class Example extends BaseTag
                     :$this->filePath;
             }
 
-            $this->description = $filePath . ' ' . parent::getContent();
+            return trim($filePath . ' ' . parent::getDescription());
         }
 
         return $this->description;
@@ -71,16 +99,29 @@ final class Example extends BaseTag
         $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];
-            }
+        if (array_key_exists(3, $matches)) {
             $description = $matches[3];
+
+            // Starting line / Number of lines / Description
+            if (preg_match('/^([1-9]\d*)(?:\s+((?1))\s*)?(.*)$/sux', $matches[3], $contentMatches)) {
+                $startingLine = (int)$contentMatches[1];
+                if (isset($contentMatches[2]) && $contentMatches[2] !== '') {
+                    $lineCount = (int)$contentMatches[2];
+                }
+
+                if (array_key_exists(3, $contentMatches)) {
+                    $description = $contentMatches[3];
+                }
+            }
         }
 
-        return new static($filePath, $fileUri, $startingLine, $lineCount, $description);
+        return new static(
+            $filePath !== null?$filePath:$fileUri,
+            $fileUri !== null,
+            $startingLine,
+            $lineCount,
+            $description
+        );
     }
 
     /**
@@ -94,46 +135,6 @@ final class Example extends BaseTag
         return $this->filePath;
     }
 
-    /**
-     * Sets the file path.
-     *
-     * @param string $filePath The new file path to use for the example.
-     *
-     * @return $this
-     */
-    public function setFilePath($filePath)
-    {
-        $this->isURI = false;
-        $this->filePath = trim($filePath);
-
-        $this->description = null;
-        return $this;
-    }
-
-    /**
-     * Sets the file path as an URI.
-     *
-     * This function is equivalent to {@link setFilePath()}, except that it
-     * converts an URI to a file path before that.
-     *
-     * There is no getFileURI(), as {@link getFilePath()} is compatible.
-     *
-     * @param string $uri The new file URI to use as an example.
-     *
-     * @return $this
-     */
-    public function setFileURI($uri)
-    {
-        $this->isURI   = true;
-        $this->description = null;
-
-        $this->filePath = $this->isUriRelative($uri)
-            ? rawurldecode(str_replace(array('/', '\\'), '%2F', $uri))
-            : $this->filePath = $uri;
-
-        return $this;
-    }
-
     /**
      * Returns a string representation for this tag.
      *
@@ -141,7 +142,7 @@ final class Example extends BaseTag
      */
     public function __toString()
     {
-        return $this->filePath . ($this->description ? ' ' . $this->description->render() : '');
+        return $this->filePath . ($this->description ? ' ' . $this->description : '');
     }
 
     /**
@@ -155,4 +156,20 @@ final class Example extends BaseTag
     {
         return false === strpos($uri, ':');
     }
+
+    /**
+     * @return int
+     */
+    public function getStartingLine()
+    {
+        return $this->startingLine;
+    }
+
+    /**
+     * @return int
+     */
+    public function getLineCount()
+    {
+        return $this->lineCount;
+    }
 }

tests/unit/DocBlock/Tags/ExampleTest.php

@@ -0,0 +1,102 @@
+<?php
+
+namespace DocBlock\Tags;
+
+use phpDocumentor\Reflection\DocBlock\Tags\Example;
+
+/**
+ * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\Tags\Example
+ */
+class ExampleTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @covers ::create
+     * @covers ::__construct
+     * @covers ::getContent
+     * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     */
+    public function testExampleWithoutContent()
+    {
+        $tag = Example::create('"example1.php"');
+        $this->assertEquals('"example1.php"', $tag->getContent());
+        $this->assertEquals('', $tag->getDescription());
+    }
+
+    /**
+     * @covers ::create
+     * @covers ::__construct
+     * @covers ::getFilePath
+     * @covers ::getDescription
+     * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     */
+    public function testWithDescription()
+    {
+        $tag = Example::create('"example1.php" some text');
+        $this->assertEquals('example1.php', $tag->getFilePath());
+        $this->assertEquals('some text', $tag->getDescription());
+    }
+
+    /**
+     * @covers ::create
+     * @covers ::__construct
+     * @covers ::getFilePath
+     * @covers ::getStartingLine
+     * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     */
+    public function testStartlineIsParsed()
+    {
+        $tag = Example::create('"example1.php" 10');
+        $this->assertEquals('example1.php', $tag->getFilePath());
+        $this->assertEquals(10, $tag->getStartingLine());
+    }
+
+    /**
+     * @covers ::create
+     * @covers ::__construct
+     * @covers ::getFilePath
+     * @covers ::getStartingLine
+     * @covers ::getDescription
+     * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     */
+    public function testAllowOmitingLineCount()
+    {
+        $tag = Example::create('"example1.php" 10 some text');
+        $this->assertEquals('example1.php', $tag->getFilePath());
+        $this->assertEquals(10, $tag->getStartingLine());
+        $this->assertEquals('some text', $tag->getDescription());
+    }
+
+    /**
+     * @covers ::create
+     * @covers ::__construct
+     * @covers ::getFilePath
+     * @covers ::getStartingLine
+     * @covers ::getLineCount
+     * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     */
+    public function testLengthIsParsed()
+    {
+        $tag = Example::create('"example1.php" 10 5');
+        $this->assertEquals('example1.php', $tag->getFilePath());
+        $this->assertEquals(10, $tag->getStartingLine());
+        $this->assertEquals(5, $tag->getLineCount());
+    }
+
+    /**
+     * @covers ::create
+     * @covers ::__construct
+     * @covers ::getFilePath
+     * @covers ::getStartingLine
+     * @covers ::getLineCount
+     * @covers ::getDescription
+     * @uses phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     */
+    public function testFullExample()
+    {
+        $tag = Example::create('"example1.php" 10 5 test text');
+        $this->assertEquals('example1.php', $tag->getFilePath());
+        $this->assertEquals(10, $tag->getStartingLine());
+        $this->assertEquals(5, $tag->getLineCount());
+        $this->assertEquals('test text', $tag->getDescription());
+    }
+}