More precise phpdocs

nikic · Jan 1, 2025 · ade70fe · ade70fe
1 parent 7d3039c
commit ade70fe
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 7 deletions.
diff --git a/lib/PhpParser/Comment.php b/lib/PhpParser/Comment.php
@@ -4,9 +4,11 @@
 
 class Comment implements \JsonSerializable {
     protected string $text;
+    /** @var -1|positive-int */
     protected int $startLine;
     protected int $startFilePos;
     protected int $startTokenPos;
+    /** @var -1|positive-int */
     protected int $endLine;
     protected int $endFilePos;
     protected int $endTokenPos;
@@ -15,9 +17,10 @@ class Comment implements \JsonSerializable {
      * Constructs a comment node.
      *
      * @param string $text Comment text (including comment delimiters like /*)
-     * @param int $startLine Line number the comment started on
+     * @param -1|positive-int $startLine Line number the comment started on
      * @param int $startFilePos File offset the comment started on
      * @param int $startTokenPos Token offset the comment started on
+     * @param -1|positive-int $endLine
      */
     public function __construct(
         string $text,
@@ -179,7 +182,9 @@ private function getShortestWhitespacePrefixLen(string $str): int {
         $lines = explode("\n", $str);
         $shortestPrefixLen = \PHP_INT_MAX;
         foreach ($lines as $line) {
-            preg_match('(^\s*)', $line, $matches);
+            if (!preg_match('(^\s*)', $line, $matches)) {
+                continue;
+            }
             $prefixLen = strlen($matches[0]);
             if ($prefixLen < $shortestPrefixLen) {
                 $shortestPrefixLen = $prefixLen;

diff --git a/lib/PhpParser/Internal/TokenPolyfill.php b/lib/PhpParser/Internal/TokenPolyfill.php
@@ -20,9 +20,9 @@ class TokenPolyfill {
     public int $id;
     /** @var string The textual content of the token. */
     public string $text;
-    /** @var int The 1-based starting line of the token (or -1 if unknown). */
+    /** @var -1|positive-int The 1-based starting line of the token (or -1 if unknown). */
     public int $line;
-    /** @var int The 0-based starting position of the token (or -1 if unknown). */
+    /** @var int<-1, max> The 0-based starting position of the token (or -1 if unknown). */
     public int $pos;
 
     /** @var array<int, bool> Tokens ignored by the PHP parser. */
@@ -38,6 +38,8 @@ class TokenPolyfill {
 
     /**
      * Create a Token with the given ID and text, as well optional line and position information.
+     *
+     * @param -1|positive-int $line
      */
     final public function __construct(int $id, string $text, int $line = -1, int $pos = -1) {
         $this->id = $id;
@@ -119,7 +121,7 @@ public function __toString(): string {
      *    T_WHITESPACE token.
      *  * Namespaced names are represented using T_NAME_* tokens.
      *
-     * @return static[]
+     * @return list<static>
      */
     public static function tokenize(string $code, int $flags = 0): array {
         self::init();

diff --git a/lib/PhpParser/Lexer.php b/lib/PhpParser/Lexer.php
@@ -19,7 +19,7 @@ class Lexer {
      * @param string $code The source code to tokenize.
      * @param ErrorHandler|null $errorHandler Error handler to use for lexing errors. Defaults to
      *                                        ErrorHandler\Throwing.
-     * @return Token[] Tokens
+     * @return list<Token> Tokens
      */
     public function tokenize(string $code, ?ErrorHandler $errorHandler = null): array {
         if (null === $errorHandler) {

diff --git a/lib/PhpParser/Token.php b/lib/PhpParser/Token.php
@@ -11,7 +11,11 @@ public function getEndPos(): int {
         return $this->pos + \strlen($this->text);
     }
 
-    /** Get 1-based end line number of the token. */
+    /**
+     * Get 1-based end line number of the token.
+     *
+     * @return -1|positive-int
+     */
     public function getEndLine(): int {
         return $this->line + \substr_count($this->text, "\n");
     }