mirror of
https://github.com/danog/psalm.git
synced 2024-11-26 20:34:47 +01:00
Use separate method for parsing docblocks
This commit is contained in:
Matthew Brown
parent
22b6c8120a
commit
c569f3932c
@ -6,6 +6,19 @@ use Psalm\Exception\DocblockParseException;
|
||||
|
||||
class DocComment
|
||||
{
|
||||
/**
|
||||
* Parse a docblock comment into its parts.
|
||||
*
|
||||
* Taken from advanced api docmaker, which was taken from
|
||||
* https://github.com/facebook/libphutil/blob/master/src/parser/docblock/PhutilDocblockParser.php
|
||||
*
|
||||
* @param string|\PhpParser\Comment\Doc $docblock
|
||||
* @param bool $preserve_format
|
||||
*
|
||||
* @return array Array of the main comment and specials
|
||||
* @psalm-return array{description:string, specials:array<string, array<int, string>>}
|
||||
* @psalm-suppress PossiblyUnusedParam
|
||||
*/
|
||||
/**
|
||||
* Parse a docblock comment into its parts.
|
||||
*
|
||||
@ -151,6 +164,122 @@ class DocComment
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse a docblock comment into its parts.
|
||||
*
|
||||
* Taken from advanced api docmaker, which was taken from
|
||||
* https://github.com/facebook/libphutil/blob/master/src/parser/docblock/PhutilDocblockParser.php
|
||||
*
|
||||
* @param \PhpParser\Comment\Doc $docblock
|
||||
* @param bool $preserve_format
|
||||
*
|
||||
* @return array Array of the main comment and specials
|
||||
* @psalm-return array{description:string, specials:array<string, array<int, string>>}
|
||||
*/
|
||||
public static function parsePreservingLength(\PhpParser\Comment\Doc $docblock)
|
||||
{
|
||||
$docblock = $docblock->getText();
|
||||
|
||||
// Strip off comments.
|
||||
$docblock = trim($docblock);
|
||||
|
||||
$docblock = preg_replace('@^/\*\*@', '', $docblock);
|
||||
$docblock = preg_replace('@\*/$@', '', $docblock);
|
||||
|
||||
// Normalize multi-line @specials.
|
||||
$lines = explode("\n", $docblock);
|
||||
|
||||
$special = [];
|
||||
|
||||
$last = false;
|
||||
foreach ($lines as $k => $line) {
|
||||
if (preg_match('/^[ \t]*\*?\s?@\w/i', $line)) {
|
||||
$last = $k;
|
||||
} elseif (preg_match('/^\s*$/', $line)) {
|
||||
$last = false;
|
||||
} elseif ($last !== false) {
|
||||
$old_last_line = $lines[$last];
|
||||
$lines[$last] = $old_last_line . "\n" . $line;
|
||||
|
||||
unset($lines[$k]);
|
||||
}
|
||||
}
|
||||
|
||||
$line_offset = 0;
|
||||
|
||||
foreach ($lines as $line) {
|
||||
if (preg_match('/^[ \t]*\*?\s?@([\w\-:]+)[\t ]*(.*)$/sm', $line, $matches, PREG_OFFSET_CAPTURE)) {
|
||||
/** @var array<int, array{string, int}> $matches */
|
||||
list($full_match_info, $type_info, $data_info) = $matches;
|
||||
|
||||
list($full_match) = $full_match_info;
|
||||
list($type) = $type_info;
|
||||
list($data, $data_offset) = $data_info;
|
||||
|
||||
$docblock = str_replace($full_match, '', $docblock);
|
||||
|
||||
if (empty($special[$type])) {
|
||||
$special[$type] = [];
|
||||
}
|
||||
|
||||
$data_offset += $line_offset;
|
||||
|
||||
$special[$type][$data_offset + 3] = $data;
|
||||
}
|
||||
|
||||
$line_offset += strlen($line) + 1;
|
||||
}
|
||||
|
||||
$docblock = str_replace("\t", ' ', $docblock);
|
||||
|
||||
// Smush the whole docblock to the left edge.
|
||||
$min_indent = 80;
|
||||
$indent = 0;
|
||||
foreach (array_filter(explode("\n", $docblock)) as $line) {
|
||||
for ($ii = 0; $ii < strlen($line); ++$ii) {
|
||||
if ($line[$ii] != ' ') {
|
||||
break;
|
||||
}
|
||||
++$indent;
|
||||
}
|
||||
|
||||
$min_indent = min($indent, $min_indent);
|
||||
}
|
||||
|
||||
$docblock = preg_replace('/^' . str_repeat(' ', $min_indent) . '/m', '', $docblock);
|
||||
$docblock = rtrim($docblock);
|
||||
|
||||
// Trim any empty lines off the front, but leave the indent level if there
|
||||
// is one.
|
||||
$docblock = preg_replace('/^\s*\n/', '', $docblock);
|
||||
|
||||
foreach ($special as $special_key => $_) {
|
||||
if (substr($special_key, 0, 6) === 'psalm-') {
|
||||
$special_key = substr($special_key, 6);
|
||||
|
||||
if (!in_array(
|
||||
$special_key,
|
||||
[
|
||||
'return', 'param', 'template', 'var', 'type',
|
||||
'template-covariant', 'property', 'method',
|
||||
'assert', 'assert-if-true', 'assert-if-false', 'suppress',
|
||||
'ignore-nullable-return', 'override-property-visibility',
|
||||
'override-method-visibility', 'seal-properties', 'seal-methods',
|
||||
'generator-return', 'ignore-falsable-return', 'variadic',
|
||||
'ignore-variable-method', 'ignore-variable-property', 'internal',
|
||||
]
|
||||
)) {
|
||||
throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return [
|
||||
'description' => $docblock,
|
||||
'specials' => $special,
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array{description:string,specials:array<string,array<string>>} $parsed_doc_comment
|
||||
* @param string $left_padding
|
||||
|
||||
@ -44,7 +44,7 @@ class CommentAnalyzer
|
||||
$original_type = null;
|
||||
|
||||
$var_comments = [];
|
||||
$comments = DocComment::parse($comment);
|
||||
$comments = DocComment::parsePreservingLength($comment);
|
||||
|
||||
$comment_text = $comment->getText();
|
||||
|
||||
@ -73,16 +73,18 @@ class CommentAnalyzer
|
||||
$line_number = $comment->getLine() + substr_count($comment_text, "\n", 0, $offset);
|
||||
|
||||
if ($line_parts && $line_parts[0]) {
|
||||
$type_start = $offset + $comment->getFilePos();
|
||||
$type_end = $type_start + strlen($line_parts[0]);
|
||||
|
||||
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
|
||||
|
||||
if ($line_parts[0][0] === '$' && $line_parts[0] !== '$this') {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
}
|
||||
|
||||
$type_start = $offset + $comment->getFilePos();
|
||||
$type_end = $type_start + strlen($line_parts[0]);
|
||||
|
||||
try {
|
||||
$var_type_tokens = Type::fixUpLocalType(
|
||||
str_replace("\n", '', $line_parts[0]),
|
||||
$line_parts[0],
|
||||
$aliases,
|
||||
$template_type_map,
|
||||
$type_aliases
|
||||
@ -163,7 +165,7 @@ class CommentAnalyzer
|
||||
Aliases $aliases,
|
||||
array $type_aliases = null
|
||||
) {
|
||||
$comments = DocComment::parse($comment);
|
||||
$comments = DocComment::parsePreservingLength($comment);
|
||||
|
||||
if (!isset($comments['specials']['psalm-type'])) {
|
||||
return [];
|
||||
@ -199,7 +201,7 @@ class CommentAnalyzer
|
||||
continue;
|
||||
}
|
||||
|
||||
$var_line = preg_replace('/[ \t]+/', ' ', $var_line);
|
||||
$var_line = preg_replace('/[ \t]+/', ' ', preg_replace('@^[ \t]*\*@m', '', $var_line));
|
||||
|
||||
$var_line_parts = preg_split('/( |=)/', $var_line, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
|
||||
|
||||
@ -258,7 +260,7 @@ class CommentAnalyzer
|
||||
*/
|
||||
public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $comment)
|
||||
{
|
||||
$comments = DocComment::parse($comment);
|
||||
$comments = DocComment::parsePreservingLength($comment);
|
||||
|
||||
$comment_text = $comment->getText();
|
||||
|
||||
@ -295,18 +297,20 @@ class CommentAnalyzer
|
||||
) {
|
||||
$line_parts[1] = str_replace('&', '', $line_parts[1]);
|
||||
|
||||
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
}
|
||||
|
||||
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
|
||||
|
||||
$start = $offset + $comment->getFilePos();
|
||||
$end = $start + strlen($line_parts[0]);
|
||||
|
||||
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
|
||||
|
||||
if ($line_parts[0][0] === '$' && !preg_match('/^\$this(\||$)/', $line_parts[0])) {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
}
|
||||
|
||||
$info->params[] = [
|
||||
'name' => trim($line_parts[1]),
|
||||
'type' => str_replace("\n", '', $line_parts[0]),
|
||||
'type' => $line_parts[0],
|
||||
'line_number' => $comment->getLine() + substr_count($comment_text, "\n", 0, $offset),
|
||||
'start' => $start,
|
||||
'end' => $end,
|
||||
@ -342,6 +346,8 @@ class CommentAnalyzer
|
||||
|
||||
$line_parts[1] = preg_replace('/,$/', '', $line_parts[1]);
|
||||
|
||||
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
|
||||
|
||||
$info->params_out[] = [
|
||||
'name' => trim($line_parts[1]),
|
||||
'type' => str_replace("\n", '', $line_parts[0]),
|
||||
@ -441,7 +447,7 @@ class CommentAnalyzer
|
||||
+ (isset($comments['specials']['psalm-template']) ? $comments['specials']['psalm-template'] : []);
|
||||
|
||||
foreach ($all_templates as $template_line) {
|
||||
$template_type = preg_split('/[\s]+/', $template_line);
|
||||
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
|
||||
|
||||
$template_name = array_shift($template_type);
|
||||
|
||||
@ -473,7 +479,7 @@ class CommentAnalyzer
|
||||
: []);
|
||||
|
||||
foreach ($all_templates as $template_line) {
|
||||
$template_type = preg_split('/[\s]+/', $template_line);
|
||||
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
|
||||
|
||||
$template_name = array_shift($template_type);
|
||||
|
||||
@ -495,7 +501,7 @@ class CommentAnalyzer
|
||||
|
||||
if (isset($comments['specials']['template-typeof'])) {
|
||||
foreach ($comments['specials']['template-typeof'] as $template_typeof) {
|
||||
$typeof_parts = preg_split('/[\s]+/', $template_typeof);
|
||||
$typeof_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_typeof));
|
||||
|
||||
if (count($typeof_parts) < 2 || $typeof_parts[1][0] !== '$') {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
@ -510,7 +516,7 @@ class CommentAnalyzer
|
||||
|
||||
if (isset($comments['specials']['psalm-assert'])) {
|
||||
foreach ($comments['specials']['psalm-assert'] as $assertion) {
|
||||
$assertion_parts = preg_split('/[\s]+/', $assertion);
|
||||
$assertion_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $assertion));
|
||||
|
||||
if (count($assertion_parts) < 2 || $assertion_parts[1][0] !== '$') {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
@ -525,7 +531,7 @@ class CommentAnalyzer
|
||||
|
||||
if (isset($comments['specials']['psalm-assert-if-true'])) {
|
||||
foreach ($comments['specials']['psalm-assert-if-true'] as $assertion) {
|
||||
$assertion_parts = preg_split('/[\s]+/', $assertion);
|
||||
$assertion_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $assertion));
|
||||
|
||||
if (count($assertion_parts) < 2 || $assertion_parts[1][0] !== '$') {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
@ -540,7 +546,7 @@ class CommentAnalyzer
|
||||
|
||||
if (isset($comments['specials']['psalm-assert-if-false'])) {
|
||||
foreach ($comments['specials']['psalm-assert-if-false'] as $assertion) {
|
||||
$assertion_parts = preg_split('/[\s]+/', $assertion);
|
||||
$assertion_parts = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $assertion));
|
||||
|
||||
if (count($assertion_parts) < 2 || $assertion_parts[1][0] !== '$') {
|
||||
throw new IncorrectDocblockException('Misplaced variable');
|
||||
@ -592,6 +598,8 @@ class CommentAnalyzer
|
||||
$start = $offset + $comment->getFilePos();
|
||||
$end = $start + strlen($line_parts[0]);
|
||||
|
||||
$line_parts[0] = str_replace("\n", '', preg_replace('@^[ \t]*\*@m', '', $line_parts[0]));
|
||||
|
||||
$info->return_type = str_replace("\n", '', array_shift($line_parts));
|
||||
$info->return_type_description = $line_parts ? implode(' ', $line_parts) : null;
|
||||
|
||||
@ -615,7 +623,7 @@ class CommentAnalyzer
|
||||
*/
|
||||
public static function extractClassLikeDocblockInfo(\PhpParser\Node $node, PhpParser\Comment\Doc $comment)
|
||||
{
|
||||
$comments = DocComment::parse($comment);
|
||||
$comments = DocComment::parsePreservingLength($comment);
|
||||
|
||||
$info = new ClassLikeDocblockComment();
|
||||
|
||||
@ -624,7 +632,7 @@ class CommentAnalyzer
|
||||
+ (isset($comments['specials']['psalm-template']) ? $comments['specials']['psalm-template'] : []);
|
||||
|
||||
foreach ($all_templates as $template_line) {
|
||||
$template_type = preg_split('/[\s]+/', $template_line);
|
||||
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
|
||||
|
||||
$template_name = array_shift($template_type);
|
||||
|
||||
@ -656,7 +664,7 @@ class CommentAnalyzer
|
||||
: []);
|
||||
|
||||
foreach ($all_templates as $template_line) {
|
||||
$template_type = preg_split('/[\s]+/', $template_line);
|
||||
$template_type = preg_split('/[\s]+/', preg_replace('@^[ \t]*\*@m', '', $template_line));
|
||||
|
||||
$template_name = array_shift($template_type);
|
||||
|
||||
@ -946,7 +954,7 @@ class CommentAnalyzer
|
||||
|
||||
$expects_callable_return = false;
|
||||
|
||||
$return_block = preg_replace('/[ \t]+/', ' ', $return_block);
|
||||
$return_block = str_replace("\t", ' ', $return_block);
|
||||
|
||||
$quote_char = null;
|
||||
$escaped = false;
|
||||
@ -1042,10 +1050,11 @@ class CommentAnalyzer
|
||||
continue;
|
||||
}
|
||||
|
||||
$remaining = trim(substr($return_block, $i + 1));
|
||||
$remaining = trim(preg_replace('@^[ \t]*\* *@m', ' ', substr($return_block, $i + 1)));
|
||||
|
||||
if ($remaining) {
|
||||
return array_merge([$type], explode(' ', $remaining));
|
||||
/** @var array<string> */
|
||||
return array_merge([rtrim($type)], preg_split('/[ \s]+/', $remaining));
|
||||
}
|
||||
|
||||
return [$type];
|
||||
|
||||
@ -206,7 +206,7 @@ class StatementsAnalyzer extends SourceAnalyzer implements StatementsSource
|
||||
|
||||
if ($docblock = $stmt->getDocComment()) {
|
||||
try {
|
||||
$comments = DocComment::parse($docblock);
|
||||
$comments = DocComment::parsePreservingLength($docblock);
|
||||
} catch (DocblockParseException $e) {
|
||||
if (IssueBuffer::accepts(
|
||||
new InvalidDocblock(
|
||||
|
||||
@ -286,11 +286,19 @@ class FunctionDocblockManipulator
|
||||
$docblock = $this->stmt->getDocComment();
|
||||
|
||||
if ($docblock) {
|
||||
$parsed_docblock = DocComment::parse($docblock);
|
||||
$parsed_docblock = DocComment::parsePreservingLength($docblock);
|
||||
} else {
|
||||
$parsed_docblock = ['description' => '', 'specials' => []];
|
||||
}
|
||||
|
||||
foreach ($parsed_docblock['specials'] as $type => $blocks) {
|
||||
foreach ($blocks as $i => $block) {
|
||||
$parsed_docblock['specials'][$type][$i] = preg_replace('@^[ \t]*\*@m', '', $block);
|
||||
}
|
||||
}
|
||||
|
||||
$parsed_docblock['description'] = trim(preg_replace('@^[ \t]*\* ?@m', '', $parsed_docblock['description']));
|
||||
|
||||
foreach ($this->new_phpdoc_param_types as $param_name => $phpdoc_type) {
|
||||
$found_in_params = false;
|
||||
$new_param_block = $phpdoc_type . ' ' . '$' . $param_name;
|
||||
|
||||
@ -333,7 +333,7 @@ class ReflectorVisitor extends PhpParser\NodeVisitorAbstract implements PhpParse
|
||||
}
|
||||
|
||||
if ($node_comment = $node->getDocComment()) {
|
||||
$comments = DocComment::parse($node_comment);
|
||||
$comments = DocComment::parsePreservingLength($node_comment);
|
||||
|
||||
if (isset($comments['specials']['template-use'])
|
||||
|| isset($comments['specials']['use'])
|
||||
@ -2703,7 +2703,7 @@ class ReflectorVisitor extends PhpParser\NodeVisitorAbstract implements PhpParse
|
||||
$config = $this->config;
|
||||
|
||||
if ($comment && $comment->getText() && ($config->use_docblock_types || $config->use_docblock_property_types)) {
|
||||
$comments = DocComment::parse($comment);
|
||||
$comments = DocComment::parsePreservingLength($comment);
|
||||
|
||||
if (isset($comments['specials']['deprecated'])) {
|
||||
$deprecated = true;
|
||||
|
||||
@ -171,8 +171,13 @@ class MoveMethodTest extends \Psalm\Tests\TestCase
|
||||
|
||||
/**
|
||||
* @param self $a1
|
||||
* @param ?self $a2
|
||||
* @param self[] $a3
|
||||
* Some description
|
||||
* @param ?self
|
||||
* $a2
|
||||
* @param array<
|
||||
* int,
|
||||
* self
|
||||
* > $a3
|
||||
* @return self
|
||||
*/
|
||||
public static function Foo(self $a1, ?self $a2, array $a3) : self {
|
||||
@ -211,8 +216,10 @@ class MoveMethodTest extends \Psalm\Tests\TestCase
|
||||
|
||||
/**
|
||||
* @param A $a1
|
||||
* @param null|A $a2
|
||||
* @param array<array-key, A> $a3
|
||||
* Some description
|
||||
* @param null|A
|
||||
* $a2
|
||||
* @param array<int, A> $a3
|
||||
* @return A
|
||||
*/
|
||||
public static function Fedbca(A $a1, ?A $a2, array $a3) : A {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user