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

@@ -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);
+                $result[$key] = DocBlock\Tag::createInstance($tag_line, $this);
-                $tag->setDocBlock($this);
-                $result[$key] = $tag;
             }
         }
 

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 <mike.vanriel@naenius.com>
  * @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
                 );
             }
 

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 */
+    /** @var DocBlock The DocBlock which this tag belongs to. */
-    protected $docblock;
+    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   $type     Name of the tag.
-     * @param string $content The contents of the given 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.
      *

tests/phpDocumentor/Reflection/DocBlock/DescriptionTest.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * phpDocumentor Long Description Test
+ * phpDocumentor Description Test
  *
  * PHP Version 5.3
  *
@@ -13,21 +13,21 @@
 namespace phpDocumentor\Reflection\DocBlock;
 
 /**
- * Test class for phpDocumentor\Reflection\DocBlock\LongDescription
+ * Test class for phpDocumentor\Reflection\DocBlock\Description
  *
  * @author    Vasil Rangelov <boen.robot@gmail.com>
  * @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 = <<<LONGDESC
 This is text for a description.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->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 = <<<LONGDESC
 This is text for a description containing { that is literal.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->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 = <<<LONGDESC
 This is text for a description with {} that is not a tag.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->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 = <<<LONGDESC
 This is text for a description with literal {{@}link}.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->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();