Add example on writing your own Tag and prepare for TagFactory objects

src/DocBlock/Serializer.php

@@ -109,7 +109,8 @@ class Serializer
      */
     private function getSummaryAndDescriptionTextBlock(DocBlock $docblock, $wrapLength)
     {
-        $text = $docblock->getSummary() . "\n\n" . $docblock->getDescription();
+        $text = $docblock->getSummary() . ((string)$docblock->getDescription() ? "\n\n" . $docblock->getDescription()
+                : '');
         if ($wrapLength !== null) {
             $text = wordwrap($text, $wrapLength);
             return $text;

src/DocBlock/StandardTagFactory.php

@@ -12,6 +12,7 @@
 
 namespace phpDocumentor\Reflection\DocBlock;
 
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\FqsenResolver;
 use phpDocumentor\Reflection\Types\Context;
@@ -139,7 +140,7 @@ final class StandardTagFactory implements TagFactory
         Assert::stringNotEmpty($tagName);
         Assert::stringNotEmpty($handler);
         Assert::classExists($handler);
-        Assert::implementsInterface($handler, Tag::class);
+        Assert::implementsInterface($handler, StaticMethod::class);
 
         if (strpos($tagName, '\\') && $tagName[0] !== '\\') {
             throw new \InvalidArgumentException(

src/DocBlock/Tags/Author.php

@@ -17,7 +17,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for an {@}author tag in a Docblock.
  */
-final class Author extends BaseTag
+final class Author extends BaseTag implements Factory\StaticMethod
 {
     /** @var string register that this is the author tag. */
     protected $name = 'author';

src/DocBlock/Tags/Covers.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a @covers tag in a Docblock.
  */
-final class Covers extends BaseTag
+final class Covers extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'covers';
 

src/DocBlock/Tags/Deprecated.php

@@ -20,7 +20,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}deprecated tag in a Docblock.
  */
-final class Deprecated extends BaseTag
+final class Deprecated extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'deprecated';
 

src/DocBlock/Tags/Factory/StaticMethod.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+interface StaticMethod
+{
+    public static function create($body);
+}

src/DocBlock/Tags/Factory/Strategy.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+interface Strategy
+{
+    public function create($body);
+}

src/DocBlock/Tags/Generic.php

@@ -21,7 +21,7 @@ use Webmozart\Assert\Assert;
 /**
  * Parses a tag definition for a DocBlock.
  */
-class Generic extends BaseTag
+class Generic extends BaseTag implements Factory\StaticMethod
 {
     /**
      * Parses a tag and populates the member variables.

src/DocBlock/Tags/Link.php

@@ -20,7 +20,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a @link tag in a Docblock.
  */
-final class Link extends BaseTag
+final class Link extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'link';
 

src/DocBlock/Tags/Method.php

@@ -23,7 +23,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for an {@}method in a Docblock.
  */
-final class Method extends BaseTag
+final class Method extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'method';
 

src/DocBlock/Tags/Param.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for the {@}param tag in a Docblock.
  */
-final class Param extends BaseTag
+final class Param extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'param';

src/DocBlock/Tags/Property.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}property tag in a Docblock.
  */
-class Property extends BaseTag
+class Property extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'property';

src/DocBlock/Tags/PropertyRead.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}property-read tag in a Docblock.
  */
-class PropertyRead extends BaseTag
+class PropertyRead extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'property-read';

src/DocBlock/Tags/PropertyWrite.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}property-write tag in a Docblock.
  */
-class PropertyWrite extends BaseTag
+class PropertyWrite extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'property-write';

src/DocBlock/Tags/Return_.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}return tag in a Docblock.
  */
-final class Return_ extends BaseTag
+final class Return_ extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'return';
 

src/DocBlock/Tags/See.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for an {@}see tag in a Docblock.
  */
-class See extends BaseTag
+class See extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'see';
 

src/DocBlock/Tags/Since.php

@@ -20,7 +20,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}since tag in a Docblock.
  */
-final class Since extends BaseTag
+final class Since extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'since';
 

src/DocBlock/Tags/Source.php

@@ -20,7 +20,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}source tag in a Docblock.
  */
-final class Source extends BaseTag
+final class Source extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'source';

src/DocBlock/Tags/Throws.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}throws tag in a Docblock.
  */
-final class Throws extends BaseTag
+final class Throws extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'throws';
 

src/DocBlock/Tags/Uses.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}uses tag in a Docblock.
  */
-final class Uses extends BaseTag
+final class Uses extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'uses';
 

src/DocBlock/Tags/Var_.php

@@ -22,7 +22,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}var tag in a Docblock.
  */
-class Var_ extends BaseTag
+class Var_ extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'var';

src/DocBlock/Tags/Version.php

@@ -20,7 +20,7 @@ use Webmozart\Assert\Assert;
 /**
  * Reflection class for a {@}version tag in a Docblock.
  */
-final class Version extends BaseTag
+final class Version extends BaseTag implements Factory\StaticMethod
 {
     protected $name = 'version';
 

src/DocBlockFactory.php

@@ -54,11 +54,12 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         $tagFactory->addService($descriptionFactory);
         $tagFactory->addService(new TypeResolver($fqsenResolver));
 
-        foreach ($additionalTags as $tagName => $tagClassName) {
-            $tagFactory->registerTagHandler($tagName, $tagClassName);
+        $docBlockFactory = new self($descriptionFactory, $tagFactory);
+        foreach ($additionalTags as $tagName => $tagHandler) {
+            $docBlockFactory->registerTagHandler($tagName, $tagHandler);
         }
 
-        return new self($descriptionFactory, $tagFactory);
+        return $docBlockFactory;
     }
 
     /**
@@ -100,6 +101,11 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         );
     }
 
+    public function registerTagHandler($tagName, $handler)
+    {
+        $this->tagFactory->registerTagHandler($tagName, $handler);
+    }
+
     /**
      * Strips the asterisks from the DocBlock comment.
      *