Skip to content
Permalink
Browse files

Use separate method for parsing docblocks

  • Loading branch information...
muglug committed Jun 1, 2019
1 parent 22b6c81 commit c569f3932c7149ffec4e7defbf6ea0d264ea5255
@@ -6,6 +6,19 @@
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
*/

This comment has been minimized.

Copy link
@voku

voku Jun 1, 2019

Contributor

doublicate phpdoc here

This comment has been minimized.

Copy link
@muglug

muglug Jun 2, 2019

Author Member

Ah thanks, will remove

/**
* Parse a docblock comment into its parts.
*
@@ -151,6 +164,122 @@ public static function parse($docblock, ?int $line_number = null)
];
}
/**
* 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 @@ public static function getTypeFromComment(
$original_type = null;
$var_comments = [];
$comments = DocComment::parse($comment);
$comments = DocComment::parsePreservingLength($comment);
$comment_text = $comment->getText();
@@ -73,16 +73,18 @@ public static function getTypeFromComment(
$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 @@ public static function getTypeAliasesFromComment(
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 @@ private static function getTypeAliasesFromCommentLines(
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 @@ private static function getTypeAliasesFromCommentLines(
*/
public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $comment)
{
$comments = DocComment::parse($comment);
$comments = DocComment::parsePreservingLength($comment);
$comment_text = $comment->getText();
@@ -295,18 +297,20 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
) {
$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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
$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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
+ (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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
: []);
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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
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 @@ public static function extractFunctionDocblockInfo(PhpParser\Comment\Doc $commen
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 @@ private static function extractReturnType(
$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 @@ private static function extractReturnType(
*/
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 @@ public static function extractClassLikeDocblockInfo(\PhpParser\Node $node, PhpPa
+ (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 @@ public static function extractClassLikeDocblockInfo(\PhpParser\Node $node, PhpPa
: []);
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 @@ public static function splitDocLine($return_block)
$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 @@ public static function splitDocLine($return_block)
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 @@ public function analyze(
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 @@ private function getDocblock()
$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 @@ public function enterNode(PhpParser\Node $node)
}
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 @@ private function visitClassConstDeclaration(
$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;

0 comments on commit c569f39

Please sign in to comment.
You can’t perform that action at this time.