From 3558e794326f279dddc98f526ed19757de3b8d35 Mon Sep 17 00:00:00 2001
From: Tyson Andre <tysonandre775@hotmail.com>
Date: Thu, 14 Sep 2017 22:46:08 -0700
Subject: [PATCH] Make phpdoc of Node and its subclasses more accurate

- Some node subclasses have `Token` (not an array) as `$this->children`
- Undefined variable in coalesce
- be more specific about getRoot()'s expected value.
- use string ...$classNames (same syntax as a real signature)
  https://github.com/phpDocumentor/fig-standards/pull/87#r37054459
- EchoExpression has ExpressionList (no expressions would be invalid PHP)
---
 src/Node.php                           | 6 +++---
 src/Node/Expression/EchoExpression.php | 3 ++-
 src/Node/NumericLiteral.php            | 2 +-
 src/Node/QualifiedName.php             | 2 +-
 src/Node/ReservedWord.php              | 2 +-
 src/Node/StringLiteral.php             | 2 +-
 6 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/Node.php b/src/Node.php
index a01c66d3..afdd6eb0 100644
--- a/src/Node.php
+++ b/src/Node.php
@@ -78,7 +78,7 @@ public function getParent() {
      * Gets first ancestor that is an instance of one of the provided classes.
      * Returns null if there is no match.
      *
-     * @param array ...$classNames
+     * @param string ...$classNames
      * @return Node|null
      */
     public function getFirstAncestor(...$classNames) {
@@ -139,7 +139,7 @@ public function getFirstDescendantNode(...$classNames) {
 
     /**
      * Gets root of the syntax tree (returns self if has no parents)
-     * @return Node
+     * @return SourceFileNode (expect root to be SourceFileNode unless the tree was manipulated)
      */
     public function getRoot() : Node {
         $node = $this;
@@ -450,7 +450,7 @@ public function __toString() {
      * @throws \Exception
      */
     public function getImportTablesForCurrentScope() {
-        $namespaceDefinition = $namespaceDefinition ?? $this->getNamespaceDefinition();
+        $namespaceDefinition = $this->getNamespaceDefinition();
 
         // Use declarations can exist in either the global scope, or inside namespace declarations.
         // http://php.net/manual/en/language.namespaces.importing.php#language.namespaces.importing.scope
diff --git a/src/Node/Expression/EchoExpression.php b/src/Node/Expression/EchoExpression.php
index c74ec969..03af3221 100644
--- a/src/Node/Expression/EchoExpression.php
+++ b/src/Node/Expression/EchoExpression.php
@@ -7,6 +7,7 @@
 namespace Microsoft\PhpParser\Node\Expression;
 
 use Microsoft\PhpParser\Node\Expression;
+use Microsoft\PhpParser\Node\DelimitedList\ExpressionList;
 use Microsoft\PhpParser\Token;
 
 class EchoExpression extends Expression {
@@ -14,7 +15,7 @@ class EchoExpression extends Expression {
     /** @var Token */
     public $echoKeyword;
 
-    /** @var Expression[] */
+    /** @var ExpressionList */
     public $expressions;
 
     const CHILD_NAMES = [
diff --git a/src/Node/NumericLiteral.php b/src/Node/NumericLiteral.php
index 2f8e105e..f311b7b0 100644
--- a/src/Node/NumericLiteral.php
+++ b/src/Node/NumericLiteral.php
@@ -9,7 +9,7 @@
 use Microsoft\PhpParser\Token;
 
 class NumericLiteral extends Expression {
-    /** @var Token[] */
+    /** @var Token */
     public $children;
 
     const CHILD_NAMES = [
diff --git a/src/Node/QualifiedName.php b/src/Node/QualifiedName.php
index ee4c8c31..8782b022 100644
--- a/src/Node/QualifiedName.php
+++ b/src/Node/QualifiedName.php
@@ -157,7 +157,7 @@ public function getLastNamePart() {
     /**
      * @param ResolvedName[] $importTable
      * @param bool $isCaseSensitive
-     * @return null
+     * @return string|null
      */
     private function tryResolveFromImportTable($importTable, bool $isCaseSensitive = false) {
         $content = $this->getFileContents();
diff --git a/src/Node/ReservedWord.php b/src/Node/ReservedWord.php
index 04567b2f..08361b07 100644
--- a/src/Node/ReservedWord.php
+++ b/src/Node/ReservedWord.php
@@ -9,7 +9,7 @@
 use Microsoft\PhpParser\Token;
 
 class ReservedWord extends Expression {
-    /** @var Token[] */
+    /** @var Token */
     public $children;
 
     const CHILD_NAMES = [
diff --git a/src/Node/StringLiteral.php b/src/Node/StringLiteral.php
index 9b081012..00018e0a 100644
--- a/src/Node/StringLiteral.php
+++ b/src/Node/StringLiteral.php
@@ -13,7 +13,7 @@ class StringLiteral extends Expression {
     /** @var Token */
     public $startQuote;
 
-    /** @var Token[] | Node[] */
+    /** @var Token[]|Node[]|Token */
     public $children;
 
     /** @var Token */