Skip to content

Commit

Permalink
Added support for array multi line function comments
Browse files Browse the repository at this point in the history
  • Loading branch information
martinssipenko committed Oct 7, 2022
1 parent d7864cb commit 0fc0907
Show file tree
Hide file tree
Showing 4 changed files with 101 additions and 7 deletions.
72 changes: 65 additions & 7 deletions src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php
Original file line number Diff line number Diff line change
Expand Up @@ -306,24 +306,57 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
$varSpace = 0;
$comment = '';
$commentLines = [];
$isMultiLine = false;
if ($tokens[($tag + 2)]['code'] === T_DOC_COMMENT_STRING) {
$content = $tokens[($tag + 2)]['content'];

$multiLineExtra = 0;

if (
!$this->parenthesisClosed($content, '{', '}')
|| !$this->parenthesisClosed($content, '<', '>')
) {
$isMultiLine = true;
$content = '';

$i = $tag + 2;

while (true) {
if ($tokens[$i]['content'] === '@param') {
break;
}

$content .= $tokens[$i]['content'];

if (
$this->parenthesisClosed($content, '{', '}')
&& $this->parenthesisClosed($content, '<', '>')
) {
break;
}

$multiLineExtra++;
$i++;
}
}

$matches = [];
preg_match('/([^$&.]+)(?:((?:\.\.\.)?(?:\$|&)[^\s]+)(?:(\s+)(.*))?)?/', $tokens[($tag + 2)]['content'], $matches);
preg_match('/([^$&.]+)(?:((?:\.\.\.)?(?:\$|&)[^\s]+)(?:(\s+)(.*))?)?/', $content, $matches);

if (empty($matches) === false) {
$typeLen = strlen($matches[1]);
$type = trim($matches[1]);
$typeSpace = ($typeLen - strlen($type));
$typeLen = strlen($type);
if ($typeLen > $maxType) {
if ($typeLen > $maxType && $isMultiLine === false) {
$maxType = $typeLen;
}
}

if (isset($matches[2]) === true) {
$var = $matches[2];
$varLen = strlen($var);
if ($varLen > $maxVar) {
if ($varLen > $maxVar && $isMultiLine === false) {
$maxVar = $varLen;
}

Expand All @@ -332,7 +365,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
$comment = $matches[4];
$commentLines[] = [
'comment' => $comment,
'token' => ($tag + 2),
'token' => ($tag + 2 + $multiLineExtra),
'indent' => $varSpace,
];

Expand All @@ -343,7 +376,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
$end = $tokens[$commentStart]['comment_closer'];
}

for ($i = ($tag + 3); $i < $end; $i++) {
for ($i = ($tag + 3 + $multiLineExtra); $i < $end; $i++) {
if ($tokens[$i]['code'] === T_DOC_COMMENT_STRING) {
$indent = 0;
if ($tokens[($i - 1)]['code'] === T_DOC_COMMENT_WHITESPACE) {
Expand Down Expand Up @@ -380,6 +413,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
'commentLines' => $commentLines,
'type_space' => $typeSpace,
'var_space' => $varSpace,
'multi_line' => $isMultiLine,
];
}//end foreach

Expand Down Expand Up @@ -547,7 +581,9 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
$foundParams[] = $param['var'];

// Check number of spaces after the type.
$this->checkSpacingAfterParamType($phpcsFile, $param, $maxType);
if ($param['multi_line'] === false) {
$this->checkSpacingAfterParamType($phpcsFile, $param, $maxType);
}

// Make sure the param name is correct.
if (isset($realParams[$pos]) === true) {
Expand Down Expand Up @@ -580,7 +616,9 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
}

// Check number of spaces after the var name.
$this->checkSpacingAfterParamName($phpcsFile, $param, $maxVar);
if ($param['multi_line'] === false) {
$this->checkSpacingAfterParamName($phpcsFile, $param, $maxVar);
}

// Param comments must start with a capital letter and end with a full stop.
if (preg_match('/^(\p{Ll}|\P{L})/u', $param['comment']) === 1) {
Expand Down Expand Up @@ -764,5 +802,25 @@ protected function checkInheritdoc(File $phpcsFile, $stackPtr, $commentStart)

}//end checkInheritdoc()

/**
* Determines wether string has the same number of open and close parenthesis.
*
* @param string $string
* @param string $openChar
* @param string $closeChar
* @return bool
*/
private function parenthesisClosed($string, $openChar, $closeChar)
{
if (stripos($string, $openChar) === false) {
return true;
}

$open = substr_count($string, $openChar);
$close = substr_count($string, $closeChar);

return $open === $close;
}//end parenthesisClosed


}//end class
17 changes: 17 additions & 0 deletions src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc
Original file line number Diff line number Diff line change
Expand Up @@ -1046,3 +1046,20 @@ public function ignored() {
* @return void
* @throws Exception If any other error occurs. */
function throwCommentOneLine() {}


/**
* @param array{foo: int} $a A.
* @param array{x: int} $ccc C.
* @param array{xxxx: int} $dddd D.
* @param array<array{
* foo: array{foo: int},
* bar: int
* }> $bb B.
*
* @return integer
*/
public function multiLineArray(array $a, array $ccc, array $dddd, array $bb)
{
return 1;
}//end multiLineArray()
Original file line number Diff line number Diff line change
Expand Up @@ -1046,3 +1046,20 @@ public function ignored() {
* @return void
* @throws Exception If any other error occurs. */
function throwCommentOneLine() {}


/**
* @param array{foo: int} $a A.
* @param array{x: int} $ccc C.
* @param array{xxxx: int} $dddd D.
* @param array<array{
* foo: array{foo: int},
* bar: int
* }> $bb B.
*
* @return integer
*/
public function multiLineArray(array $a, array $ccc, array $dddd, array $bb)
{
return 1;
}//end multiLineArray()
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,8 @@ public function getErrorList()
1004 => 2,
1006 => 1,
1029 => 1,
1052 => 2,
1053 => 2,
];

// Scalar type hints only work from PHP 7 onwards.
Expand Down

0 comments on commit 0fc0907

Please sign in to comment.