From ade70feb999233f7382bdb0b0cbd30d95cf016eb Mon Sep 17 00:00:00 2001 From: Markus Staab Date: Wed, 1 Jan 2025 20:37:05 +0100 Subject: [PATCH 1/2] More precise phpdocs --- lib/PhpParser/Comment.php | 9 +++++++-- lib/PhpParser/Internal/TokenPolyfill.php | 8 +++++--- lib/PhpParser/Lexer.php | 2 +- lib/PhpParser/Token.php | 6 +++++- 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/lib/PhpParser/Comment.php b/lib/PhpParser/Comment.php index 01b341e438..eb8fdb4909 100644 --- 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 index 36022d09a0..26e9694f81 100644 --- 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 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 */ public static function tokenize(string $code, int $flags = 0): array { self::init(); diff --git a/lib/PhpParser/Lexer.php b/lib/PhpParser/Lexer.php index 5e2ece9617..c865e3ad4d 100644 --- 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 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 index 6683310f16..8b64668b41 100644 --- 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"); } From 0753360754b73cf50dc73f0bb9aa33313ac29599 Mon Sep 17 00:00:00 2001 From: Markus Staab Date: Wed, 1 Jan 2025 21:01:06 +0100 Subject: [PATCH 2/2] Drop changes to parameter types --- lib/PhpParser/Comment.php | 3 +-- lib/PhpParser/Internal/TokenPolyfill.php | 2 -- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/lib/PhpParser/Comment.php b/lib/PhpParser/Comment.php index eb8fdb4909..fa073c5055 100644 --- a/lib/PhpParser/Comment.php +++ b/lib/PhpParser/Comment.php @@ -17,10 +17,9 @@ class Comment implements \JsonSerializable { * Constructs a comment node. * * @param string $text Comment text (including comment delimiters like /*) - * @param -1|positive-int $startLine Line number the comment started on + * @param 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, diff --git a/lib/PhpParser/Internal/TokenPolyfill.php b/lib/PhpParser/Internal/TokenPolyfill.php index 26e9694f81..8af103308e 100644 --- a/lib/PhpParser/Internal/TokenPolyfill.php +++ b/lib/PhpParser/Internal/TokenPolyfill.php @@ -38,8 +38,6 @@ 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;