Add integration test and example on how to read tags

Author: mvriel

examples/interpreting-a-simple-docblock.php renamed to examples/01-interpreting-a-simple-docblock.php

@@ -0,0 +1,24 @@
+<?php
+require_once(__DIR__ . '/../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * @see \phpDocumentor\Reflection\DocBlock\StandardTagFactory
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// You can check if a DocBlock has one or more see tags
+$hasSeeTag = $docblock->hasTag('see');
+
+// Or we can get a complete list of all tags
+$tags = $docblock->getTags();
+
+// But we can also grab all tags of a specific type, such as `see`
+$seeTags = $docblock->getTagsByName('see');

examples/02-interpreting-tags.php

@@ -13,6 +13,9 @@
 namespace phpDocumentor\Reflection;
 
 use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\StandardTagFactory;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Tags\See;
 
 /**
  * @coversNothing
@@ -29,7 +32,7 @@ public function testInterpretingASimpleDocBlock()
          * @var string      $summary
          * @var Description $description
          */
-        include(__DIR__ . '/../../examples/interpreting-a-simple-docblock.php');
+        include(__DIR__ . '/../../examples/01-interpreting-a-simple-docblock.php');
 
         $descriptionText = <<<DESCRIPTION
 This is a Description. A Summary and Description are separated by either
@@ -44,4 +47,26 @@ public function testInterpretingASimpleDocBlock()
         $this->assertSame($descriptionText, $description->render());
         $this->assertEmpty($docblock->getTags());
     }
+
+    public function testInterpretingTags()
+    {
+        /**
+         * @var DocBlock $docblock
+         * @var boolean  $hasSeeTag
+         * @var Tag[]    $tags
+         * @var See[]    $seeTags
+         */
+        include(__DIR__ . '/../../examples/02-interpreting-tags.php');
+
+        $this->assertTrue($hasSeeTag);
+        $this->assertCount(1, $tags);
+        $this->assertCount(1, $seeTags);
+
+        $this->assertInstanceOf(See::class, $tags[0]);
+        $this->assertInstanceOf(See::class, $seeTags[0]);
+
+        $seeTag = $seeTags[0];
+        $this->assertSame('\\' . StandardTagFactory::class, (string)$seeTag->getReference());
+        $this->assertSame('', (string)$seeTag->getDescription());
+    }
 }