From c054cfdfe1ee0d06c9347f9548c368c23ad8102c Mon Sep 17 00:00:00 2001 From: Jaapio Date: Fri, 18 Aug 2017 23:00:12 +0200 Subject: [PATCH] Fixes implementation of Example tag --- src/DocBlock/Tags/Example.php | 117 +++++++++++++---------- tests/unit/DocBlock/Tags/ExampleTest.php | 102 ++++++++++++++++++++ 2 files changed, 169 insertions(+), 50 deletions(-) create mode 100644 tests/unit/DocBlock/Tags/ExampleTest.php diff --git a/src/DocBlock/Tags/Example.php b/src/DocBlock/Tags/Example.php index 571ef8d..f56222d 100644 --- a/src/DocBlock/Tags/Example.php +++ b/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; + } } diff --git a/tests/unit/DocBlock/Tags/ExampleTest.php b/tests/unit/DocBlock/Tags/ExampleTest.php new file mode 100644 index 0000000..d70f226 --- /dev/null +++ b/tests/unit/DocBlock/Tags/ExampleTest.php @@ -0,0 +1,102 @@ +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()); + } +}