fix(DocComment): Fix handling of doc comment tags within tag groups (#2947589) (c8664dfc) · Commits · project / coder

coder_sniffer/Drupal/Sniffs/Commenting/DocCommentAlignmentSniff.php

+11 −4

Original line number	Diff line number	Diff line
		@@ -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()

coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php

+8 −10

Original line number	Diff line number	Diff line
		@@ -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;
		}

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

+20 −8

Original line number	Diff line number	Diff line
		@@ -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];
		}
		} 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

coder_sniffer/Drupal/Test/Commenting/DocCommentAlignmentUnitTest.inc

+18 −0

Original line number	Diff line number	Diff line
		@@ -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) {

		}

coder_sniffer/Drupal/Test/Commenting/DocCommentAlignmentUnitTest.inc.fixed

+18 −0

Original line number	Diff line number	Diff line
		@@ -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) {

		}