Merge pull request #254 from voku/fix_for_phpstorm_stubs

do not resolve types if it's not possible
phpDocumentor · Sep 3, 2020 · 069a785 · 069a785
2 parents f607592 + 2ef4c3d
commit 069a785
Show file tree

Hide file tree

Showing 39 changed files with 1,048 additions and 68 deletions.
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
@@ -46,7 +46,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Quick check code coverage level
-        run: php tests/coverage-checker.php 89
+        run: php tests/coverage-checker.php 91
 
   phpunit:
     name: Unit tests for PHP version ${{ matrix.php-versions }} on ${{ matrix.operating-system }}

diff --git a/src/DocBlock/Tags/Author.php b/src/DocBlock/Tags/Author.php
@@ -71,7 +71,15 @@ public function getEmail() : string
      */
     public function __toString() : string
     {
-        return $this->authorName . ($this->authorEmail !== '' ? ' <' . $this->authorEmail . '>' : '');
+        if ($this->authorEmail) {
+            $authorEmail = '<' . $this->authorEmail . '>';
+        } else {
+            $authorEmail = '';
+        }
+
+        $authorName = (string) $this->authorName;
+
+        return $authorName . ($authorEmail !== '' ? ($authorName !== '' ? ' ' : '') . $authorEmail : '');
     }
 
     /**

diff --git a/src/DocBlock/Tags/Covers.php b/src/DocBlock/Tags/Covers.php
@@ -49,7 +49,7 @@ public static function create(
         ?FqsenResolver $resolver = null,
         ?TypeContext $context = null
     ) : self {
-        Assert::notEmpty($body);
+        Assert::stringNotEmpty($body);
         Assert::notNull($descriptionFactory);
         Assert::notNull($resolver);
 
@@ -87,6 +87,14 @@ public function getReference() : Fqsen
      */
     public function __toString() : string
     {
-        return $this->refers . ($this->description ? ' ' . $this->description->render() : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        $refers = (string) $this->refers;
+
+        return $refers . ($description !== '' ? ($refers !== '' ? ' ' : '') . $description : '');
     }
 }
diff --git a/src/DocBlock/Tags/Deprecated.php b/src/DocBlock/Tags/Deprecated.php
@@ -95,6 +95,14 @@ public function getVersion() : ?string
      */
     public function __toString() : string
     {
-        return ($this->version ?? '') . ($this->description ? ' ' . $this->description->render() : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        $version = (string) $this->version;
+
+        return $version . ($description !== '' ? ($version !== '' ? ' ' : '') . $description : '');
     }
 }
diff --git a/src/DocBlock/Tags/Example.php b/src/DocBlock/Tags/Example.php
@@ -45,9 +45,14 @@ final class Example implements Tag, Factory\StaticMethod
     /** @var string|null */
     private $content;
 
-    public function __construct(string $filePath, bool $isURI, int $startingLine, int $lineCount, ?string $content)
-    {
-        Assert::notEmpty($filePath);
+    public function __construct(
+        string $filePath,
+        bool $isURI,
+        int $startingLine,
+        int $lineCount,
+        ?string $content
+    ) {
+        Assert::stringNotEmpty($filePath);
         Assert::greaterThanEq($startingLine, 1);
         Assert::greaterThanEq($lineCount, 0);
 
@@ -64,7 +69,7 @@ public function __construct(string $filePath, bool $isURI, int $startingLine, in
     public function getContent() : string
     {
         if ($this->content === null || $this->content === '') {
-            $filePath = '"' . $this->filePath . '"';
+            $filePath = $this->filePath;
             if ($this->isURI) {
                 $filePath = $this->isUriRelative($this->filePath)
                     ? str_replace('%2F', '/', rawurlencode($this->filePath))
@@ -85,7 +90,7 @@ public function getDescription() : ?string
     public static function create(string $body) : ?Tag
     {
         // File component: File path in quotes or File URI / Source information
-        if (!preg_match('/^(?:\"([^\"]+)\"|(\S+))(?:\s+(.*))?$/sux', $body, $matches)) {
+        if (!preg_match('/^\s*(?:(\"[^\"]+\")|(\S+))(?:\s+(.*))?$/sux', $body, $matches)) {
             return null;
         }
 
@@ -134,15 +139,30 @@ public static function create(string $body) : ?Tag
      */
     public function getFilePath() : string
     {
-        return $this->filePath;
+        return trim($this->filePath, '"');
     }
 
     /**
      * Returns a string representation for this tag.
      */
     public function __toString() : string
     {
-        return $this->filePath . ($this->content ? ' ' . $this->content : '');
+        $filePath = (string) $this->filePath;
+        $isDefaultLine = $this->startingLine === 1 && $this->lineCount === 0;
+        $startingLine = !$isDefaultLine ? (string) $this->startingLine : '';
+        $lineCount = !$isDefaultLine ? (string) $this->lineCount : '';
+        $content = (string) $this->content;
+
+        return $filePath
+            . ($startingLine !== ''
+                ? ($filePath !== '' ? ' ' : '') . $startingLine
+                : '')
+            . ($lineCount !== ''
+                ? ($filePath !== '' || $startingLine !== '' ? ' ' : '') . $lineCount
+                : '')
+            . ($content !== ''
+                ? ($filePath !== '' || $startingLine !== '' || $lineCount !== '' ? ' ' : '') . $content
+                : '');
     }
 
     /**

diff --git a/src/DocBlock/Tags/Generic.php b/src/DocBlock/Tags/Generic.php
@@ -64,7 +64,13 @@ public static function create(
      */
     public function __toString() : string
     {
-        return $this->description ? $this->description->render() : '';
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        return $description;
     }
 
     /**

diff --git a/src/DocBlock/Tags/Link.php b/src/DocBlock/Tags/Link.php
@@ -65,6 +65,14 @@ public function getLink() : string
      */
     public function __toString() : string
     {
-        return $this->link . ($this->description ? ' ' . $this->description->render() : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        $link = (string) $this->link;
+
+        return $link . ($description !== '' ? ($link !== '' ? ' ' : '') . $description : '');
     }
 }
diff --git a/src/DocBlock/Tags/Method.php b/src/DocBlock/Tags/Method.php
@@ -213,11 +213,25 @@ public function __toString() : string
             $arguments[] = $argument['type'] . ' $' . $argument['name'];
         }
 
-        return trim(($this->isStatic() ? 'static ' : '')
-            . (string) $this->returnType . ' '
-            . $this->methodName
-            . '(' . implode(', ', $arguments) . ')'
-            . ($this->description ? ' ' . $this->description->render() : ''));
+        $argumentStr = '(' . implode(', ', $arguments) . ')';
+
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        $static = $this->isStatic ? 'static' : '';
+
+        $returnType = (string) $this->returnType;
+
+        $methodName = (string) $this->methodName;
+
+        return $static
+            . ($returnType !== '' ? ($static !== '' ? ' ' : '') . $returnType : '')
+            . ($methodName !== '' ? ($static !== '' || $returnType !== '' ? ' ' : '') . $methodName : '')
+            . $argumentStr
+            . ($description !== '' ? ' ' . $description : '');
     }
 
     /**

diff --git a/src/DocBlock/Tags/Param.php b/src/DocBlock/Tags/Param.php
@@ -75,28 +75,19 @@ public static function create(
         $isReference   = false;
 
         // if the first item that is encountered is not a variable; it is a type
-        if ($firstPart && $firstPart[0] !== '$') {
+        if ($firstPart && !self::strStartsWithVariable($firstPart)) {
             $type = $typeResolver->resolve($firstPart, $context);
         } else {
             // first part is not a type; we should prepend it to the parts array for further processing
             array_unshift($parts, $firstPart);
         }
 
         // if the next item starts with a $ or ...$ or &$ or &...$ it must be the variable name
-        if (isset($parts[0])
-            &&
-            (
-                strpos($parts[0], '$') === 0
-                ||
-                strpos($parts[0], '...$') === 0
-                ||
-                strpos($parts[0], '&$') === 0
-                ||
-                strpos($parts[0], '&...$') === 0
-            )
-        ) {
+        if (isset($parts[0]) && self::strStartsWithVariable($parts[0])) {
             $variableName = array_shift($parts);
-            array_shift($parts);
+            if ($type) {
+                array_shift($parts);
+            }
 
             Assert::notNull($variableName);
 
@@ -149,10 +140,33 @@ public function isReference() : bool
      */
     public function __toString() : string
     {
-        return ($this->type ? $this->type . ' ' : '')
-            . ($this->isReference() ? '&' : '')
-            . ($this->isVariadic() ? '...' : '')
-            . ($this->variableName !== null ? '$' . $this->variableName : '')
-            . ($this->description ? ' ' . $this->description : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        $variableName = '';
+        if ($this->variableName) {
+            $variableName .= ($this->isReference ? '&' : '') . ($this->isVariadic ? '...' : '');
+            $variableName .= '$' . $this->variableName;
+        }
+
+        $type = (string) $this->type;
+
+        return $type
+            . ($variableName !== '' ? ($type !== '' ? ' ' : '') . $variableName : '')
+            . ($description !== '' ? ($type !== '' || $variableName !== '' ? ' ' : '') . $description : '');
+    }
+
+    private static function strStartsWithVariable(string $str) : bool
+    {
+        return strpos($str, '$') === 0
+               ||
+               strpos($str, '...$') === 0
+               ||
+               strpos($str, '&$') === 0
+               ||
+               strpos($str, '&...$') === 0;
     }
 }
diff --git a/src/DocBlock/Tags/Property.php b/src/DocBlock/Tags/Property.php
@@ -68,10 +68,12 @@ public static function create(
             array_unshift($parts, $firstPart);
         }
 
-        // if the next item starts with a $ or ...$ it must be the variable name
+        // if the next item starts with a $ it must be the variable name
         if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
-            array_shift($parts);
+            if ($type) {
+                array_shift($parts);
+            }
 
             Assert::notNull($variableName);
 
@@ -96,8 +98,22 @@ public function getVariableName() : ?string
      */
     public function __toString() : string
     {
-        return ($this->type ? $this->type . ' ' : '')
-            . ($this->variableName ? '$' . $this->variableName : '')
-            . ($this->description ? ' ' . $this->description : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        if ($this->variableName) {
+            $variableName = '$' . $this->variableName;
+        } else {
+            $variableName = '';
+        }
+
+        $type = (string) $this->type;
+
+        return $type
+            . ($variableName !== '' ? ($type !== '' ? ' ' : '') . $variableName : '')
+            . ($description !== '' ? ($type !== '' || $variableName !== '' ? ' ' : '') . $description : '');
     }
 }
diff --git a/src/DocBlock/Tags/PropertyRead.php b/src/DocBlock/Tags/PropertyRead.php
@@ -68,10 +68,12 @@ public static function create(
             array_unshift($parts, $firstPart);
         }
 
-        // if the next item starts with a $ or ...$ it must be the variable name
+        // if the next item starts with a $ it must be the variable name
         if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
-            array_shift($parts);
+            if ($type) {
+                array_shift($parts);
+            }
 
             Assert::notNull($variableName);
 
@@ -96,8 +98,22 @@ public function getVariableName() : ?string
      */
     public function __toString() : string
     {
-        return ($this->type ? $this->type . ' ' : '')
-            . ($this->variableName ? '$' . $this->variableName : '')
-            . ($this->description ? ' ' . $this->description : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        if ($this->variableName) {
+            $variableName = '$' . $this->variableName;
+        } else {
+            $variableName = '';
+        }
+
+        $type = (string) $this->type;
+
+        return $type
+            . ($variableName !== '' ? ($type !== '' ? ' ' : '') . $variableName : '')
+            . ($description !== '' ? ($type !== '' || $variableName !== '' ? ' ' : '') . $description : '');
     }
 }
diff --git a/src/DocBlock/Tags/PropertyWrite.php b/src/DocBlock/Tags/PropertyWrite.php
@@ -68,10 +68,12 @@ public static function create(
             array_unshift($parts, $firstPart);
         }
 
-        // if the next item starts with a $ or ...$ it must be the variable name
+        // if the next item starts with a $ it must be the variable name
         if (isset($parts[0]) && strpos($parts[0], '$') === 0) {
             $variableName = array_shift($parts);
-            array_shift($parts);
+            if ($type) {
+                array_shift($parts);
+            }
 
             Assert::notNull($variableName);
 
@@ -96,8 +98,22 @@ public function getVariableName() : ?string
      */
     public function __toString() : string
     {
-        return ($this->type ? $this->type . ' ' : '')
-            . ($this->variableName ? '$' . $this->variableName : '')
-            . ($this->description ? ' ' . $this->description : '');
+        if ($this->description) {
+            $description = $this->description->render();
+        } else {
+            $description = '';
+        }
+
+        if ($this->variableName) {
+            $variableName = '$' . $this->variableName;
+        } else {
+            $variableName = '';
+        }
+
+        $type = (string) $this->type;
+
+        return $type
+            . ($variableName !== '' ? ($type !== '' ? ' ' : '') . $variableName : '')
+            . ($description !== '' ? ($type !== '' || $variableName !== '' ? ' ' : '') . $description : '');
     }
 }