Add support for DocBlock template markers

DocBlocks may start with #@+ and #@- to indicate that they are (the start) of a DocBlock
template or the end of a template.

In this commit I have changed the way a DocBlock is parsed to interpret this information
and added tests to show for it. In addition I have added more comments to the Regular
Expression responsible for splitting a DocBlock to show the business rules more clearly.

This is the first step in implementing https://github.com/phpDocumentor/phpDocumentor2/issues/42.

tests/phpDocumentor/Reflection/DocBlockTest.php

@@ -71,6 +71,7 @@ DOCBLOCK;
 
     /**
      * @covers \phpDocumentor\Reflection\DocBlock::splitDocBlock
+     * @group test
      * 
      * @return void
      */
@@ -91,6 +92,35 @@ DOCBLOCK;
         $this->assertFalse($object->hasTag('category'));
     }
 
+    public function testIfStartOfTemplateIsDiscovered()
+    {
+        $fixture = <<<DOCBLOCK
+/**#@+
+ * @see \MyClass
+ * @return void
+ */
+DOCBLOCK;
+        $object = new DocBlock($fixture);
+        $this->assertEquals('', $object->getShortDescription());
+        $this->assertEquals('', $object->getLongDescription()->getContents());
+        $this->assertCount(2, $object->getTags());
+        $this->assertTrue($object->hasTag('see'));
+        $this->assertTrue($object->hasTag('return'));
+        $this->assertFalse($object->hasTag('category'));
+        $this->assertTrue($object->isTemplateStart());
+    }
+
+    public function testIfEndOfTemplateIsDiscovered()
+    {
+        $fixture = <<<DOCBLOCK
+/**#@-*/
+DOCBLOCK;
+        $object = new DocBlock($fixture);
+        $this->assertEquals('', $object->getShortDescription());
+        $this->assertEquals('', $object->getLongDescription()->getContents());
+        $this->assertTrue($object->isTemplateEnd());
+    }
+
     /**
      * @covers \phpDocumentor\Reflection\DocBlock::cleanInput
      *