Refactored the source tag and written test

src/DocBlock/Tags/Link.php

@@ -47,13 +47,12 @@ final class Link extends BaseTag
     public static function create($body, DescriptionFactory $descriptionFactory = null, Context $context = null)
     {
         Assert::string($body);
+        Assert::notNull($descriptionFactory);
 
         $parts = preg_split('/\s+/Su', $body, 2);
-
-        $link = $parts[0];
         $description = isset($parts[1]) ? $descriptionFactory->create($parts[1], $context) : null;
 
-        return new static($link, $description);
+        return new static($parts[0], $description);
     }
 
     /**

src/DocBlock/Tags/Param.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for the {@}param tag in a Docblock.
  */
-class Param extends BaseTag
+final class Param extends BaseTag
 {
     /** @var string */
     protected $name = 'param';
@@ -31,10 +31,10 @@ class Param extends BaseTag
     private $type;
 
     /** @var string */
-    protected $variableName = '';
+    private $variableName = '';
 
     /** @var bool determines whether this is a variadic argument */
-    protected $isVariadic = false;
+    private $isVariadic = false;
 
     /**
      * @param string $variableName

src/DocBlock/Tags/Source.php

@@ -1,80 +1,68 @@
 <?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-2015 Mike van Riel<[email protected]>
- * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
  * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
 
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
-use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\Types\Context;
+use Webmozart\Assert\Assert;
 
 /**
- * Reflection class for a @source tag in a Docblock.
+ * Reflection class for a {@}source tag in a Docblock.
  */
-class Source extends Tag
+final class Source extends BaseTag
 {
-    /**
+    /** @var string */
-     * @var int The starting line, relative to the structural element's
+    protected $name = 'source';
-     *     location.
-     */
-    protected $startingLine = 1;
 
-    /**
+    /** @var int The starting line, relative to the structural element's location. */
-     * @var int|null The number of lines, relative to the starting line. NULL
+    private $startingLine = 1;
-     *     means "to the end".
-     */
-    protected $lineCount = null;
 
-    /**
+    /** @var int|null The number of lines, relative to the starting line. NULL means "to the end". */
-     * {@inheritdoc}
+    private $lineCount = null;
-     */
+
-    public function getContent()
+    public function __construct($startingLine, $lineCount = null, Description $description = null)
     {
-        if (null === $this->description) {
+        Assert::integerish($startingLine);
-            $this->description
+        Assert::nullOrIntegerish($lineCount);
-                = "{$this->startingLine} {$this->lineCount} {$this->description}";
-        }
 
-        return $this->description;
+        $this->startingLine = (int)$startingLine;
+        $this->lineCount    = $lineCount !== null ? (int)$lineCount : null;
+        $this->description  = $description;
     }
 
     /**
      * {@inheritdoc}
      */
-    public function setContent($content)
+    public static function create($body, DescriptionFactory $descriptionFactory = null, Context $context = null)
     {
-        parent::setContent($content);
+        Assert::stringNotEmpty($body);
-        if (preg_match(
+        Assert::notNull($descriptionFactory);
-            '/^
+
-                # Starting line
+        $startingLine = 1;
-                ([1-9]\d*)
+        $lineCount    = null;
-                \s*
+        $description  = null;
-                # Number of lines
+
-                (?:
+        // Starting line / Number of lines / Description
-                    ((?1))
+        if (preg_match('/^([1-9]\d*)\s*(?:((?1))\s+)?(.*)$/sux', $body, $matches)) {
-                    \s+
+            $startingLine = (int)$matches[1];
-                )?
+            if (isset($matches[2]) && $matches[2] !== '') {
-                # Description
+                $lineCount = (int)$matches[2];
-                (.*)
-            $/sux',
-            $this->description,
-            $matches
-        )) {
-            $this->startingLine = (int)$matches[1];
-            if (isset($matches[2]) && '' !== $matches[2]) {
-                $this->lineCount = (int)$matches[2];
             }
-            $this->setDescription($matches[3]);
+            $description = $matches[3];
-            $this->description = $content;
         }
 
-        return $this;
+        return new static($startingLine, $lineCount, $descriptionFactory->create($description, $context));
     }
 
     /**
@@ -88,22 +76,6 @@ class Source extends Tag
         return $this->startingLine;
     }
 
-    /**
-     * Sets the starting line.
-     *
-     * @param int $startingLine The new starting line, relative to the
-     *     structural element's location.
-     *
-     * @return $this
-     */
-    public function setStartingLine($startingLine)
-    {
-        $this->startingLine = $startingLine;
-
-        $this->description = null;
-        return $this;
-    }
-
     /**
      * Returns the number of lines.
      *
@@ -115,19 +87,10 @@ class Source extends Tag
         return $this->lineCount;
     }
 
-    /**
+    public function __toString()
-     * Sets the number of lines.
-     *
-     * @param int|null $lineCount The new number of lines, relative to the
-     *     starting line. NULL means "to the end".
-     *
-     * @return $this
-     */
-    public function setLineCount($lineCount)
     {
-        $this->lineCount = $lineCount;
+        return $this->startingLine
-
+        . ($this->lineCount !== null ? ' ' . $this->lineCount : '')
-        $this->description = null;
+        . ($this->description ? ' ' . $this->description->render() : '');
-        return $this;
     }
 }

tests/unit/DocBlock/Tags/SourceTest.php

@@ -0,0 +1,198 @@
+<?php
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags;
+
+use Mockery as m;
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\TypeResolver;
+use phpDocumentor\Reflection\Types\Context;
+use phpDocumentor\Reflection\Types\String_;
+
+/**
+ * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\Tags\Source
+ * @covers ::<private>
+ */
+class SourceTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Source::__construct
+     * @uses   \phpDocumentor\Reflection\DocBlock\Description
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
+     */
+    public function testIfCorrectTagNameIsReturned()
+    {
+        $fixture = new Source(1, null, new Description('Description'));
+
+        $this->assertSame('source', $fixture->getName());
+    }
+
+    /**
+     * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Source::__construct
+     * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Source::__toString
+     * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
+     * @uses   \phpDocumentor\Reflection\DocBlock\Description
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     */
+    public function testIfTagCanBeRenderedUsingDefaultFormatter()
+    {
+        $fixture = new Source(1, 10, new Description('Description'));
+        $this->assertSame('1 10 Description', $fixture->render());
+
+        $fixture = new Source(1, null, new Description('Description'));
+        $this->assertSame('1 Description', $fixture->render());
+
+        $fixture = new Source(1);
+        $this->assertSame('1', $fixture->render());
+    }
+
+    /**
+     * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Source::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     */
+    public function testIfTagCanBeRenderedUsingSpecificFormatter()
+    {
+        $fixture = new Source(1);
+
+        $formatter = m::mock(Formatter::class);
+        $formatter->shouldReceive('format')->with($fixture)->andReturn('Rendered output');
+
+        $this->assertSame('Rendered output', $fixture->render($formatter));
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::getStartingLine
+     */
+    public function testHasStartingLine()
+    {
+        $expected = 1;
+
+        $fixture = new Source($expected);
+
+        $this->assertSame($expected, $fixture->getStartingLine());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::getLineCount
+     */
+    public function testHasLineCount()
+    {
+        $expected = 2;
+
+        $fixture = new Source(1, $expected);
+
+        $this->assertSame($expected, $fixture->getLineCount());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getDescription
+     * @uses   \phpDocumentor\Reflection\DocBlock\Description
+     */
+    public function testHasDescription()
+    {
+        $expected = new Description('Description');
+
+        $fixture = new Source('1', null, $expected);
+
+        $this->assertSame($expected, $fixture->getDescription());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::__toString
+     * @uses   \phpDocumentor\Reflection\DocBlock\Description
+     * @uses   \phpDocumentor\Reflection\Types\String_
+     */
+    public function testStringRepresentationIsReturned()
+    {
+        $fixture = new Source(1, 10, new Description('Description'));
+
+        $this->assertSame('1 10 Description', (string)$fixture);
+    }
+
+    /**
+     * @covers ::create
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\Source::<public>
+     * @uses \phpDocumentor\Reflection\DocBlock\DescriptionFactory
+     * @uses \phpDocumentor\Reflection\DocBlock\Description
+     * @uses \phpDocumentor\Reflection\Types\Context
+     */
+    public function testFactoryMethod()
+    {
+        $descriptionFactory = m::mock(DescriptionFactory::class);
+        $context            = new Context('');
+
+        $description = new Description('My Description');
+        $descriptionFactory->shouldReceive('create')->with('My Description', $context)->andReturn($description);
+
+        $fixture = Source::create('1 10 My Description', $descriptionFactory, $context);
+
+        $this->assertSame('1 10 My Description', (string)$fixture);
+        $this->assertSame(1, $fixture->getStartingLine());
+        $this->assertSame(10, $fixture->getLineCount());
+        $this->assertSame($description, $fixture->getDescription());
+    }
+
+    /**
+     * @covers ::create
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\Source::<public>
+     * @uses \phpDocumentor\Reflection\TypeResolver
+     * @uses \phpDocumentor\Reflection\DocBlock\DescriptionFactory
+     * @expectedException \InvalidArgumentException
+     */
+    public function testFactoryMethodFailsIfEmptyBodyIsGiven()
+    {
+        $descriptionFactory = m::mock(DescriptionFactory::class);
+        Source::create('', $descriptionFactory);
+    }
+
+    /**
+     * @covers ::create
+     * @expectedException \InvalidArgumentException
+     */
+    public function testFactoryMethodFailsIfBodyIsNotString()
+    {
+        Source::create([]);
+    }
+
+    /**
+     * @covers ::create
+     * @uses \phpDocumentor\Reflection\TypeResolver
+     * @expectedException \InvalidArgumentException
+     */
+    public function testFactoryMethodFailsIfDescriptionFactoryIsNull()
+    {
+        Source::create('1');
+    }
+
+    /**
+     * @covers ::__construct
+     * @expectedException \InvalidArgumentException
+     */
+    public function testExceptionIsThrownIfStartingLineIsNotInteger()
+    {
+        new Source('blabla');
+    }
+
+    /**
+     * @covers ::__construct
+     * @expectedException \InvalidArgumentException
+     */
+    public function testExceptionIsThrownIfLineCountIsNotIntegerOrNull()
+    {
+        new Source('1', []);
+    }
+}