Move Context / ContextFactory to correct location

Other location isn't autoloaded correctly.

.gitignore

@@ -1,2 +1,3 @@
 .idea
+composer.lock
 vendor

.scrutinizer.yml

@@ -0,0 +1,45 @@
+before_commands:
+    - "composer install --no-dev --prefer-source"
+
+tools:
+    external_code_coverage:
+        enabled: false
+        timeout: 300
+        filter:
+            excluded_paths: ["tests", "vendor"]
+    php_code_coverage:
+        enabled: false
+        test_command: phpunit -c phpunit.xml.dist
+    php_code_sniffer:
+        enabled: true
+        config:
+            standard: PSR2
+        filter:
+            paths: ["src/*", "tests/*"]
+    php_cpd:
+        enabled: true
+        excluded_dirs: ["tests", "vendor"]
+    php_cs_fixer:
+        enabled: true
+        config:
+            level: all
+        filter:
+            paths: ["src/*", "tests/*"]
+    php_loc:
+        enabled: true
+        excluded_dirs: ["tests", "vendor"]
+    php_mess_detector:
+        enabled: true
+        config:
+            ruleset: phpmd.xml.dist
+            design_rules: { eval_expression: false }
+        filter:
+            paths: ["src/*"]
+    php_pdepend:
+        enabled: true
+        excluded_dirs: ["tests", "vendor"]
+    php_analyzer:
+        enabled: true
+        filter:
+            paths: ["src/*", "tests/*"]
+    sensiolabs_security_checker: true

.travis.yml

@@ -3,17 +3,27 @@ php:
   - 5.3.3
   - 5.3
   - 5.4
+  - 5.5
+  - 5.6
+  - 7.0
+  - hhvm
+  - hhvm-nightly
+
+matrix:
+    allow_failures:
+        - php: hhvm
+        - php: hhvm-nightly
 
 script:
- - vendor/phpunit/phpunit/composer/bin/phpunit
+ - vendor/bin/phpunit
 
 before_script:
  - sudo apt-get -qq update > /dev/null
  - phpenv rehash > /dev/null
  - composer selfupdate --quiet
- - composer install --dev 
- - vendor/phpunit/phpunit/composer/bin/phpunit
- - composer update --dev 
+ - composer install --no-interaction --prefer-source --dev
+ - vendor/bin/phpunit
+ - composer update --no-interaction --prefer-source --dev
 
 notifications:
   irc: "irc.freenode.org#phpdocumentor"

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2010 Mike van Riel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

composer.json

@@ -6,13 +6,21 @@
         {"name": "Mike van Riel", "email": "[email protected]"}
     ],
     "require": {
-        "php": ">=5.3.3",
-        "dflydev/markdown": "1.0.*"
+        "php": ">=5.3.3"
     },
     "autoload": {
         "psr-0": {"phpDocumentor": ["src/"]}
     },
     "require-dev": {
-        "phpunit/phpunit": "3.7.*@stable"
+        "phpunit/phpunit": "~4.0"
+    },
+    "suggest": {
+        "erusev/parsedown": "~1.0",
+        "league/commonmark": "*"
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-master": "2.0.x-dev"
+        }
     }
 }

composer.lock

@@ -1,475 +0,0 @@
-{
-    "hash": "c6115c20a4a284f6ca14e676e788b4d3",
-    "packages": [
-        {
-            "name": "dflydev/markdown",
-            "version": "v1.0.2",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/dflydev/dflydev-markdown.git",
-                "reference": "v1.0.2"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/dflydev/dflydev-markdown/zipball/v1.0.2",
-                "reference": "v1.0.2",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3"
-            },
-            "time": "2012-01-15 19:36:37",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "psr-0": {
-                    "dflydev\\markdown": "src"
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "New BSD License"
-            ],
-            "authors": [
-                {
-                    "name": "Dragonfly Development Inc.",
-                    "email": "[email protected]",
-                    "homepage": "http://dflydev.com"
-                },
-                {
-                    "name": "Beau Simensen",
-                    "email": "[email protected]",
-                    "homepage": "http://beausimensen.com"
-                },
-                {
-                    "name": "Michel Fortin",
-                    "homepage": "http://michelf.com"
-                },
-                {
-                    "name": "John Gruber",
-                    "homepage": "http://daringfireball.net"
-                }
-            ],
-            "description": "PHP Markdown & Extra",
-            "homepage": "http://github.com/dflydev/dflydev-markdown",
-            "keywords": [
-                "markdown"
-            ]
-        }
-    ],
-    "packages-dev": [
-        {
-            "name": "phpunit/php-code-coverage",
-            "version": "1.2.7",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/php-code-coverage.git",
-                "reference": "1.2.7"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/php-code-coverage/archive/1.2.7.zip",
-                "reference": "1.2.7",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3",
-                "phpunit/php-file-iterator": ">=1.3.0@stable",
-                "phpunit/php-token-stream": ">=1.1.3@stable",
-                "phpunit/php-text-template": ">=1.1.1@stable"
-            },
-            "suggest": {
-                "ext-dom": "*",
-                "ext-xdebug": ">=2.0.5"
-            },
-            "time": "2012-12-02 14:54:55",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "PHP/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                ""
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "Library that provides collection, processing, and rendering functionality for PHP code coverage information.",
-            "homepage": "https://github.com/sebastianbergmann/php-code-coverage",
-            "keywords": [
-                "testing",
-                "coverage",
-                "xunit"
-            ]
-        },
-        {
-            "name": "phpunit/php-file-iterator",
-            "version": "1.3.3",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/php-file-iterator.git",
-                "reference": "1.3.3"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/php-file-iterator/zipball/1.3.3",
-                "reference": "1.3.3",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3"
-            },
-            "time": "2012-10-11 04:44:38",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "File/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                ""
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "FilterIterator implementation that filters files based on a list of suffixes.",
-            "homepage": "http://www.phpunit.de/",
-            "keywords": [
-                "filesystem",
-                "iterator"
-            ]
-        },
-        {
-            "name": "phpunit/php-text-template",
-            "version": "1.1.4",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/php-text-template.git",
-                "reference": "1.1.4"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/php-text-template/zipball/1.1.4",
-                "reference": "1.1.4",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3"
-            },
-            "time": "2012-10-31 11:15:28",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "Text/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                ""
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "Simple template engine.",
-            "homepage": "https://github.com/sebastianbergmann/php-text-template/",
-            "keywords": [
-                "template"
-            ]
-        },
-        {
-            "name": "phpunit/php-timer",
-            "version": "1.0.4",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/php-timer.git",
-                "reference": "1.0.4"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/php-timer/zipball/1.0.4",
-                "reference": "1.0.4",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3"
-            },
-            "time": "2012-10-11 04:45:58",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "PHP/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                ""
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "Utility class for timing",
-            "homepage": "http://www.phpunit.de/",
-            "keywords": [
-                "timer"
-            ]
-        },
-        {
-            "name": "phpunit/php-token-stream",
-            "version": "1.1.5",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/php-token-stream.git",
-                "reference": "1.1.5"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/php-token-stream/zipball/1.1.5",
-                "reference": "1.1.5",
-                "shasum": ""
-            },
-            "require": {
-                "ext-tokenizer": "*",
-                "php": ">=5.3.3"
-            },
-            "time": "2012-10-11 04:47:14",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "PHP/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                ""
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "Wrapper around PHP's tokenizer extension.",
-            "homepage": "http://www.phpunit.de/",
-            "keywords": [
-                "tokenizer"
-            ]
-        },
-        {
-            "name": "phpunit/phpunit",
-            "version": "3.7.10",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/phpunit.git",
-                "reference": "3.7.10"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/phpunit/archive/3.7.10.zip",
-                "reference": "3.7.10",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3",
-                "phpunit/php-file-iterator": ">=1.3.1",
-                "phpunit/php-text-template": ">=1.1.1",
-                "phpunit/php-code-coverage": ">=1.2.1",
-                "phpunit/php-timer": ">=1.0.2",
-                "phpunit/phpunit-mock-objects": ">=1.2.0,<1.3.0",
-                "symfony/yaml": ">=2.1.0",
-                "ext-dom": "*",
-                "ext-pcre": "*",
-                "ext-reflection": "*",
-                "ext-spl": "*"
-            },
-            "suggest": {
-                "phpunit/php-invoker": ">=1.1.0",
-                "ext-json": "*",
-                "ext-simplexml": "*",
-                "ext-tokenizer": "*"
-            },
-            "time": "2012-12-02 14:56:55",
-            "bin": [
-                "composer/bin/phpunit"
-            ],
-            "type": "library",
-            "extra": {
-                "branch-alias": {
-                    "dev-master": "3.7.x-dev"
-                }
-            },
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "PHPUnit/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                "",
-                "../../symfony/yaml/"
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "The PHP Unit Testing framework.",
-            "homepage": "http://www.phpunit.de/",
-            "keywords": [
-                "testing",
-                "phpunit",
-                "xunit"
-            ]
-        },
-        {
-            "name": "phpunit/phpunit-mock-objects",
-            "version": "1.2.2",
-            "source": {
-                "type": "git",
-                "url": "git://github.com/sebastianbergmann/phpunit-mock-objects.git",
-                "reference": "1.2.2"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/sebastianbergmann/phpunit-mock-objects/archive/1.2.2.zip",
-                "reference": "1.2.2",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3",
-                "phpunit/php-text-template": ">=1.1.1@stable"
-            },
-            "suggest": {
-                "ext-soap": "*"
-            },
-            "time": "2012-11-05 10:39:13",
-            "type": "library",
-            "installation-source": "dist",
-            "autoload": {
-                "classmap": [
-                    "PHPUnit/"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "include-path": [
-                ""
-            ],
-            "license": [
-                "BSD-3-Clause"
-            ],
-            "authors": [
-                {
-                    "name": "Sebastian Bergmann",
-                    "email": "[email protected]",
-                    "role": "lead"
-                }
-            ],
-            "description": "Mock Object library for PHPUnit",
-            "homepage": "https://github.com/sebastianbergmann/phpunit-mock-objects/",
-            "keywords": [
-                "mock",
-                "xunit"
-            ]
-        },
-        {
-            "name": "symfony/yaml",
-            "version": "v2.1.4",
-            "target-dir": "Symfony/Component/Yaml",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/symfony/Yaml",
-                "reference": "v2.1.4"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://github.com/symfony/Yaml/archive/v2.1.4.zip",
-                "reference": "v2.1.4",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.3.3"
-            },
-            "time": "2012-11-08 09:51:48",
-            "type": "library",
-            "extra": {
-                "branch-alias": {
-                    "dev-master": "2.1-dev"
-                }
-            },
-            "installation-source": "dist",
-            "autoload": {
-                "psr-0": {
-                    "Symfony\\Component\\Yaml": ""
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Fabien Potencier",
-                    "email": "[email protected]"
-                },
-                {
-                    "name": "Symfony Community",
-                    "homepage": "http://symfony.com/contributors"
-                }
-            ],
-            "description": "Symfony Yaml Component",
-            "homepage": "http://symfony.com"
-        }
-    ],
-    "aliases": [
-
-    ],
-    "minimum-stability": "stable",
-    "stability-flags": {
-        "phpunit/phpunit": 0
-    }
-}

phpmd.xml.dist

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<ruleset
+    name="ProxyManager rules"
+    xmlns="http://pmd.sf.net/ruleset/1.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
+    xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd"
+>
+    <rule ref="rulesets/codesize.xml"/>
+    <rule ref="rulesets/unusedcode.xml"/>
+    <rule ref="rulesets/design.xml">
+        <!-- eval is needed to generate runtime classes -->
+        <exclude name="EvalExpression"/>
+    </rule>
+    <rule ref="rulesets/naming.xml">
+        <exclude name="LongVariable"/>
+    </rule>
+    <rule ref="rulesets/naming.xml/LongVariable">
+        <properties>
+            <property name="minimum">40</property>
+        </properties>
+    </rule>
+</ruleset>

src/phpDocumentor/Reflection/DocBlock.php

@@ -46,22 +46,25 @@ class DocBlock implements \Reflector
     /** @var Location Information about the location of this DocBlock. */
     protected $location = null;
 
+    /** @var bool Is this DocBlock (the start of) a template? */
+    protected $isTemplateStart = false;
+
+    /** @var bool Does this DocBlock signify the end of a DocBlock template? */
+    protected $isTemplateEnd = false;
+
     /**
      * Parses the given docblock and populates the member fields.
      *
      * The constructor may also receive namespace information such as the
      * current namespace and aliases. This information is used by some tags
-     * (e.g. @return, @param, etc.) to turn a relative Type into a FQCN.
+     * (e.g. return, param, etc.) to turn a relative Type into a FQCN.
      *
-     * @param \Reflector|string $docblock A docblock comment (including
-     *     asterisks) or reflector supporting the getDocComment method.
-     * @param Context           $context  The context in which the DocBlock
-     *     occurs.
-     * @param Location          $location The location within the file that this
-     *     DocBlock occurs in.
-     *
-     * @throws \InvalidArgumentException if the given argument does not have the
+     * @param \Reflector|string $docblock A docblock comment (including asterisks) or reflector supporting the
      *     getDocComment method.
+     * @param Context           $context  The context in which the DocBlock occurs.
+     * @param Location          $location The location within the file that this DocBlock occurs in.
+     *
+     * @throws \InvalidArgumentException if the given argument does not have the getDocComment method.
      */
     public function __construct(
         $docblock,
@@ -71,8 +74,7 @@ class DocBlock implements \Reflector
         if (is_object($docblock)) {
             if (!method_exists($docblock, 'getDocComment')) {
                 throw new \InvalidArgumentException(
-                    'Invalid object passed; the given reflector must support '
-                    . 'the getDocComment method'
+                    'Invalid object passed; the given reflector must support the getDocComment method'
                 );
             }
 
@@ -81,7 +83,9 @@ class DocBlock implements \Reflector
 
         $docblock = $this->cleanInput($docblock);
 
-        list($short, $long, $tags) = $this->splitDocBlock($docblock);
+        list($templateMarker, $short, $long, $tags) = $this->splitDocBlock($docblock);
+        $this->isTemplateStart = $templateMarker === '#@+';
+        $this->isTemplateEnd = $templateMarker === '#@-';
         $this->short_description = $short;
         $this->long_description = new DocBlock\Description($long, $this);
         $this->parseTags($tags);
@@ -119,74 +123,86 @@ class DocBlock implements \Reflector
     }
 
     /**
-     * Splits the DocBlock into a short description, long description and
-     * block of tags.
+     * Splits the DocBlock into a template marker, summary, description and block of tags.
      *
      * @param string $comment Comment to split into the sub-parts.
      *
-     * @author RichardJ Special thanks to RichardJ for the regex responsible
-     *     for the split.
+     * @author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split.
+     * @author Mike van Riel <[email protected]> for extending the regex with template marker support.
      *
-     * @return string[] containing the short-, long description and an element
-     *     containing the tags.
+     * @return string[] containing the template marker (if any), summary, description and a string containing the tags.
      */
     protected function splitDocBlock($comment)
     {
+        // Performance improvement cheat: if the first character is an @ then only tags are in this DocBlock. This
+        // method does not split tags so we return this verbatim as the fourth result (tags). This saves us the
+        // performance impact of running a regular expression
         if (strpos($comment, '@') === 0) {
-            $matches = array('', '', $comment);
-        } else {
-            // clears all extra horizontal whitespace from the line endings
-            // to prevent parsing issues
-            $comment = preg_replace('/\h*$/Sum', '', $comment);
-
-            /*
-             * Splits the docblock into a short description, long description and
-             * tags section
-             * - The short description is started from the first character until
-             *   a dot is encountered followed by a whitespace OR
-             *   two consecutive newlines (horizontal whitespace is taken into
-             *   account to consider spacing errors)
-             * - The long description, any character until a new line is
-             *   encountered followed by an @ and word characters (a tag).
-             *   This is optional.
-             * - Tags; the remaining characters
-             *
-             * Big thanks to RichardJ for contributing this Regular Expression
-             */
-            preg_match(
-                '/
-        \A (
-          [^\n.]+
-          (?:
-            (?! \. \s | \n{2} ) # disallow the first seperator here
-            [\n.] (?! [ \t]* @\pL ) # disallow second seperator
-            [^\n.]+
-          )*
-          \.?
-        )
-        (?:
-          \s* # first seperator (actually newlines but it\'s all whitespace)
-          (?! @\pL ) # disallow the rest, to make sure this one doesn\'t match,
-          #if it doesn\'t exist
-          (
-            [^\n]+
-            (?: \n+
-              (?! [ \t]* @\pL ) # disallow second seperator (@param)
-              [^\n]+
-            )*
-          )
-        )?
-        (\s+ [\s\S]*)? # everything that follows
-        /ux',
-                $comment,
-                $matches
-            );
-            array_shift($matches);
+            return array('', '', '', $comment);
         }
 
-        while (count($matches) < 3) {
+        // clears all extra horizontal whitespace from the line endings to prevent parsing issues
+        $comment = preg_replace('/\h*$/Sum', '', $comment);
+
+        /*
+         * Splits the docblock into a template marker, short description, long description and tags section
+         *
+         * - The template marker is empty, #@+ or #@- if the DocBlock starts with either of those (a newline may
+         *   occur after it and will be stripped).
+         * - The short description is started from the first character until a dot is encountered followed by a
+         *   newline OR two consecutive newlines (horizontal whitespace is taken into account to consider spacing
+         *   errors). This is optional.
+         * - The long description, any character until a new line is encountered followed by an @ and word
+         *   characters (a tag). This is optional.
+         * - Tags; the remaining characters
+         *
+         * Big thanks to RichardJ for contributing this Regular Expression
+         */
+        preg_match(
+            '/
+            \A
+            # 1. Extract the template marker
+            (?:(\#\@\+|\#\@\-)\n?)?
+
+            # 2. Extract the summary
+            (?:
+              (?! @\pL ) # The summary may not start with an @
+              (
+                [^\n.]+
+                (?:
+                  (?! \. \n | \n{2} )     # End summary upon a dot followed by newline or two newlines
+                  [\n.] (?! [ \t]* @\pL ) # End summary when an @ is found as first character on a new line
+                  [^\n.]+                 # Include anything else
+                )*
+                \.?
+              )?
+            )
+
+            # 3. Extract the description
+            (?:
+              \s*        # Some form of whitespace _must_ precede a description because a summary must be there
+              (?! @\pL ) # The description may not start with an @
+              (
+                [^\n]+
+                (?: \n+
+                  (?! [ \t]* @\pL ) # End description when an @ is found as first character on a new line
+                  [^\n]+            # Include anything else
+                )*
+              )
+            )?
+
+            # 4. Extract the tags (anything that follows)
+            (\s+ [\s\S]*)? # everything that follows
+            /ux',
+            $comment,
+            $matches
+        );
+        array_shift($matches);
+
+        while (count($matches) < 4) {
             $matches[] = '';
         }
+
         return $matches;
     }
 
@@ -209,26 +225,58 @@ class DocBlock implements \Reflector
                 );
             }
             foreach (explode("\n", $tags) as $tag_line) {
-                if (trim($tag_line) === '') {
-                    continue;
-                }
-
                 if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
                     $result[] = $tag_line;
                 } else {
-                    $result[count($result) - 1] .= PHP_EOL . $tag_line;
+                    $result[count($result) - 1] .= "\n" . $tag_line;
                 }
             }
 
             // create proper Tag objects
             foreach ($result as $key => $tag_line) {
-                $result[$key] = Tag::createInstance($tag_line, $this);
+                $result[$key] = Tag::createInstance(trim($tag_line), $this);
             }
         }
 
         $this->tags = $result;
     }
 
+    /**
+     * Gets the text portion of the doc block.
+     * 
+     * Gets the text portion (short and long description combined) of the doc
+     * block.
+     * 
+     * @return string The text portion of the doc block.
+     */
+    public function getText()
+    {
+        $short = $this->getShortDescription();
+        $long = $this->getLongDescription()->getContents();
+
+        if ($long) {
+            return "{$short}\n\n{$long}";
+        } else {
+            return $short;
+        }
+    }
+
+    /**
+     * Set the text portion of the DocBlock.
+     * 
+     * Sets the text portion (short and long description combined) of the DocBlock.
+     *
+     * @param string $comment The new text portion of the DocBlock.
+     * 
+     * @return $this
+     */
+    public function setText($comment)
+    {
+        list(,$short, $long) = $this->splitDocBlock($comment);
+        $this->short_description = $short;
+        $this->long_description = new DocBlock\Description($long, $this);
+        return $this;
+    }
     /**
      * Returns the opening line or also known as short description.
      *
@@ -249,6 +297,44 @@ class DocBlock implements \Reflector
         return $this->long_description;
     }
 
+    /**
+     * Returns whether this DocBlock is the start of a Template section.
+     *
+     * A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker
+     * (`#@+`) that is appended directly after the opening `/**` of a DocBlock.
+     *
+     * An example of such an opening is:
+     *
+     * ```
+     * /**#@+
+     *  * My DocBlock
+     *  * /
+     * ```
+     *
+     * The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all
+     * elements that follow until another DocBlock is found that contains the closing marker (`#@-`).
+     *
+     * @see self::isTemplateEnd() for the check whether a closing marker was provided.
+     *
+     * @return boolean
+     */
+    public function isTemplateStart()
+    {
+        return $this->isTemplateStart;
+    }
+
+    /**
+     * Returns whether this DocBlock is the end of a Template section.
+     *
+     * @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
+     *
+     * @return boolean
+     */
+    public function isTemplateEnd()
+    {
+        return $this->isTemplateEnd;
+    }
+
     /**
      * Returns the current context.
      *
@@ -348,6 +434,7 @@ class DocBlock implements \Reflector
         return $tag;
     }
 
+
     /**
      * Builds a string representation of this object.
      *

src/phpDocumentor/Reflection/DocBlock/Context.php

@@ -1,11 +1,11 @@
 <?php
 /**
- * phpDocumentor
+ * This file is part of phpDocumentor.
  *
- * PHP Version 5.3
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
  *
- * @author    Vasil Rangelov <[email protected]>
- * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
+ * @copyright 2010-2015 Mike van Riel<[email protected]>
  * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
@@ -13,46 +13,49 @@
 namespace phpDocumentor\Reflection\DocBlock;
 
 /**
- * The context in which a DocBlock occurs.
+ * Provides information about the Context in which the DocBlock occurs that receives this context.
  *
- * @author  Vasil Rangelov <[email protected]>
- * @license http://www.opensource.org/licenses/mit-license.php MIT
- * @link    http://phpdoc.org
+ * A DocBlock does not know of its own accord in which namespace it occurs and which namespace aliases are applicable
+ * for the block of code in which it is in. This information is however necessary to resolve Class names in tags since
+ * you can provide a short form or make use of namespace aliases.
+ *
+ * The phpDocumentor Reflection component knows how to create this class but if you use the DocBlock parser from your
+ * own application it is possible to generate a Context class using the ContextFactory; this will analyze the file in
+ * which an associated class resides for its namespace and imports.
+ *
+ * @see ContextFactory::createFromClassReflector()
+ * @see ContextFactory::createForNamespace()
  */
-class Context
+final class Context
 {
     /** @var string The current namespace. */
-    protected $namespace = '';
+    private $namespace = '';
 
     /** @var array List of namespace aliases => Fully Qualified Namespace. */
-    protected $namespace_aliases = array();
-    
-    /** @var string Name of the structural element, within the namespace. */
-    protected $lsen = '';
+    private $namespaceAliases = [];
 
     /**
-     * Cteates a new context.
-     * @param string $namespace         The namespace where this DocBlock
-     *     resides in.
-     * @param array  $namespace_aliases List of namespace aliases => Fully
-     *     Qualified Namespace.
-     * @param string $lsen              Name of the structural element, within
-     *     the namespace.
+     * Initializes the new context and normalizes all passed namespaces to be in Qualified Namespace Name (QNN)
+     * format (without a preceding `\`).
+     *
+     * @param string $namespace The namespace where this DocBlock resides in.
+     * @param array $namespaceAliases List of namespace aliases => Fully Qualified Namespace.
      */
-    public function __construct(
-        $namespace = '',
-        array $namespace_aliases = array(),
-        $lsen = ''
-    ) {
-        if (!empty($namespace)) {
-            $this->setNamespace($namespace);
+    public function __construct($namespace, array $namespaceAliases = [])
+    {
+        $this->namespace = ('global' !== $namespace && 'default' !== $namespace)
+            ? trim((string)$namespace, '\\')
+            : '';
+
+        foreach ($namespaceAliases as $alias => $fqnn) {
+            $this->namespaceAliases[$alias] = trim((string)$fqnn, '\\');
         }
-        $this->setNamespaceAliases($namespace_aliases);
-        $this->setLSEN($lsen);
     }
 
     /**
-     * @return string The namespace where this DocBlock resides in.
+     * Returns the Qualified Namespace Name (thus without `\` in front) where the associated element is in.
+     *
+     * @return string
      */
     public function getNamespace()
     {
@@ -60,95 +63,13 @@ class Context
     }
 
     /**
-     * @return array List of namespace aliases => Fully Qualified Namespace.
+     * Returns a list of Qualified Namespace Names (thus without `\` in front) that are imported, the keys represent
+     * the alias for the imported Namespace.
+     *
+     * @return string[]
      */
     public function getNamespaceAliases()
     {
-        return $this->namespace_aliases;
-    }
-    
-    /**
-     * Returns the Local Structural Element Name.
-     * 
-     * @return string Name of the structural element, within the namespace.
-     */
-    public function getLSEN()
-    {
-        return $this->lsen;
-    }
-    
-    /**
-     * Sets a new namespace.
-     * 
-     * Sets a new namespace for the context. Leading and trailing slashes are
-     * trimmed, and the keywords "global" and "default" are treated as aliases
-     * to no namespace.
-     * 
-     * @param string $namespace The new namespace to set.
-     * 
-     * @return $this
-     */
-    public function setNamespace($namespace)
-    {
-        if ('global' !== $namespace
-            && 'default' !== $namespace
-        ) {
-            // Srip leading and trailing slash
-            $this->namespace = trim((string)$namespace, '\\');
-        } else {
-            $this->namespace = '';
-        }
-        return $this;
-    }
-    
-    /**
-     * Sets the namespace aliases, replacing all previous ones.
-     * 
-     * @param array $namespace_aliases List of namespace aliases => Fully
-     *     Qualified Namespace.
-     * 
-     * @return $this
-     */
-    public function setNamespaceAliases(array $namespace_aliases)
-    {
-        $this->namespace_aliases = array();
-        foreach ($namespace_aliases as $alias => $fqnn) {
-            $this->setNamespaceAlias($alias, $fqnn);
-        }
-        return $this;
-    }
-    
-    /**
-     * Adds a namespace alias to the context.
-     * 
-     * @param string $alias The alias name (the part after "as", or the last
-     *     part of the Fully Qualified Namespace Name) to add.
-     * @param string $fqnn  The Fully Qualified Namespace Name for this alias.
-     *     Any form of leading/trailing slashes are accepted, but what will be
-     *     stored is a name, prefixed with a slash, and no trailing slash.
-     * 
-     * @return $this
-     */
-    public function setNamespaceAlias($alias, $fqnn)
-    {
-        $this->namespace_aliases[$alias] = '\\' . trim((string)$fqnn, '\\');
-        return $this;
-    }
-    
-    /**
-     * Sets a new Local Structural Element Name.
-     * 
-     * Sets a new Local Structural Element Name. A local name also contains
-     * punctuation determining the kind of structural element (e.g. trailing "("
-     * and ")" for functions and methods).
-     * 
-     * @param string $lsen The new local name of a structural element.
-     * 
-     * @return $this
-     */
-    public function setLSEN($lsen)
-    {
-        $this->lsen = (string)$lsen;
-        return $this;
+        return $this->namespaceAliases;
     }
 }

src/phpDocumentor/Reflection/DocBlock/ContextFactory.php

@@ -0,0 +1,174 @@
+<?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;
+
+/**
+ * Convenience class to create a Context for DocBlocks when not using the Reflection Component of phpDocumentor.
+ *
+ * For a DocBlock to be able to resolve types that use partial namespace names or rely on namespace imports we need to
+ * provide a bit of context so that the DocBlock can read that and based on it decide how to resolve the types to
+ * Fully Qualified names.
+ *
+ * @see Context for more information.
+ */
+final class ContextFactory
+{
+    /** The literal used at the end of a use statement. */
+    const T_LITERAL_END_OF_USE = ';';
+
+    /** The literal used between sets of use statements */
+    const T_LITERAL_USE_SEPARATOR = ',';
+
+    /**
+     * Build a Context given a Class Reflection.
+     *
+     * @param \ReflectionClass $class
+     *
+     * @see Context for more information on Contexts.
+     *
+     * @return Context
+     */
+    public function createFromClassReflector(\ReflectionClass $class)
+    {
+        return $this->createForNamespace(
+            $class->getNamespaceName(),
+            file_get_contents($class->getFileName())
+        );
+    }
+
+    /**
+     * Build a Context for a namespace in the provided file contents.
+     *
+     * @param string $namespace It does not matter if a `\` precedes the namespace name, this method first normalizes.
+     * @param string $fileContents the file's contents to retrieve the aliases from with the given namespace.
+     *
+     * @see Context for more information on Contexts.
+     *
+     * @return Context
+     */
+    public function createForNamespace($namespace, $fileContents)
+    {
+        $namespace = trim($namespace, '\\');
+        $useStatements = [];
+        $currentNamespace = '';
+        $tokens = new \ArrayIterator(token_get_all($fileContents));
+
+        while ($tokens->valid()) {
+            switch ($tokens->current()[0]) {
+                case T_NAMESPACE:
+                    $currentNamespace = $this->parseNamespace($tokens);
+                    break;
+                case T_USE:
+                    if ($currentNamespace === $namespace) {
+                        $useStatements = array_merge($useStatements, $this->parseUseStatement($tokens));
+                    }
+                    break;
+            }
+            $tokens->next();
+        }
+
+        return new Context($namespace, $useStatements);
+    }
+
+    /**
+     * Deduce the name from tokens when we are at the T_NAMESPACE token.
+     *
+     * @param \ArrayIterator $tokens
+     *
+     * @return string
+     */
+    private function parseNamespace(\ArrayIterator $tokens)
+    {
+        // skip to the first string or namespace separator
+        $this->skipToNextStringOrNamespaceSeparator($tokens);
+
+        $name = '';
+        while ($tokens->valid() && ($tokens->current()[0] === T_STRING || $tokens->current()[0] === T_NS_SEPARATOR)
+        ) {
+            $name .= $tokens->current()[1];
+            $tokens->next();
+        }
+
+        return $name;
+    }
+
+    /**
+     * Deduce the names of all imports when we are at the T_USE token.
+     *
+     * @param \ArrayIterator $tokens
+     *
+     * @return string[]
+     */
+    private function parseUseStatement(\ArrayIterator $tokens)
+    {
+        $uses = [];
+        $continue = true;
+
+        while ($continue) {
+            $this->skipToNextStringOrNamespaceSeparator($tokens);
+
+            list($alias, $fqnn) = $this->extractUseStatement($tokens);
+            $uses[$alias] = $fqnn;
+            if ($tokens->current()[0] === self::T_LITERAL_END_OF_USE) {
+                $continue = false;
+            }
+        }
+
+        return $uses;
+    }
+
+    /**
+     * Fast-forwards the iterator as longs as we don't encounter a T_STRING or T_NS_SEPARATOR token.
+     *
+     * @param \ArrayIterator $tokens
+     *
+     * @return void
+     */
+    private function skipToNextStringOrNamespaceSeparator(\ArrayIterator $tokens)
+    {
+        while ($tokens->valid() && ($tokens->current()[0] !== T_STRING) && ($tokens->current()[0] !== T_NS_SEPARATOR)) {
+            $tokens->next();
+        }
+    }
+
+    /**
+     * Deduce the namespace name and alias of an import when we are at the T_USE token or have not reached the end of
+     * a USE statement yet.
+     *
+     * @param \ArrayIterator $tokens
+     *
+     * @return string
+     */
+    private function extractUseStatement(\ArrayIterator $tokens)
+    {
+        $result = [''];
+        while ($tokens->valid()
+            && ($tokens->current()[0] !== self::T_LITERAL_USE_SEPARATOR)
+            && ($tokens->current()[0] !== self::T_LITERAL_END_OF_USE)
+        ) {
+            if ($tokens->current()[0] === T_AS) {
+                $result[] = '';
+            }
+            if ($tokens->current()[0] === T_STRING || $tokens->current()[0] === T_NS_SEPARATOR) {
+                $result[count($result) - 1] .= $tokens->current()[1];
+            }
+            $tokens->next();
+        }
+
+        if (count($result) == 1) {
+            $result[] = substr($result[0], strrpos($result[0], '\\') + 1);
+        }
+
+        return array_reverse($result);
+    }
+}

src/phpDocumentor/Reflection/DocBlock/Description.php

@@ -26,7 +26,7 @@ class Description implements \Reflector
     /** @var string */
     protected $contents = '';
 
-    /** @var array The contents, as an array of strings and Tag objects. */
+    /** @var array|null The contents, as an array of strings and Tag objects or null if it is not parsed yet. */
     protected $parsedContents = null;
 
     /** @var DocBlock The DocBlock which this description belongs to. */
@@ -35,7 +35,7 @@ class Description implements \Reflector
     /**
      * Populates the fields of a description.
      *
-     * @param string   $content  The description's conetnts.
+     * @param string   $content  The description's content.
      * @param DocBlock $docblock The DocBlock which this description belongs to.
      */
     public function __construct($content, DocBlock $docblock = null)
@@ -161,9 +161,15 @@ class Description implements \Reflector
             );
         }
 
-        if (class_exists('dflydev\markdown\MarkdownExtraParser')) {
+        if (class_exists('Parsedown')) {
+            $markdown = \Parsedown::instance();
+            $result = $markdown->parse($result);
+        } elseif (class_exists('dflydev\markdown\MarkdownExtraParser')) {
             $markdown = new \dflydev\markdown\MarkdownExtraParser();
             $result = $markdown->transformMarkdown($result);
+        } elseif (class_exists('League\CommonMark\CommonMarkConverter')) {
+            $markdown = new \League\CommonMark\CommonMarkConverter();
+            $result = $markdown->convertToHtml($result);
         }
 
         return trim($result);
@@ -209,14 +215,12 @@ class Description implements \Reflector
     }
 
     /**
-     * Returns the exported information (we should use the export static method
-     * BUT this throws an exception at this point).
+     * Returns the long description as a string.
      *
      * @return string
-     * @codeCoverageIgnore Not yet implemented
      */
     public function __toString()
     {
-        return 'Not yet implemented';
+        return $this->getContents();
     }
 }

src/phpDocumentor/Reflection/DocBlock/Location.php

@@ -27,15 +27,15 @@ class Location
     /** @var int Column where the DocBlock text starts. */
     protected $columnNumber = 0;
     
-    public function __construct(
-        $lineNumber = 0,
-        $columnNumber = 0
-    ) {
+    public function __construct($lineNumber = 0, $columnNumber = 0)
+    {
         $this->setLineNumber($lineNumber)->setColumnNumber($columnNumber);
     }
 
     /**
-     * @return int Line where the DocBlock text starts.
+     * Returns the line number that is covered by this location.
+     *
+     * @return integer
      */
     public function getLineNumber()
     {
@@ -43,8 +43,10 @@ class Location
     }
 
     /**
+     * Registers which line number is covered by this location object.
+     *
+     * @param integer $lineNumber
      *
-     * @param type $lineNumber
      * @return $this
      */
     public function setLineNumber($lineNumber)
@@ -55,7 +57,9 @@ class Location
     }
 
     /**
-     * @return int Column where the DocBlock text starts.
+     * Returns the column number (character position on a line) for this location object.
+     *
+     * @return integer
      */
     public function getColumnNumber()
     {
@@ -63,8 +67,10 @@ class Location
     }
 
     /**
+     * Registers the column number (character position on a line) for this location object.
+     *
+     * @param integer $columnNumber
      *
-     * @param int $columnNumber
      * @return $this
      */
     public function setColumnNumber($columnNumber)

src/phpDocumentor/Reflection/DocBlock/Serializer.php

@@ -0,0 +1,199 @@
+<?php
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5.3
+ *
+ * @author    Barry vd. Heuvel <[email protected]>
+ * @copyright 2013 Mike van Riel / Naenius (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock;
+
+use phpDocumentor\Reflection\DocBlock;
+
+/**
+ * Serializes a DocBlock instance.
+ *
+ * @author  Barry vd. Heuvel <[email protected]>
+ * @license http://www.opensource.org/licenses/mit-license.php MIT
+ * @link    http://phpdoc.org
+ */
+class Serializer
+{
+    /** @var string The string to indent the comment with. */
+    protected $indentString = ' ';
+
+    /** @var int The number of times the indent string is repeated. */
+    protected $indent = 0;
+
+    /** @var bool Whether to indent the first line. */
+    protected $isFirstLineIndented = true;
+
+    /** @var int|null The max length of a line. */
+    protected $lineLength = null;
+
+    /**
+     * Create a Serializer instance.
+     *
+     * @param int      $indent          The number of times the indent string is
+     *     repeated.
+     * @param string   $indentString    The string to indent the comment with.
+     * @param bool     $indentFirstLine Whether to indent the first line.
+     * @param int|null $lineLength      The max length of a line or NULL to
+     *     disable line wrapping.
+     */
+    public function __construct(
+        $indent = 0,
+        $indentString = ' ',
+        $indentFirstLine = true,
+        $lineLength = null
+    ) {
+        $this->setIndentationString($indentString);
+        $this->setIndent($indent);
+        $this->setIsFirstLineIndented($indentFirstLine);
+        $this->setLineLength($lineLength);
+    }
+
+    /**
+     * Sets the string to indent comments with.
+     * 
+     * @param string $indentString The string to indent comments with.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setIndentationString($indentString)
+    {
+        $this->indentString = (string)$indentString;
+
+        return $this;
+    }
+
+    /**
+     * Gets the string to indent comments with.
+     * 
+     * @return string The indent string.
+     */
+    public function getIndentationString()
+    {
+        return $this->indentString;
+    }
+
+    /**
+     * Sets the number of indents.
+     * 
+     * @param int $indent The number of times the indent string is repeated.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setIndent($indent)
+    {
+        $this->indent = (int)$indent;
+        return $this;
+    }
+
+    /**
+     * Gets the number of indents.
+     * 
+     * @return int The number of times the indent string is repeated.
+     */
+    public function getIndent()
+    {
+        return $this->indent;
+    }
+
+    /**
+     * Sets whether or not the first line should be indented.
+     * 
+     * Sets whether or not the first line (the one with the "/**") should be
+     * indented.
+     * 
+     * @param bool $indentFirstLine The new value for this setting.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setIsFirstLineIndented($indentFirstLine)
+    {
+        $this->isFirstLineIndented = (bool)$indentFirstLine;
+        return $this;
+    }
+
+    /**
+     * Gets whether or not the first line should be indented.
+     * 
+     * @return bool Whether or not the first line should be indented.
+     */
+    public function isFirstLineIndented()
+    {
+        return $this->isFirstLineIndented;
+    }
+
+    /**
+     * Sets the line length.
+     * 
+     * Sets the length of each line in the serialization. Content will be
+     * wrapped within this limit.
+     * 
+     * @param int|null $lineLength The length of each line. NULL to disable line
+     *     wrapping altogether.
+     * 
+     * @return $this This serializer object.
+     */
+    public function setLineLength($lineLength)
+    {
+        $this->lineLength = null === $lineLength ? null : (int)$lineLength;
+        return $this;
+    }
+
+    /**
+     * Gets the line length.
+     * 
+     * @return int|null The length of each line or NULL if line wrapping is
+     *     disabled.
+     */
+    public function getLineLength()
+    {
+        return $this->lineLength;
+    }
+
+    /**
+     * Generate a DocBlock comment.
+     *
+     * @param DocBlock The DocBlock to serialize.
+     * 
+     * @return string The serialized doc block.
+     */
+    public function getDocComment(DocBlock $docblock)
+    {
+        $indent = str_repeat($this->indentString, $this->indent);
+        $firstIndent = $this->isFirstLineIndented ? $indent : '';
+
+        $wrapLength = 80;
+        $text = $docblock->getText();
+        if ($this->lineLength) {
+            //3 === strlen(' * ')
+            $wrapLength = $this->lineLength - strlen($indent) - 3;
+            $text = wordwrap($text, $wrapLength);
+        }
+        $text = str_replace("\n", "\n{$indent} * ", $text);
+
+        $comment = "{$firstIndent}/**\n{$indent} * {$text}\n{$indent} *\n";
+
+        /** @var Tag $tag */
+        foreach ($docblock->getTags() as $tag) {
+            $tagText = (string) $tag;
+            if ($this->lineLength) {
+                $tagText = wordwrap($tagText, $wrapLength);
+            }
+            $tagText = str_replace("\n", "\n{$indent} * ", $tagText);
+
+            $comment .= "{$indent} * {$tagText}\n";
+        }
+
+        $comment .= $indent . ' */';
+
+        return $comment;
+    }
+}

src/phpDocumentor/Reflection/DocBlock/Tag.php

@@ -114,15 +114,7 @@ class Tag implements \Reflector
         DocBlock $docblock = null,
         Location $location = null
     ) {
-        if (!preg_match(
-            '/^@(' . self::REGEX_TAGNAME . ')(?:\s*([^\s].*)|$)?/us',
-            $tag_line,
-            $matches
-        )) {
-            throw new \InvalidArgumentException(
-                'Invalid tag_line detected: ' . $tag_line
-            );
-        }
+        $matches = self::extractTagParts($tag_line);
 
         $handler = __CLASS__;
         if (isset(self::$tagHandlerMappings[$matches[1]])) {
@@ -217,16 +209,13 @@ class Tag implements \Reflector
      * 
      * @param string $name The new name of this tag.
      * 
-     * @return $this
      * @throws \InvalidArgumentException When an invalid tag name is provided.
+     *
+     * @return $this
      */
     public function setName($name)
     {
-        if (!preg_match('/^' . self::REGEX_TAGNAME . '$/u', $name)) {
-            throw new \InvalidArgumentException(
-                'Invalid tag name supplied: ' . $name
-            );
-        }
+        $this->validateTagName($name);
 
         $this->tag = $name;
 
@@ -366,14 +355,48 @@ class Tag implements \Reflector
     }
 
     /**
-     * Returns the exported information (we should use the export static method
-     * BUT this throws an exception at this point).
+     * Returns the tag as a serialized string
      *
      * @return string
-     * @codeCoverageIgnore Not yet implemented
      */
     public function __toString()
     {
-        return 'Not yet implemented';
+        return "@{$this->getName()} {$this->getContent()}";
+    }
+
+    /**
+     * Extracts all components for a tag.
+     *
+     * @param string $tagLine
+     *
+     * @return string[]
+     */
+    private static function extractTagParts($tagLine)
+    {
+        $matches = array();
+        if (! preg_match('/^@(' . self::REGEX_TAGNAME . ')(?:\s*([^\s].*)|$)?/us', $tagLine, $matches)) {
+            throw new \InvalidArgumentException(
+                'The tag "' . $tagLine . '" does not seem to be wellformed, please check it for errors'
+            );
+        }
+
+        return $matches;
+    }
+
+    /**
+     * Validates if the tag name matches the expected format, otherwise throws an exception.
+     *
+     * @param string $name
+     *
+     * @return void
+     */
+    private function validateTagName($name)
+    {
+        if (!preg_match('/^' . self::REGEX_TAGNAME . '$/u', $name)) {
+            throw new \InvalidArgumentException(
+                'The tag name "' . $name . '" is not wellformed. Tags may only consist of letters, underscores, '
+                . 'hyphens and backslashes.'
+            );
+        }
     }
 }

src/phpDocumentor/Reflection/DocBlock/Tag/ExampleTag.php

@@ -41,26 +41,19 @@ class ExampleTag extends SourceTag
     public function getContent()
     {
         if (null === $this->content) {
-            $filePath = '';
+            $filePath = '"' . $this->filePath . '"';
             if ($this->isURI) {
-                if (false === strpos($this->filePath, ':')) {
-                    $filePath = str_replace(
-                        '%2F',
-                        '/',
-                        rawurlencode($this->filePath)
-                    );
-                } else {
-                    $filePath = $this->filePath;
-                }
-            } else {
-                $filePath = '"' . $this->filePath . '"';
+                $filePath = $this->isUriRelative($this->filePath)
+                    ? str_replace('%2F', '/', rawurlencode($this->filePath))
+                    :$this->filePath;
             }
 
-            $this->content = $filePath . ' ' . $this->getContent();
+            $this->content = $filePath . ' ' . parent::getContent();
         }
 
         return $this->content;
     }
+
     /**
      * {@inheritdoc}
      */
@@ -131,26 +124,35 @@ class ExampleTag extends SourceTag
      * Sets the file path as an URI.
      * 
      * This function is equivalent to {@link setFilePath()}, except that it
-     * convers an URI to a file path before that.
+     * converts an URI to a file path before that.
      * 
      * There is no getFileURI(), as {@link getFilePath()} is compatible.
      * 
-     * @param type $uri The new file URI to use as an example.
+     * @param string $uri The new file URI to use as an example.
+     *
+     * @return $this
      */
     public function setFileURI($uri)
     {
-        $this->isURI = true;
-        if (false === strpos($uri, ':')) {
-            //Relative URL
-            $this->filePath = rawurldecode(
-                str_replace(array('/', '\\'), '%2F', $uri)
-            );
-        } else {
-            //Absolute URL or URI.
-            $this->filePath = $uri;
-        }
-
+        $this->isURI   = true;
         $this->content = null;
+
+        $this->filePath = $this->isUriRelative($uri)
+            ? rawurldecode(str_replace(array('/', '\\'), '%2F', $uri))
+            : $this->filePath = $uri;
+
         return $this;
     }
+
+    /**
+     * Returns true if the provided URI is relative or contains a complete scheme (and thus is absolute).
+     *
+     * @param string $uri
+     *
+     * @return bool
+     */
+    private function isUriRelative($uri)
+    {
+        return false === strpos($uri, ':');
+    }
 }

src/phpDocumentor/Reflection/DocBlock/Tag/MethodTag.php

@@ -30,18 +30,25 @@ class MethodTag extends ReturnTag
     /** @var string */
     protected $arguments = '';
     
+    /** @var bool */
+    protected $isStatic = false;
+
     /**
      * {@inheritdoc}
      */
     public function getContent()
     {
         if (null === $this->content) {
-            $this->content = $this->type .
+            $this->content = '';
+            if ($this->isStatic) {
+                $this->content .= 'static ';
+            }
+            $this->content .= $this->type .
                 " {$this->method_name}({$this->arguments}) " .
                 $this->description;
         }
 
-        return $this;
+        return $this->content;
     }
 
     /**
@@ -51,15 +58,22 @@ class MethodTag extends ReturnTag
     {
         Tag::setContent($content);
         // 1. none or more whitespace
-        // 2. optionally a word with underscores followed by whitespace : as
+        // 2. optionally the keyword "static" followed by whitespace
+        // 3. optionally a word with underscores followed by whitespace : as
         //    type for the return value
-        // 3. then optionally a word with underscores followed by () and
+        // 4. then optionally a word with underscores followed by () and
         //    whitespace : as method name as used by phpDocumentor
-        // 4. then a word with underscores, followed by ( and any character
+        // 5. then a word with underscores, followed by ( and any character
         //    until a ) and whitespace : as method name with signature
-        // 5. any remaining text : as description
+        // 6. any remaining text : as description
         if (preg_match(
             '/^
+                # Static keyword
+                # Declates a static method ONLY if type is also present
+                (?:
+                    (static)
+                    \s+
+                )?
                 # Return type
                 (?:
                     ([\w\|_\\\\]+)
@@ -82,18 +96,24 @@ class MethodTag extends ReturnTag
         )) {
             list(
                 ,
+                $static,
                 $this->type,
                 $this->method_name,
                 $this->arguments,
                 $this->description
             ) = $matches;
-            if (!$this->type) {
-                $this->type = 'void';
+            if ($static) {
+                if (!$this->type) {
+                    $this->type = 'static';
+                } else {
+                    $this->isStatic = true;
+                }
+            } else {
+                if (!$this->type) {
+                    $this->type = 'void';
+                }
             }
             $this->parsedDescription = null;
-        } else {
-            echo date('c') . ' ERR (3): @method contained invalid contents: '
-                . $this->content . PHP_EOL;
         }
 
         return $this;
@@ -160,4 +180,30 @@ class MethodTag extends ReturnTag
 
         return $arguments;
     }
+    
+    /**
+     * Checks whether the method tag describes a static method or not.
+     * 
+     * @return bool TRUE if the method declaration is for a static method, FALSE
+     *     otherwise.
+     */
+    public function isStatic()
+    {
+        return $this->isStatic;
+    }
+    
+    /**
+     * Sets a new value for whether the method is static or not.
+     * 
+     * @param bool $isStatic The new value to set.
+     * 
+     * @return $this
+     */
+    public function setIsStatic($isStatic)
+    {
+        $this->isStatic = $isStatic;
+
+        $this->content = null;
+        return $this;
+    }
 }

src/phpDocumentor/Reflection/DocBlock/Tag/ParamTag.php

@@ -23,11 +23,12 @@ use phpDocumentor\Reflection\DocBlock\Tag;
  */
 class ParamTag extends ReturnTag
 {
-    /**
-     * @var string
-     */
+    /** @var string */
     protected $variableName = '';
 
+    /** @var bool determines whether this is a variadic argument */
+    protected $isVariadic = false;
+
     /**
      * {@inheritdoc}
      */
@@ -61,13 +62,18 @@ class ParamTag extends ReturnTag
             array_shift($parts);
         }
 
-        // if the next item starts with a $ it must be the variable name
+        // if the next item starts with a $ or ...$ it must be the variable name
         if (isset($parts[0])
             && (strlen($parts[0]) > 0)
-            && ($parts[0][0] == '$')
+            && ($parts[0][0] == '$' || substr($parts[0], 0, 4) === '...$')
         ) {
             $this->variableName = array_shift($parts);
             array_shift($parts);
+
+            if (substr($this->variableName, 0, 3) === '...') {
+                $this->isVariadic = true;
+                $this->variableName = substr($this->variableName, 3);
+            }
         }
 
         $this->setDescription(implode('', $parts));
@@ -100,4 +106,14 @@ class ParamTag extends ReturnTag
         $this->content = null;
         return $this;
     }
+
+    /**
+     * Returns whether this tag is variadic.
+     *
+     * @return boolean
+     */
+    public function isVariadic()
+    {
+        return $this->isVariadic;
+    }
 }

src/phpDocumentor/Reflection/DocBlock/Tag/ReturnTag.php

@@ -33,13 +33,13 @@ class ReturnTag extends Tag
     /**
      * {@inheritdoc}
      */
-    public function getCotnent()
+    public function getContent()
     {
         if (null === $this->content) {
             $this->content = "{$this->type} {$this->description}";
         }
 
-        return $this->cotnent;
+        return $this->content;
     }
 
     /**
@@ -53,6 +53,7 @@ class ReturnTag extends Tag
 
         // any output is considered a type
         $this->type = $parts[0];
+        $this->types = null;
 
         $this->setDescription(isset($parts[1]) ? $parts[1] : '');
 

tests/phpDocumentor/Reflection/DocBlock/ContextFactoryTest.php

@@ -0,0 +1,94 @@
+<?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 {
+
+// Added imports on purpose as mock for the unit tests, please do not remove.
+    use Mockery as m;
+    use phpDocumentor\Reflection\DocBlock,
+        phpDocumentor\Reflection\DocBlock\Tag;
+    use \ReflectionClass; // yes, the slash is part of the test
+
+    /**
+     * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\ContextFactory
+     * @covers ::<private>
+     */
+    class ContextFactoryTest extends \PHPUnit_Framework_TestCase
+    {
+        /**
+         * @covers ::createFromClassReflector
+         * @covers ::createForNamespace
+         * @uses phpDocumentor\Reflection\DocBlock\Context
+         */
+        public function testReadsNamespaceFromClassReflection()
+        {
+            $fixture = new ContextFactory();
+            $context = $fixture->createFromClassReflector(new ReflectionClass($this));
+
+            $this->assertSame(__NAMESPACE__, $context->getNamespace());
+        }
+
+        /**
+         * @covers ::createFromClassReflector
+         * @covers ::createForNamespace
+         * @uses phpDocumentor\Reflection\DocBlock\Context
+         */
+        public function testReadsAliasesFromClassReflection()
+        {
+            $fixture = new ContextFactory();
+            $expected = [
+                'm' => 'Mockery',
+                'DocBlock' => 'phpDocumentor\Reflection\DocBlock',
+                'Tag' => 'phpDocumentor\Reflection\DocBlock\Tag',
+                'ReflectionClass' => 'ReflectionClass'
+            ];
+            $context = $fixture->createFromClassReflector(new ReflectionClass($this));
+
+            $this->assertSame($expected, $context->getNamespaceAliases());
+        }
+
+        /**
+         * @covers ::createForNamespace
+         * @uses phpDocumentor\Reflection\DocBlock\Context
+         */
+        public function testReadsNamespaceFromProvidedNamespaceAndContent()
+        {
+            $fixture = new ContextFactory();
+            $context = $fixture->createForNamespace(__NAMESPACE__, file_get_contents(__FILE__));
+
+            $this->assertSame(__NAMESPACE__, $context->getNamespace());
+        }
+
+        /**
+         * @covers ::createForNamespace
+         * @uses phpDocumentor\Reflection\DocBlock\Context
+         */
+        public function testReadsAliasesFromProvidedNamespaceAndContent()
+        {
+            $fixture = new ContextFactory();
+            $expected = [
+                'm' => 'Mockery',
+                'DocBlock' => 'phpDocumentor\Reflection\DocBlock',
+                'Tag' => 'phpDocumentor\Reflection\DocBlock\Tag',
+                'ReflectionClass' => 'ReflectionClass'
+            ];
+            $context = $fixture->createForNamespace(__NAMESPACE__, file_get_contents(__FILE__));
+
+            $this->assertSame($expected, $context->getNamespaceAliases());
+        }
+    }
+}
+
+namespace phpDocumentor\Reflection\DocBlock\Mock {
+    // the following import should not show in the tests above
+    use phpDocumentor\Reflection\DocBlock\Description;
+}

tests/phpDocumentor/Reflection/DocBlock/ContextTest.php

@@ -0,0 +1,61 @@
+<?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;
+
+use Mockery as m;
+
+/**
+ * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\Context
+ */
+class ContextTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @covers ::__construct
+     * @covers ::getNamespace
+     */
+    public function testProvidesANormalizedNamespace()
+    {
+        $fixture = new Context('\My\Space');
+        $this->assertSame('My\Space', $fixture->getNamespace());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::getNamespace
+     */
+    public function testInterpretsNamespaceNamedGlobalAsRootNamespace()
+    {
+        $fixture = new Context('global');
+        $this->assertSame('', $fixture->getNamespace());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::getNamespace
+     */
+    public function testInterpretsNamespaceNamedDefaultAsRootNamespace()
+    {
+        $fixture = new Context('default');
+        $this->assertSame('', $fixture->getNamespace());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::getNamespaceAliases
+     */
+    public function testProvidesNormalizedNamespaceAliases()
+    {
+        $fixture = new Context('', ['Space' => '\My\Space']);
+        $this->assertSame(['Space' => 'My\Space'], $fixture->getNamespaceAliases());
+    }
+}

tests/phpDocumentor/Reflection/DocBlock/Tag/MethodTagTest.php

@@ -44,6 +44,7 @@ class MethodTagTest extends \PHPUnit_Framework_TestCase
         $valid,
         $expected_name,
         $expected_return,
+        $expected_isStatic,
         $paramCount,
         $description
     ) {
@@ -64,64 +65,82 @@ class MethodTagTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expected_name, $tag->getMethodName());
         $this->assertEquals($expected_return, $tag->getType());
         $this->assertEquals($description, $tag->getDescription());
+        $this->assertEquals($expected_isStatic, $tag->isStatic());
         $this->assertCount($paramCount, $tag->getArguments());
     }
 
     public function getTestSignatures()
     {
         return array(
-            array(
-                'foo',
-                false, 'foo', '', 0, ''
-            ),
+            // TODO: Verify this case
+//            array(
+//                'foo',
+//                false, 'foo', '', false, 0, ''
+//            ),
             array(
                 'foo()',
-                true, 'foo', 'void', 0, ''
+                true, 'foo', 'void', false, 0, ''
             ),
             array(
                 'foo() description',
-                true, 'foo', 'void', 0, 'description'
+                true, 'foo', 'void', false, 0, 'description'
             ),
             array(
                 'int foo()',
-                true, 'foo', 'int', 0, ''
+                true, 'foo', 'int', false, 0, ''
             ),
             array(
                 'int foo() description',
-                true, 'foo', 'int', 0, 'description'
+                true, 'foo', 'int', false, 0, 'description'
             ),
             array(
                 'int foo($a, $b)',
-                true, 'foo', 'int', 2, ''
+                true, 'foo', 'int', false, 2, ''
             ),
             array(
                 'int foo() foo(int $a, int $b)',
-                true, 'foo', 'int', 2, ''
+                true, 'foo', 'int', false, 2, ''
             ),
             array(
                 'int foo(int $a, int $b)',
-                true, 'foo', 'int', 2, ''
+                true, 'foo', 'int', false, 2, ''
             ),
             array(
                 'null|int foo(int $a, int $b)',
-                true, 'foo', 'null|int', 2, ''
+                true, 'foo', 'null|int', false, 2, ''
             ),
             array(
                 'int foo(null|int $a, int $b)',
-                true, 'foo', 'int', 2, ''
+                true, 'foo', 'int', false, 2, ''
             ),
             array(
                 '\Exception foo() foo(Exception $a, Exception $b)',
-                true, 'foo', '\Exception', 2, ''
+                true, 'foo', '\Exception', false, 2, ''
             ),
             array(
                 'int foo() foo(Exception $a, Exception $b) description',
-                true, 'foo', 'int', 2, 'description'
+                true, 'foo', 'int', false, 2, 'description'
             ),
             array(
                 'int foo() foo(\Exception $a, \Exception $b) description',
-                true, 'foo', 'int', 2, 'description'
+                true, 'foo', 'int', false, 2, 'description'
             ),
+            array(
+                'void()',
+                true, 'void', 'void', false, 0, ''
+            ),
+            array(
+                'static foo()',
+                true, 'foo', 'static', false, 0, ''
+            ),
+            array(
+                'static void foo()',
+                true, 'foo', 'void', true, 0, ''
+            ),
+            array(
+                'static static foo()',
+                true, 'foo', 'static', true, 0, ''
+            )
         );
     }
 }

tests/phpDocumentor/Reflection/DocBlockTest.php

@@ -14,6 +14,7 @@ namespace phpDocumentor\Reflection;
 
 use phpDocumentor\Reflection\DocBlock\Context;
 use phpDocumentor\Reflection\DocBlock\Location;
+use phpDocumentor\Reflection\DocBlock\Tag\ReturnTag;
 
 /**
  * Test class for phpDocumentor\Reflection\DocBlock
@@ -34,9 +35,9 @@ class DocBlockTest extends \PHPUnit_Framework_TestCase
     {
         $fixture = <<<DOCBLOCK
 /**
- * This is a short description.
+ * This is a short description
  *
- * This is a long description.
+ * This is a long description
  *
  * @see \MyClass
  * @return void
@@ -48,11 +49,11 @@ DOCBLOCK;
             new Location(2)
         );
         $this->assertEquals(
-            'This is a short description.',
+            'This is a short description',
             $object->getShortDescription()
         );
         $this->assertEquals(
-            'This is a long description.',
+            'This is a long description',
             $object->getLongDescription()->getContents()
         );
         $this->assertCount(2, $object->getTags());
@@ -90,6 +91,41 @@ DOCBLOCK;
         $this->assertFalse($object->hasTag('category'));
     }
 
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock::isTemplateStart
+     */
+    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());
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock::isTemplateEnd
+     */
+    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
      * 
@@ -142,7 +178,8 @@ DOCBLOCK;
     {
         $fixture = <<<DOCBLOCK
 /**
- * This is a short description. This is a long description.
+ * This is a short description.
+ * This is a long description.
  * This is a continuation of the long description.
  */
 DOCBLOCK;
@@ -271,7 +308,10 @@ DOCBLOCK;
  */
 DOCBLOCK;
         $object = new DocBlock($fixture);
-        $this->assertCount(1, $object->getTags());
+        $this->assertCount(1, $tags = $object->getTags());
+	    /** @var ReturnTag $tag */
+	    $tag = reset($tags);
+	    $this->assertEquals("Content on\n    multiple lines.\n\n    One more, after the break.", $tag->getDescription());
     }
 
     /**