Skip to content
Snippets Groups Projects
Commit c8664dfc authored by Klaus Purer's avatar Klaus Purer
Browse files

fix(DocComment): Fix handling of doc comment tags within tag groups (#2947589)

parent c31df23e
Branches
Tags
No related merge requests found
Showing with 150 additions and 25 deletions
......@@ -138,9 +138,16 @@ class DocCommentAlignmentSniff implements Sniff
} else if ($tokens[($i + 2)]['code'] === T_DOC_COMMENT_TAG
&& $tokens[($i + 1)]['content'] !== ' '
// Special @code/@endcode/@see tags can have more than 1 space.
&& $tokens[($i + 2)]['content'] !== '@code'
&& $tokens[($i + 2)]['content'] !== '@endcode'
&& $tokens[($i + 2)]['content'] !== '@see'
&& in_array(
$tokens[($i + 2)]['content'],
[
'@param',
'@return',
'@throws',
'@ingroup',
'@var',
]
) === true
) {
$error = 'Expected 1 space after asterisk; %s found';
$data = [strlen($tokens[($i + 1)]['content'])];
......@@ -148,7 +155,7 @@ class DocCommentAlignmentSniff implements Sniff
if ($fix === true) {
$phpcsFile->fixer->replaceToken(($i + 1), ' ');
}
}
}//end if
}//end for
}//end process()
......
......@@ -375,10 +375,11 @@ class DocCommentSniff implements Sniff
$currentTag = null;
$previousTag = null;
$isNewGroup = null;
$ignoreTags = [
'@code',
'@endcode',
'@see',
$checkTags = [
'@param',
'@return',
'@throws',
'@ingroup',
];
foreach ($tokens[$commentStart]['comment_tags'] as $pos => $tag) {
if ($pos > 0) {
......@@ -416,12 +417,9 @@ class DocCommentSniff implements Sniff
// The @param, @return and @throws tag sections should be
// separated by a blank line both before and after these sections.
} else if ($isNewGroup === false
&& (in_array($currentTag, ['@param', '@return', '@throws']) === true
|| in_array($previousTag, ['@param', '@return', '@throws']) === true)
&& in_array($currentTag, $checkTags) === true
&& in_array($previousTag, $checkTags) === true
&& $previousTag !== $currentTag
// Ignore code blocks in comments, they can be anywhere.
&& in_array($previousTag, $ignoreTags) === false
&& in_array($currentTag, $ignoreTags) === false
) {
$error = 'Separate the %s and %s sections by a blank line.';
$fix = $phpcsFile->addFixableError($error, $tag, 'TagGroupSpacing', [$previousTag, $currentTag]);
......@@ -507,7 +505,7 @@ class DocCommentSniff implements Sniff
foreach ($tokens[$stackPtr]['comment_tags'] as $pos => $tag) {
$tagName = $tokens[$tag]['content'];
// Skip code tags, they can be anywhere.
if (in_array($tagName, $ignoreTags) === true) {
if (in_array($tagName, $checkTags) === false) {
continue;
}
......
......@@ -541,19 +541,24 @@ class FunctionCommentSniff implements Sniff
$skipTags = [
'@code',
'@endcode',
'@link',
];
$skipPos = $pos;
while (isset($tokens[$commentStart]['comment_tags'][($skipPos + 1)]) === true
&& in_array($tokens[$tokens[$commentStart]['comment_tags'][($skipPos + 1)]]['content'], $skipTags) === true
) {
while (isset($tokens[$commentStart]['comment_tags'][($skipPos + 1)]) === true) {
$skipPos++;
if (in_array($tokens[$tokens[$commentStart]['comment_tags'][$skipPos]]['content'], $skipTags) === false
// Stop when we reached the next tag on the outer @param level.
&& $tokens[$tokens[$commentStart]['comment_tags'][$skipPos]]['column'] === $tokens[$tag]['column']
) {
break;
}
}
if ($skipPos === $pos) {
$skipPos++;
if ($tokens[$tokens[$commentStart]['comment_tags'][$skipPos]]['column'] === ($tokens[$tag]['column'] + 2)) {
$end = $tokens[$commentStart]['comment_closer'];
} else {
$end = $tokens[$commentStart]['comment_tags'][$skipPos];
}
$end = $tokens[$commentStart]['comment_tags'][$skipPos];
} else {
$end = $tokens[$commentStart]['comment_closer'];
}//end if
......@@ -563,6 +568,13 @@ class FunctionCommentSniff implements Sniff
$indent = 0;
if ($tokens[($i - 1)]['code'] === T_DOC_COMMENT_WHITESPACE) {
$indent = strlen($tokens[($i - 1)]['content']);
// There can be @code or @link tags within an @param comment.
if ($tokens[($i - 2)]['code'] === T_DOC_COMMENT_TAG) {
$indent = 0;
if ($tokens[($i - 3)]['code'] === T_DOC_COMMENT_WHITESPACE) {
$indent = strlen($tokens[($i - 3)]['content']);
}
}
}
$comment .= ' '.$tokens[$i]['content'];
......@@ -578,7 +590,7 @@ class FunctionCommentSniff implements Sniff
$phpcsFile->fixer->replaceToken(($i - 1), ' ');
}
}
}
}//end if
}//end for
// The first line of the comment must be indented no more than 3
......
......@@ -27,3 +27,21 @@ class Test {
function test31($a) {
}
/**
* Some short comment.
*
* @param array $matches
* An array of matches by a preg_replace_callback() call that scans for
* @import-ed CSS files, except for external CSS files.
* @param array $sub_key
* An array containing the sub-keys specifying the library asset, e.g.
* @code['js']@endcode or @code['css', 'component']@endcode
* @param string $to
* The email address or addresses where the message will be sent to. The
* formatting of this string will be validated with the
* @link http://php.net/manual/filter.filters.validate.php PHP email @endlink.
*/
function test14(array $matches, array $sub_key, $to) {
}
......@@ -27,3 +27,21 @@ class Test {
function test31($a) {
}
/**
* Some short comment.
*
* @param array $matches
* An array of matches by a preg_replace_callback() call that scans for
* @import-ed CSS files, except for external CSS files.
* @param array $sub_key
* An array containing the sub-keys specifying the library asset, e.g.
* @code['js']@endcode or @code['css', 'component']@endcode
* @param string $to
* The email address or addresses where the message will be sent to. The
* formatting of this string will be validated with the
* @link http://php.net/manual/filter.filters.validate.php PHP email @endlink.
*/
function test14(array $matches, array $sub_key, $to) {
}
<?php
/**
* This doc comment ends in a dot, but has some white space after it.
* This doc comment ends in a dot, but has some white space after it.
*/
/**
......@@ -94,7 +94,7 @@ function test12() {
*
* @Given (the following )organisations:
*/
public function givenOrganisations(TableNode $organisation_table) {
function givenOrganisations(TableNode $organisation_table) {
}
/**+
......@@ -103,3 +103,21 @@ public function givenOrganisations(TableNode $organisation_table) {
function test13() {
}
/**
* Some short comment.
*
* @param array $matches
* An array of matches by a preg_replace_callback() call that scans for
* @import-ed CSS files, except for external CSS files.
* @param array $sub_key
* An array containing the sub-keys specifying the library asset, e.g.
* @code['js']@endcode or @code['css', 'component']@endcode
* @param string $to
* The email address or addresses where the message will be sent to. The
* formatting of this string will be validated with the
* @link http://php.net/manual/filter.filters.validate.php PHP email @endlink.
*/
function test14(array $matches, array $sub_key, $to) {
}
......@@ -102,7 +102,7 @@ function test12() {
*
* @Given (the following )organisations:
*/
public function givenOrganisations(TableNode $organisation_table) {
function givenOrganisations(TableNode $organisation_table) {
}
/**
......@@ -112,3 +112,21 @@ public function givenOrganisations(TableNode $organisation_table) {
function test13() {
}
/**
* Some short comment.
*
* @param array $matches
* An array of matches by a preg_replace_callback() call that scans for
* @import-ed CSS files, except for external CSS files.
* @param array $sub_key
* An array containing the sub-keys specifying the library asset, e.g.
* @code['js']@endcode or @code['css', 'component']@endcode
* @param string $to
* The email address or addresses where the message will be sent to. The
* formatting of this string will be validated with the
* @link http://php.net/manual/filter.filters.validate.php PHP email @endlink.
*/
function test14(array $matches, array $sub_key, $to) {
}
......@@ -488,3 +488,21 @@ class Small {
}
}
/**
* Some short comment.
*
* @param array $matches
* An array of matches by a preg_replace_callback() call that scans for
* @import-ed CSS files, except for external CSS files.
* @param array $sub_key
* An array containing the sub-keys specifying the library asset, e.g.
* @code['js']@endcode or @code['css', 'component']@endcode
* @param string $to
* The email address or addresses where the message will be sent to. The
* formatting of this string will be validated with the
* @link http://php.net/manual/filter.filters.validate.php PHP email @endlink.
*/
function test37(array $matches, array $sub_key, $to) {
}
......@@ -514,3 +514,21 @@ class Small {
}
}
/**
* Some short comment.
*
* @param array $matches
* An array of matches by a preg_replace_callback() call that scans for
* @import-ed CSS files, except for external CSS files.
* @param array $sub_key
* An array containing the sub-keys specifying the library asset, e.g.
* @code['js']@endcode or @code['css', 'component']@endcode
* @param string $to
* The email address or addresses where the message will be sent to. The
* formatting of this string will be validated with the
* @link http://php.net/manual/filter.filters.validate.php PHP email @endlink.
*/
function test37(array $matches, array $sub_key, $to) {
}
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment