Document what parseText is doing

Author: ondrejmirtes

Diff for: src/Parser/PhpDocParser.php

@@ -214,21 +214,27 @@ private function parseText(TokenIterator $tokens): Ast\PhpDoc\PhpDocTextNode
 	{
 		$text = '';
 
+		// if the next token is EOL, everything below is skipped and empty string is returned
 		while (!$tokens->isCurrentTokenType(Lexer::TOKEN_PHPDOC_EOL)) {
 			$text .= $tokens->getSkippedHorizontalWhiteSpaceIfAny() . $tokens->joinUntil(Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END);
 
+			// stop if we're not at EOL - meaning it's the end of PHPDoc
 			if (!$tokens->isCurrentTokenType(Lexer::TOKEN_PHPDOC_EOL)) {
 				break;
 			}
 
 			$tokens->pushSavePoint();
 			$tokens->next();
 
+			// if we're at EOL, check what's next
+			// if next is a PHPDoc tag, EOL, or end of PHPDoc, stop
 			if ($tokens->isCurrentTokenType(Lexer::TOKEN_PHPDOC_TAG, Lexer::TOKEN_DOCTRINE_TAG, Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END)) {
 				$tokens->rollback();
 				break;
 			}
 
+			// otherwise if the next is text, continue building the description string
+
 			$tokens->dropSavePoint();
 			$text .= $tokens->getDetectedNewline() ?? "\n";
 		}
@@ -241,9 +247,11 @@ private function parseOptionalDescriptionAfterDoctrineTag(TokenIterator $tokens)
 	{
 		$text = '';
 
+		// if the next token is EOL, everything below is skipped and empty string is returned
 		while (!$tokens->isCurrentTokenType(Lexer::TOKEN_PHPDOC_EOL)) {
 			$text .= $tokens->getSkippedHorizontalWhiteSpaceIfAny() . $tokens->joinUntil(Lexer::TOKEN_PHPDOC_TAG, Lexer::TOKEN_DOCTRINE_TAG, Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END);
 
+			// stop if we're not at EOL - meaning it's the end of PHPDoc
 			if (!$tokens->isCurrentTokenType(Lexer::TOKEN_PHPDOC_EOL)) {
 				if (!$tokens->isPrecededByHorizontalWhitespace()) {
 					return trim($text . $this->parseText($tokens)->text, " \t");
@@ -281,11 +289,15 @@ private function parseOptionalDescriptionAfterDoctrineTag(TokenIterator $tokens)
 			$tokens->pushSavePoint();
 			$tokens->next();
 
+			// if we're at EOL, check what's next
+			// if next is a PHPDoc tag, EOL, or end of PHPDoc, stop
 			if ($tokens->isCurrentTokenType(Lexer::TOKEN_PHPDOC_TAG, Lexer::TOKEN_DOCTRINE_TAG, Lexer::TOKEN_PHPDOC_EOL, Lexer::TOKEN_CLOSE_PHPDOC, Lexer::TOKEN_END)) {
 				$tokens->rollback();
 				break;
 			}
 
+			// otherwise if the next is text, continue building the description string
+
 			$tokens->dropSavePoint();
 			$text .= $tokens->getDetectedNewline() ?? "\n";
 		}