From 903722e389c72f50f42057bf170f006b3e8d92e2 Mon Sep 17 00:00:00 2001 From: Vasil Rangelov Date: Tue, 13 Nov 2012 17:09:05 +0200 Subject: [PATCH] Renamed LongDescription to Description, to better serve its new dual role as "holder for a place where inline tags can occur"; Removed Tag::setDocblock() in favor of an additional constructor argument that defaults to NULL; Tag::createInstance() and Description's constructor now have a second argument, allowing the specification of an owning DocBlock; Description::getParsedContents() assigns the Description's owning DocBlock object when creating tags. --- src/phpDocumentor/Reflection/DocBlock.php | 6 +-- .../{LongDescription.php => Description.php} | 16 ++++-- src/phpDocumentor/Reflection/DocBlock/Tag.php | 50 +++++++++---------- ...escriptionTest.php => DescriptionTest.php} | 26 +++++----- 4 files changed, 50 insertions(+), 48 deletions(-) rename src/phpDocumentor/Reflection/DocBlock/{LongDescription.php => Description.php} (91%) rename tests/phpDocumentor/Reflection/DocBlock/{LongDescriptionTest.php => DescriptionTest.php} (91%) diff --git a/src/phpDocumentor/Reflection/DocBlock.php b/src/phpDocumentor/Reflection/DocBlock.php index fa2a4cb..b55b470 100644 --- a/src/phpDocumentor/Reflection/DocBlock.php +++ b/src/phpDocumentor/Reflection/DocBlock.php @@ -83,7 +83,7 @@ class DocBlock implements \Reflector list($short, $long, $tags) = $this->splitDocBlock($docblock); $this->short_description = $short; - $this->long_description = new DocBlock\LongDescription($long); + $this->long_description = new DocBlock\Description($long); $this->parseTags($tags); $this->namespace = $namespace; @@ -222,9 +222,7 @@ class DocBlock implements \Reflector // create proper Tag objects foreach ($result as $key => $tag_line) { - $tag = DocBlock\Tag::createInstance($tag_line); - $tag->setDocBlock($this); - $result[$key] = $tag; + $result[$key] = DocBlock\Tag::createInstance($tag_line, $this); } } diff --git a/src/phpDocumentor/Reflection/DocBlock/LongDescription.php b/src/phpDocumentor/Reflection/DocBlock/Description.php similarity index 91% rename from src/phpDocumentor/Reflection/DocBlock/LongDescription.php rename to src/phpDocumentor/Reflection/DocBlock/Description.php index 3c26035..b9cad7d 100644 --- a/src/phpDocumentor/Reflection/DocBlock/LongDescription.php +++ b/src/phpDocumentor/Reflection/DocBlock/Description.php @@ -13,13 +13,13 @@ namespace phpDocumentor\Reflection\DocBlock; /** - * Parses a Long Description of a DocBlock. + * Parses a Description of a DocBlock or tag. * * @author Mike van Riel * @license http://www.opensource.org/licenses/mit-license.php MIT * @link http://phpdoc.org */ -class LongDescription implements \Reflector +class Description implements \Reflector { /** @var string */ protected $contents = ''; @@ -30,15 +30,20 @@ class LongDescription implements \Reflector /** @var \phpDocumentor\Reflection\DocBlock\Tags[] */ protected $tags = array(); + /** @var DocBlock The DocBlock which this description belongs to. */ + protected $docblock = null; + /** * Parses the string for inline tags and if the Markdown class is included; * format the found text. * - * @param string $content the DocBlock contents without asterisks. + * @param string $content The DocBlock contents without asterisks. + * @param DocBlock $docblock The DocBlock which this description belongs to. */ - public function __construct($content) + public function __construct($content, DocBlock $docblock = null) { $this->contents = trim($content); + $this->docblock = $docblock; } /** @@ -97,7 +102,8 @@ class LongDescription implements \Reflector ); for ($i=1, $l = count($this->parsedContents); $i<$l; $i += 2) { $this->parsedContents[$i] = Tag::createInstance( - $this->parsedContents[$i] + $this->parsedContents[$i], + $this->docblock ); } diff --git a/src/phpDocumentor/Reflection/DocBlock/Tag.php b/src/phpDocumentor/Reflection/DocBlock/Tag.php index 1c8be4a..4f0e26e 100644 --- a/src/phpDocumentor/Reflection/DocBlock/Tag.php +++ b/src/phpDocumentor/Reflection/DocBlock/Tag.php @@ -12,6 +12,8 @@ namespace phpDocumentor\Reflection\DocBlock; +use phpDocumentor\Reflection\DocBlock; + /** * Parses a tag definition for a DocBlock. * @@ -36,8 +38,8 @@ class Tag implements \Reflector /** @var int Line number of the tag */ protected $line_number = 0; - /** @var \phpDocumentor\Reflection\DocBlock docblock class */ - protected $docblock; + /** @var DocBlock The DocBlock which this tag belongs to. */ + protected $docblock = null; /** * @var array An array with a tag as a key, and an FQCN to a class that @@ -78,14 +80,17 @@ class Tag implements \Reflector /** * Factory method responsible for instantiating the correct sub type. * - * @param string $tag_line The text for this tag, including description. + * @param string $tag_line The text for this tag, including description. + * @param DocBlock $docblock The DocBlock which this tag belongs to. * * @throws \InvalidArgumentException if an invalid tag line was presented. * - * @return \phpDocumentor\Reflection\DocBlock\Tag + * @return static A new tag object. */ - final public static function createInstance($tag_line) - { + final public static function createInstance( + $tag_line, + DocBlock $docblock = null + ) { if (!preg_match( '/^@([\w\-\_\\\\]+)(?:\s*([^\s].*)|$)?/us', $tag_line, @@ -100,10 +105,15 @@ class Tag implements \Reflector $handler = self::$tagHandlerMappings[$matches[1]]; return new $handler( $matches[1], - isset($matches[2]) ? $matches[2] : '' + isset($matches[2]) ? $matches[2] : '', + $docblock ); } - return new self($matches[1], isset($matches[2]) ? $matches[2] : ''); + return new self( + $matches[1], + isset($matches[2]) ? $matches[2] : '', + $docblock + ); } /** @@ -141,14 +151,16 @@ class Tag implements \Reflector /** * Parses a tag and populates the member variables. * - * @param string $type Name of the tag. - * @param string $content The contents of the given tag. + * @param string $type Name of the tag. + * @param string $content The contents of the given tag. + * @param DocBlock $docblock The DocBlock which this tag belongs to. */ - public function __construct($type, $content) + public function __construct($type, $content, DocBlock $docblock = null) { $this->tag = $type; $this->content = $content; $this->description = $content; + $this->docblock = $docblock; } /** @@ -190,7 +202,7 @@ class Tag implements \Reflector public function getParsedDescription() { if (null === $this->parsedDescription) { - $description = new LongDescription($this->description); + $description = new Description($this->description, $this->docblock); $this->parsedDescription = $description->getParsedContents(); } return $this->parsedDescription; @@ -218,20 +230,6 @@ class Tag implements \Reflector return $this->line_number; } - /** - * Inject the docblock class - * - * This exposes some common functionality contained in the docblock abstract. - * - * @param object $docblock Object containing the DocBlock. - * - * @return void - */ - public function setDocBlock($docblock) - { - $this->docblock = $docblock; - } - /** * Builds a string representation of this object. * diff --git a/tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php b/tests/phpDocumentor/Reflection/DocBlock/DescriptionTest.php similarity index 91% rename from tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php rename to tests/phpDocumentor/Reflection/DocBlock/DescriptionTest.php index b262403..8b48060 100644 --- a/tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php +++ b/tests/phpDocumentor/Reflection/DocBlock/DescriptionTest.php @@ -1,6 +1,6 @@ * @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 */ -class LongDescriptionTest extends \PHPUnit_Framework_TestCase +class DescriptionTest extends \PHPUnit_Framework_TestCase { public function testConstruct() { $fixture = <<assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -41,7 +41,7 @@ LONGDESC; This is text for a {@link http://phpdoc.org/ description} that uses inline tags. LONGDESC; - $object = new LongDescription($fixture); + $object = new Description($fixture); $this->assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -64,7 +64,7 @@ tags.', {@link http://phpdoc.org/ This} is text for a description that uses inline tags. LONGDESC; - $object = new LongDescription($fixture); + $object = new Description($fixture); $this->assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -88,7 +88,7 @@ tags.', This is text for a description with {@internal inline tag with {@link http://phpdoc.org another inline tag} in it}. LONGDESC; - $object = new LongDescription($fixture); + $object = new Description($fixture); $this->assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -119,7 +119,7 @@ LONGDESC; $fixture = <<assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -133,7 +133,7 @@ LONGDESC; This is text for a description containing {@internal inline tag that has { that is literal}. LONGDESC; - $object = new LongDescription($fixture); + $object = new Description($fixture); $this->assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -160,7 +160,7 @@ is literal'), $fixture = <<assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -177,7 +177,7 @@ LONGDESC; This is text for a description with {@internal inline tag with {} that is not an inline tag}. LONGDESC; - $object = new LongDescription($fixture); + $object = new Description($fixture); $this->assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -204,7 +204,7 @@ inline tag'), $fixture = <<assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents(); @@ -221,7 +221,7 @@ LONGDESC; This is text for a description with an {@internal inline tag with literal {{@}link{} in it}. LONGDESC; - $object = new LongDescription($fixture); + $object = new Description($fixture); $this->assertSame($fixture, $object->getContents()); $parsedContents = $object->getParsedContents();