danog/PHP-Parser
1
0
Fork 0
mirror of https://github.com/danog/PHP-Parser.git synced 2024-11-30 04:19:30 +01:00
Code Issues Projects Releases Wiki Activity

Update doc comments after previous comment

Browse Source 
Make some of the type annotations more accurate, and complete the
generated doc-comments to be complete (with description and
parameter annotations.)
This commit is contained in:
Nikita Popov 2017-01-26 00:16:54 +01:00
parent e3b87f40aa
commit bfea338d36
18 changed files with 185 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
UPGRADE-4.0.md
View File

@ -19,4 +19,5 @@ source code, while running on a newer version.
### Removed functionality
* Removed `type` subnode on `Class`, `ClassMethod` and `Property` nodes. Use `flags` instead.
* Removed `type` subnode on `Class`, `ClassMethod` and `Property` nodes. Use `flags` instead.
* The `ClassConst::isStatic()` method has been removed. Constants cannot have a static modifier.

7
lib/PhpParser/Comment.php
View File

@ -115,7 +115,12 @@ class Comment implements \JsonSerializable
}
/**
* @return float
* Get length of shortest whitespace prefix (at the start of a line).
*
* If there is a line with no prefix whitespace, 0 is a valid return value.
*
* @param string $str String to check
* @return int Length in characters. Tabs count as single characters.
*/
private function getShortestWhitespacePrefixLen($str) {
$lines = explode("\n", $str);

14
lib/PhpParser/Error.php
View File

@ -131,7 +131,11 @@ class Error extends \RuntimeException
}
/**
* @return string
* Formats message including line and column information.
*
* @param string $code Source code associated with the error, for calculation of the columns
*
* @return string Formatted message
*/
public function getMessageWithColumnInfo($code) {
return sprintf(
@ -141,6 +145,14 @@ class Error extends \RuntimeException
);
}
/**
* Converts a file offset into a column.
*
* @param string $code Source code that $pos indexes into
* @param int $pos 0-based position in $code
*
* @return int 1-based column (relative to start of line)
*/
private function toColumn($code, $pos) {
if ($pos > strlen($code)) {
throw new \RuntimeException('Invalid position information');

4
lib/PhpParser/Lexer.php
View File

@ -118,6 +118,8 @@ class Lexer
}
/**
* Check whether comment token is unterminated.
*
* @return bool
*/
private function isUnterminatedComment($token) {
@ -127,6 +129,8 @@ class Lexer
}
/**
* Check whether an error *may* have occurred during tokenization.
*
* @return bool
*/
private function errorMayHaveOccurred() {

13
lib/PhpParser/Lexer/Emulative.php
View File

@ -49,21 +49,22 @@ class Emulative extends \PhpParser\Lexer
}
}
/*
* Checks if the code is potentially using features that require emulation.
*/
/**
* @return int|false
* Checks if the code is potentially using features that require emulation.
*
* @param string $code Code to check
*
* @return bool
*/
protected function requiresEmulation($code) {
if (version_compare(PHP_VERSION, self::PHP_7_0, '>=')) {
return false;
}
return preg_match('(\?\?|<=>|yield[ \n\r\t]+from)', $code);
return (bool) preg_match('(\?\?|<=>|yield[ \n\r\t]+from)', $code);
}
/*
/**
* Emulates tokens for newer PHP versions.
*/
protected function emulateTokens() {

6
lib/PhpParser/Node/Scalar/String_.php
View File

@ -112,7 +112,11 @@ class String_ extends Scalar
}
/**
* @return string
* Converts a Unicode code point to its UTF-8 encoded representation.
*
* @param int $num Code point
*
* @return string UTF-8 representation of code point
*/
private static function codePointToUtf8($num) {
if ($num <= 0x7F) {

13
lib/PhpParser/Node/Stmt/ClassConst.php
View File

@ -29,6 +29,8 @@ class ClassConst extends Node\Stmt
}
/**
* Whether constant is explicitly or implicitly public.
*
* @return bool
*/
public function isPublic() {
@ -37,6 +39,8 @@ class ClassConst extends Node\Stmt
}
/**
* Whether constant is protected.
*
* @return bool
*/
public function isProtected() {
@ -44,16 +48,11 @@ class ClassConst extends Node\Stmt
}
/**
* Whether constant is private.
*
* @return bool
*/
public function isPrivate() {
return (bool) ($this->flags & Class_::MODIFIER_PRIVATE);
}
/**
* @return bool
*/
public function isStatic() {
return (bool) ($this->flags & Class_::MODIFIER_STATIC);
}
}

12
lib/PhpParser/Node/Stmt/ClassMethod.php
View File

@ -64,6 +64,8 @@ class ClassMethod extends Node\Stmt implements FunctionLike
}
/**
* Whether the method is explicitly or implicitly public.
*
* @return bool
*/
public function isPublic() {
@ -72,6 +74,8 @@ class ClassMethod extends Node\Stmt implements FunctionLike
}
/**
* Whether the method is protected.
*
* @return bool
*/
public function isProtected() {
@ -79,6 +83,8 @@ class ClassMethod extends Node\Stmt implements FunctionLike
}
/**
* Whether the method is private.
*
* @return bool
*/
public function isPrivate() {
@ -86,6 +92,8 @@ class ClassMethod extends Node\Stmt implements FunctionLike
}
/**
* Whether the method is abstract.
*
* @return bool
*/
public function isAbstract() {
@ -93,6 +101,8 @@ class ClassMethod extends Node\Stmt implements FunctionLike
}
/**
* Whether the method is final.
* #
* @return bool
*/
public function isFinal() {
@ -100,6 +110,8 @@ class ClassMethod extends Node\Stmt implements FunctionLike
}
/**
* Whether the method is static.
*
* @return bool
*/
public function isStatic() {

6
lib/PhpParser/Node/Stmt/Class_.php
View File

@ -55,6 +55,8 @@ class Class_ extends ClassLike
}
/**
* Whether the class is explicitly abstract.
*
* @return bool
*/
public function isAbstract() {
@ -62,6 +64,8 @@ class Class_ extends ClassLike
}
/**
* Whether the class is final.
*
* @return bool
*/
public function isFinal() {
@ -69,6 +73,8 @@ class Class_ extends ClassLike
}
/**
* Whether the class is anonymous.
*
* @return bool
*/
public function isAnonymous() {

8
lib/PhpParser/Node/Stmt/Property.php
View File

@ -29,6 +29,8 @@ class Property extends Node\Stmt
}
/**
* Whether the property is explicitly or implicitly public.
*
* @return bool
*/
public function isPublic() {
@ -37,6 +39,8 @@ class Property extends Node\Stmt
}
/**
* Whether the property is protected.
*
* @return bool
*/
public function isProtected() {
@ -44,6 +48,8 @@ class Property extends Node\Stmt
}
/**
* Whether the property is private.
*
* @return bool
*/
public function isPrivate() {
@ -51,6 +57,8 @@ class Property extends Node\Stmt
}
/**
* Whether the property is static.
*
* @return bool
*/
public function isStatic() {

6
lib/PhpParser/NodeDumper.php
View File

@ -165,7 +165,11 @@ class NodeDumper
}
/**
* @return string|null
* Dump node position, if possible.
*
* @param Node $node Node for which to dump position
*
* @return string|null Dump of position, or null if position information not available
*/
protected function dumpPosition(Node $node) {
if (!$node->hasAttribute('startLine') || !$node->hasAttribute('endLine')) {

17
lib/PhpParser/NodeTraverser.php
View File

@ -58,8 +58,9 @@ class NodeTraverser implements NodeTraverserInterface
/**
* Traverses an array of nodes using the registered visitors.
*
* @param Node[] $nodes Array of nodes
* @return array
* @param Node[] $nodes Array of nodes
*
* @return Node[] Traversed array of nodes
*/
public function traverse(array $nodes) {
foreach ($this->visitors as $visitor) {
@ -80,7 +81,11 @@ class NodeTraverser implements NodeTraverserInterface
}
/**
* @return \PhpParser\Node
* Recursively traverse a node.
*
* @param Node $node Node to traverse.
*
* @return Node Result of traversal (may be original node or new one)
*/
protected function traverseNode(Node $node) {
foreach ($node->getSubNodeNames() as $name) {
@ -121,7 +126,11 @@ class NodeTraverser implements NodeTraverserInterface
}
/**
* @return array
* Recursively traverse array (usually of nodes).
*
* @param array $nodes Array to traverse
*
* @return array Result of traversal (may be original array or changed one)
*/
protected function traverseArray(array $nodes) {
$doNodes = array();

26
lib/PhpParser/NodeVisitor/NameResolver.php
View File

@ -193,7 +193,11 @@ class NameResolver extends NodeVisitorAbstract
}
/**
* @return null|Name
* Resolve class name, according to name resolver options.
*
* @param Name $name Class ame to resolve
*
* @return Name Resolved name, or original name with attribute
*/
protected function resolveClassName(Name $name) {
if (!$this->replaceNodes) {
@ -212,7 +216,12 @@ class NameResolver extends NodeVisitorAbstract
}
/**
* @return Name
* Resolve function or constant name, according to name resolver options.
*
* @param Name $name Function or constant name to resolve
* @param int $type One of Stmt\Use_::TYPE_{FUNCTION|CONSTANT}
*
* @return Name Resolved name, or original name with attribute
*/
protected function resolveOtherName(Name $name, $type) {
if (!$this->replaceNodes) {
@ -246,7 +255,11 @@ class NameResolver extends NodeVisitorAbstract
}
/**
* @return null|Name
* Get resolved class name.
*
* @param Name $name Class ame to resolve
*
* @return Name Resolved name
*/
protected function getResolvedClassName(Name $name) {
// don't resolve special class names
@ -277,7 +290,12 @@ class NameResolver extends NodeVisitorAbstract
}
/**
* @return null|Name
* Get resolved function or constant name.
*
* @param Name $name Function or constant name to resolve
* @param int $type One of Stmt\Use_::TYPE_{FUNCTION|CONSTANT}
*
* @return null|Name Resolved name, or null if static resolution is not possible
*/
protected function getResolvedOtherName(Name $name, $type) {
// fully qualified names are already resolved

4
lib/PhpParser/Parser/Multiple.php
View File

@ -23,10 +23,6 @@ class Multiple implements Parser {
$this->parsers = $parsers;
}
/**
* @return \PhpParser\Node\Stmt[]
* @psalm-return array<mixed, \PhpParser\Node\Stmt>
*/
public function parse($code, ErrorHandler $errorHandler = null) {
if (null === $errorHandler) {
$errorHandler = new ErrorHandler\Throwing;

63
lib/PhpParser/ParserAbstract.php
View File

@ -47,40 +47,40 @@ abstract class ParserAbstract implements Parser
protected $YY2TBLSTATE;
protected $YYNLSTATES;
/** @var array Map of lexer tokens to internal symbols */
/** @var int[] Map of lexer tokens to internal symbols */
protected $tokenToSymbol;
/** @var array Map of symbols to their names */
/** @var string[] Map of symbols to their names */
protected $symbolToName;
/** @var array Names of the production rules (only necessary for debugging) */
protected $productions;
/** @var array Map of states to a displacement into the $action table. The corresponding action for this
/** @var int[] Map of states to a displacement into the $action table. The corresponding action for this
* state/symbol pair is $action[$actionBase[$state] + $symbol]. If $actionBase[$state] is 0, the
action is defaulted, i.e. $actionDefault[$state] should be used instead. */
protected $actionBase;
/** @var array Table of actions. Indexed according to $actionBase comment. */
/** @var int[] Table of actions. Indexed according to $actionBase comment. */
protected $action;
/** @var array Table indexed analogously to $action. If $actionCheck[$actionBase[$state] + $symbol] != $symbol
/** @var int[] Table indexed analogously to $action. If $actionCheck[$actionBase[$state] + $symbol] != $symbol
* then the action is defaulted, i.e. $actionDefault[$state] should be used instead. */
protected $actionCheck;
/** @var array Map of states to their default action */
/** @var int[]Map of states to their default action */
protected $actionDefault;
/** @var array Map of non-terminals to a displacement into the $goto table. The corresponding goto state for this
/** @var int[] Map of non-terminals to a displacement into the $goto table. The corresponding goto state for this
* non-terminal/state pair is $goto[$gotoBase[$nonTerminal] + $state] (unless defaulted) */
protected $gotoBase;
/** @var array Table of states to goto after reduction. Indexed according to $gotoBase comment. */
/** @var int[] Table of states to goto after reduction. Indexed according to $gotoBase comment. */
protected $goto;
/** @var array Table indexed analogously to $goto. If $gotoCheck[$gotoBase[$nonTerminal] + $state] != $nonTerminal
/** @var int[] Table indexed analogously to $goto. If $gotoCheck[$gotoBase[$nonTerminal] + $state] != $nonTerminal
* then the goto state is defaulted, i.e. $gotoDefault[$nonTerminal] should be used. */
protected $gotoCheck;
/** @var array Map of non-terminals to the default state to goto after their reduction */
/** @var int[] Map of non-terminals to the default state to goto after their reduction */
protected $gotoDefault;
/** @var array Map of rules to the non-terminal on their left-hand side, i.e. the non-terminal to use for
/** @var int[] Map of rules to the non-terminal on their left-hand side, i.e. the non-terminal to use for
* determining the state to goto after reduction. */
protected $ruleToNonTerminal;
/** @var array Map of rules to the length of their right-hand side, which is the number of elements that have to
/** @var int[] Map of rules to the length of their right-hand side, which is the number of elements that have to
* be popped from the stack(s) on reduction. */
protected $ruleToLength;
@ -356,7 +356,12 @@ abstract class ParserAbstract implements Parser
}
/**
* @return string
* Format error message including expected tokens.
*
* @param int $symbol Unexpected symbol
* @param int $state State at time of error
*
* @return string Formatted error message
*/
protected function getErrorMessage($symbol, $state) {
$expectedString = '';
@ -368,8 +373,11 @@ abstract class ParserAbstract implements Parser
}
/**
* @return array
* @psalm-return array<int, mixed>
* Get limited number of expected tokens in given state.
*
* @param int $state State
*
* @return string[] Expected tokens. If too many, an empty array is returned.
*/
protected function getExpectedTokens($state) {
$expected = array();
@ -517,7 +525,11 @@ abstract class ParserAbstract implements Parser
}
/**
* @return null|string
* Determine namespacing style (semicolon or brace)
*
* @param Node[] $stmts Top-level statements.
*
* @return null|string One of "semicolon", "brace" or null (no namespaces)
*/
private function getNamespacingStyle(array $stmts) {
$style = null;
@ -562,9 +574,6 @@ abstract class ParserAbstract implements Parser
return $style;
}
/**
* @return \PhpParser\Node\Expr\StaticCall
*/
protected function fixupPhp5StaticPropCall($prop, array $args, array $attributes) {
if ($prop instanceof Node\Expr\StaticPropertyFetch) {
// Preserve attributes if possible
@ -649,15 +658,16 @@ abstract class ParserAbstract implements Parser
);
/**
* @return array
* Get combined start and end attributes at a stack location
*
* @param int $pos Stack location
*
* @return array Combined start and end attributes
*/
protected function getAttributesAt($pos) {
return $this->startAttributeStack[$pos] + $this->endAttributeStack[$pos];
}
/**
* @return LNumber
*/
protected function parseLNumber($str, $attributes, $allowInvalidOctal = false) {
try {
return LNumber::fromString($str, $attributes, $allowInvalidOctal);
@ -669,7 +679,12 @@ abstract class ParserAbstract implements Parser
}
/**
* @return LNumber|String_
* Parse a T_NUM_STRING token into either an integer or string node.
*
* @param string $str Number string
* @param array $attributes Attributes
*
* @return LNumber|String_ Integer or string node.
*/
protected function parseNumString($str, $attributes) {
if (!preg_match('/^(?:0|-?[1-9][0-9]*)$/', $str)) {

35
lib/PhpParser/PrettyPrinterAbstract.php
View File

@ -239,7 +239,14 @@ abstract class PrettyPrinterAbstract
}
/**
* @return string
* Pretty-print an infix operation while taking precedence into account.
*
* @param string $type Node type of operator
* @param Node $leftNode Left-hand side node
* @param string $operatorString String representation of the operator
* @param Node $rightNode Right-hand side node
*
* @return string Pretty printed infix operation
*/
protected function pInfixOp($type, Node $leftNode, $operatorString, Node $rightNode) {
list($precedence, $associativity) = $this->precedenceMap[$type];
@ -250,7 +257,13 @@ abstract class PrettyPrinterAbstract
}
/**
* @return string
* Pretty-print a prefix operation while taking precedence into account.
*
* @param string $type Node type of operator
* @param string $operatorString String representation of the operator
* @param Node $node Node
*
* @return string Pretty printed prefix operation
*/
protected function pPrefixOp($type, $operatorString, Node $node) {
list($precedence, $associativity) = $this->precedenceMap[$type];
@ -258,7 +271,13 @@ abstract class PrettyPrinterAbstract
}
/**
* @return string
* Pretty-print a postfix operation while taking precedence into account.
*
* @param string $type Node type of operator
* @param string $operatorString String representation of the operator
* @param Node $node Node
*
* @return string Pretty printed postfix operation
*/
protected function pPostfixOp($type, Node $node, $operatorString) {
list($precedence, $associativity) = $this->precedenceMap[$type];
@ -735,6 +754,11 @@ abstract class PrettyPrinterAbstract
}
/**
* Whether the fiven position is immediately surrounded by parenthesis.
*
* @param int $startPos Start position
* @param int $endPos End position
*
* @return bool
*/
protected function haveParens($startPos, $endPos) {
@ -743,6 +767,11 @@ abstract class PrettyPrinterAbstract
}
/**
* Whether the fiven position is immediately surrounded by braces.
*
* @param int $startPos Start position
* @param int $endPos End position
*
* @return bool
*/
protected function haveBraces($startPos, $endPos) {

6
lib/PhpParser/Unserializer/XML.php
View File

@ -140,7 +140,11 @@ class XML implements Unserializer
}
/**
* @return string
* Reconstruct the class name from the node type.
*
* @param string $type Node type
*
* @return string Node class name
*/
protected function getClassNameFromType($type) {
$className = 'PhpParser\\Node\\' . strtr($type, '_', '\\');

1
test/PhpParser/Node/Stmt/ClassConstTest.php
View File

@ -22,7 +22,6 @@ class ClassConstTest extends \PHPUnit_Framework_TestCase
$this->assertTrue($node->isPublic());
$this->assertFalse($node->isProtected());
$this->assertFalse($node->isPrivate());
$this->assertFalse($node->isStatic());
}
public function provideModifiers() {