Chris@0: <?php
Chris@0: /**
Chris@0:  * Ensures doc blocks follow basic formatting.
Chris@0:  *
Chris@0:  * @category PHP
Chris@0:  * @package  PHP_CodeSniffer
Chris@0:  * @link     http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@0: 
Chris@17: namespace Drupal\Sniffs\Commenting;
Chris@17: 
Chris@17: use PHP_CodeSniffer\Files\File;
Chris@17: use PHP_CodeSniffer\Sniffs\Sniff;
Chris@17: 
Chris@0: /**
Chris@0:  * Ensures doc blocks follow basic formatting.
Chris@0:  *
Chris@17:  * Largely copied from
Chris@17:  * \PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting\DocCommentSniff,
Chris@17:  * but Drupal @file comments are different.
Chris@0:  *
Chris@0:  * @category PHP
Chris@0:  * @package  PHP_CodeSniffer
Chris@0:  * @link     http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@17: class DocCommentSniff implements Sniff
Chris@0: {
Chris@0: 
Chris@0:     /**
Chris@0:      * A list of tokenizers this sniff supports.
Chris@0:      *
Chris@0:      * @var array
Chris@0:      */
Chris@0:     public $supportedTokenizers = array(
Chris@0:                                    'PHP',
Chris@0:                                    'JS',
Chris@0:                                   );
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns an array of tokens this test wants to listen for.
Chris@0:      *
Chris@0:      * @return array
Chris@0:      */
Chris@0:     public function register()
Chris@0:     {
Chris@0:         return array(T_DOC_COMMENT_OPEN_TAG);
Chris@0: 
Chris@0:     }//end register()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Processes this test, when one of its tokens is encountered.
Chris@0:      *
Chris@17:      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
Chris@17:      * @param int                         $stackPtr  The position of the current token
Chris@17:      *                                               in the stack passed in $tokens.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@17:     public function process(File $phpcsFile, $stackPtr)
Chris@0:     {
Chris@0:         $tokens       = $phpcsFile->getTokens();
Chris@0:         $commentEnd   = $phpcsFile->findNext(T_DOC_COMMENT_CLOSE_TAG, ($stackPtr + 1));
Chris@0:         $commentStart = $tokens[$commentEnd]['comment_opener'];
Chris@0: 
Chris@0:         $empty = array(
Chris@0:                   T_DOC_COMMENT_WHITESPACE,
Chris@0:                   T_DOC_COMMENT_STAR,
Chris@0:                  );
Chris@0: 
Chris@0:         $short = $phpcsFile->findNext($empty, ($stackPtr + 1), $commentEnd, true);
Chris@0:         if ($short === false) {
Chris@0:             // No content at all.
Chris@0:             $error = 'Doc comment is empty';
Chris@0:             $phpcsFile->addError($error, $stackPtr, 'Empty');
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         // Ignore doc blocks in functions, this is handled by InlineCommentSniff.
Chris@0:         if (empty($tokens[$stackPtr]['conditions']) === false && in_array(T_FUNCTION, $tokens[$stackPtr]['conditions']) === true) {
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         // The first line of the comment should just be the /** code.
Chris@0:         // In JSDoc there are cases with @lends that are on the same line as code.
Chris@0:         if ($tokens[$short]['line'] === $tokens[$stackPtr]['line'] && $phpcsFile->tokenizerType !== 'JS') {
Chris@0:             $error = 'The open comment tag must be the only content on the line';
Chris@0:             $fix   = $phpcsFile->addFixableError($error, $stackPtr, 'ContentAfterOpen');
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->beginChangeset();
Chris@0:                 $phpcsFile->fixer->addNewline($stackPtr);
Chris@0:                 $phpcsFile->fixer->addContentBefore($short, '* ');
Chris@0:                 $phpcsFile->fixer->endChangeset();
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         // The last line of the comment should just be the */ code.
Chris@0:         $prev = $phpcsFile->findPrevious($empty, ($commentEnd - 1), $stackPtr, true);
Chris@0:         if ($tokens[$commentEnd]['content'] !== '*/') {
Chris@0:             $error = 'Wrong function doc comment end; expected "*/", found "%s"';
Chris@0:             $phpcsFile->addError($error, $commentEnd, 'WrongEnd', array($tokens[$commentEnd]['content']));
Chris@0:         }
Chris@0: 
Chris@0:         // Check for additional blank lines at the end of the comment.
Chris@0:         if ($tokens[$prev]['line'] < ($tokens[$commentEnd]['line'] - 1)) {
Chris@0:             $error = 'Additional blank lines found at end of doc comment';
Chris@0:             $fix   = $phpcsFile->addFixableError($error, $commentEnd, 'SpacingAfter');
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->beginChangeset();
Chris@0:                 for ($i = ($prev + 1); $i < $commentEnd; $i++) {
Chris@0:                     if ($tokens[($i + 1)]['line'] === $tokens[$commentEnd]['line']) {
Chris@0:                         break;
Chris@0:                     }
Chris@0: 
Chris@0:                     $phpcsFile->fixer->replaceToken($i, '');
Chris@0:                 }
Chris@0: 
Chris@0:                 $phpcsFile->fixer->endChangeset();
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         // The short description of @file comments is one line below.
Chris@0:         if ($tokens[$short]['code'] === T_DOC_COMMENT_TAG && $tokens[$short]['content'] === '@file') {
Chris@0:             $next = $phpcsFile->findNext($empty, ($short + 1), $commentEnd, true);
Chris@0:             if ($next !== false) {
Chris@0:                 $fileShort = $short;
Chris@0:                 $short     = $next;
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         // Do not check defgroup sections, they have no short description. Also don't
Chris@0:         // check PHPUnit tests doc blocks because they might not have a description.
Chris@0:         if (in_array($tokens[$short]['content'], array('@defgroup', '@addtogroup', '@}', '@coversDefaultClass')) === true) {
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         // Check for a comment description.
Chris@0:         if ($tokens[$short]['code'] !== T_DOC_COMMENT_STRING) {
Chris@0:             // JSDoc has many cases of @type declaration that don't have a
Chris@0:             // description.
Chris@0:             if ($phpcsFile->tokenizerType === 'JS') {
Chris@0:                 return;
Chris@0:             }
Chris@0: 
Chris@0:             // PHPUnit test methods are allowed to skip the short description and
Chris@0:             // only provide an @covers annotation.
Chris@0:             if ($tokens[$short]['content'] === '@covers') {
Chris@0:                 return;
Chris@0:             }
Chris@0: 
Chris@0:             $error = 'Missing short description in doc comment';
Chris@0:             $phpcsFile->addError($error, $stackPtr, 'MissingShort');
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         if (isset($fileShort) === true) {
Chris@0:             $start = $fileShort;
Chris@0:         } else {
Chris@0:             $start = $stackPtr;
Chris@0:         }
Chris@0: 
Chris@0:         // No extra newline before short description.
Chris@0:         if ($tokens[$short]['line'] !== ($tokens[$start]['line'] + 1)) {
Chris@0:             $error = 'Doc comment short description must be on the first line';
Chris@0:             $fix   = $phpcsFile->addFixableError($error, $short, 'SpacingBeforeShort');
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->beginChangeset();
Chris@0:                 for ($i = $start; $i < $short; $i++) {
Chris@0:                     if ($tokens[$i]['line'] === $tokens[$start]['line']) {
Chris@0:                         continue;
Chris@0:                     } else if ($tokens[$i]['line'] === $tokens[$short]['line']) {
Chris@0:                         break;
Chris@0:                     }
Chris@0: 
Chris@0:                     $phpcsFile->fixer->replaceToken($i, '');
Chris@0:                 }
Chris@0: 
Chris@0:                 $phpcsFile->fixer->endChangeset();
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         if ($tokens[($short - 1)]['content'] !== ' '
Chris@0:             && strpos($tokens[($short - 1)]['content'], $phpcsFile->eolChar) === false
Chris@0:         ) {
Chris@0:             $error = 'Function comment short description must start with exactly one space';
Chris@0:             $fix   = $phpcsFile->addFixableError($error, $short, 'ShortStartSpace');
Chris@0:             if ($fix === true) {
Chris@0:                 if ($tokens[($short - 1)]['code'] === T_DOC_COMMENT_WHITESPACE) {
Chris@0:                     $phpcsFile->fixer->replaceToken(($short - 1), ' ');
Chris@0:                 } else {
Chris@0:                     $phpcsFile->fixer->addContent(($short - 1), ' ');
Chris@0:                 }
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         // Account for the fact that a short description might cover
Chris@0:         // multiple lines.
Chris@0:         $shortContent = $tokens[$short]['content'];
Chris@0:         $shortEnd     = $short;
Chris@0:         for ($i = ($short + 1); $i < $commentEnd; $i++) {
Chris@0:             if ($tokens[$i]['code'] === T_DOC_COMMENT_STRING) {
Chris@0:                 if ($tokens[$i]['line'] === ($tokens[$shortEnd]['line'] + 1)) {
Chris@0:                     $shortContent .= $tokens[$i]['content'];
Chris@0:                     $shortEnd      = $i;
Chris@0:                 } else {
Chris@0:                     break;
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             if ($tokens[$i]['code'] === T_DOC_COMMENT_TAG) {
Chris@0:                 break;
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         // Remove any trailing white spaces which are detected by other sniffs.
Chris@0:         $shortContent = trim($shortContent);
Chris@0: 
Chris@0:         if (preg_match('|\p{Lu}|u', $shortContent[0]) === 0 && $shortContent !== '{@inheritdoc}'
Chris@0:             // Ignore Features module export files that just use the file name as
Chris@0:             // comment.
Chris@0:             && $shortContent !== basename($phpcsFile->getFilename())
Chris@0:         ) {
Chris@0:             $error = 'Doc comment short description must start with a capital letter';
Chris@0:             // If we cannot capitalize the first character then we don't have a
Chris@0:             // fixable error.
Chris@0:             if ($tokens[$short]['content'] === ucfirst($tokens[$short]['content'])) {
Chris@0:                 $phpcsFile->addError($error, $short, 'ShortNotCapital');
Chris@0:             } else {
Chris@0:                 $fix = $phpcsFile->addFixableError($error, $short, 'ShortNotCapital');
Chris@0:                 if ($fix === true) {
Chris@0:                     $phpcsFile->fixer->replaceToken($short, ucfirst($tokens[$short]['content']));
Chris@0:                 }
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         $lastChar = substr($shortContent, -1);
Chris@0:         if (in_array($lastChar, array('.', '!', '?', ')')) === false && $shortContent !== '{@inheritdoc}'
Chris@0:             // Ignore Features module export files that just use the file name as
Chris@0:             // comment.
Chris@0:             && $shortContent !== basename($phpcsFile->getFilename())
Chris@0:         ) {
Chris@0:             $error = 'Doc comment short description must end with a full stop';
Chris@0:             $fix   = $phpcsFile->addFixableError($error, $shortEnd, 'ShortFullStop');
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->addContent($shortEnd, '.');
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         if ($tokens[$short]['line'] !== $tokens[$shortEnd]['line']) {
Chris@0:             $error = 'Doc comment short description must be on a single line, further text should be a separate paragraph';
Chris@0:             $phpcsFile->addError($error, $shortEnd, 'ShortSingleLine');
Chris@0:         }
Chris@0: 
Chris@0:         $long = $phpcsFile->findNext($empty, ($shortEnd + 1), ($commentEnd - 1), true);
Chris@0:         if ($long === false) {
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         if ($tokens[$long]['code'] === T_DOC_COMMENT_STRING) {
Chris@0:             if ($tokens[$long]['line'] !== ($tokens[$shortEnd]['line'] + 2)) {
Chris@0:                 $error = 'There must be exactly one blank line between descriptions in a doc comment';
Chris@0:                 $fix   = $phpcsFile->addFixableError($error, $long, 'SpacingBetween');
Chris@0:                 if ($fix === true) {
Chris@0:                     $phpcsFile->fixer->beginChangeset();
Chris@0:                     for ($i = ($shortEnd + 1); $i < $long; $i++) {
Chris@0:                         if ($tokens[$i]['line'] === $tokens[$shortEnd]['line']) {
Chris@0:                             continue;
Chris@0:                         } else if ($tokens[$i]['line'] === ($tokens[$long]['line'] - 1)) {
Chris@0:                             break;
Chris@0:                         }
Chris@0: 
Chris@0:                         $phpcsFile->fixer->replaceToken($i, '');
Chris@0:                     }
Chris@0: 
Chris@0:                     $phpcsFile->fixer->endChangeset();
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             if (preg_match('|\p{Lu}|u', $tokens[$long]['content'][0]) === 0
Chris@0:                 && $tokens[$long]['content'] !== ucfirst($tokens[$long]['content'])
Chris@0:             ) {
Chris@0:                 $error = 'Doc comment long description must start with a capital letter';
Chris@0:                 $fix   = $phpcsFile->addFixableError($error, $long, 'LongNotCapital');
Chris@0:                 if ($fix === true) {
Chris@0:                     $phpcsFile->fixer->replaceToken($long, ucfirst($tokens[$long]['content']));
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             // Account for the fact that a description might cover multiple lines.
Chris@0:             $longContent = $tokens[$long]['content'];
Chris@0:             $longEnd     = $long;
Chris@0:             for ($i = ($long + 1); $i < $commentEnd; $i++) {
Chris@0:                 if ($tokens[$i]['code'] === T_DOC_COMMENT_STRING) {
Chris@0:                     if ($tokens[$i]['line'] <= ($tokens[$longEnd]['line'] + 1)) {
Chris@0:                         $longContent .= $tokens[$i]['content'];
Chris@0:                         $longEnd      = $i;
Chris@0:                     } else {
Chris@0:                         break;
Chris@0:                     }
Chris@0:                 }
Chris@0: 
Chris@0:                 if ($tokens[$i]['code'] === T_DOC_COMMENT_TAG) {
Chris@0:                     if ($tokens[$i]['line'] <= ($tokens[$longEnd]['line'] + 1)
Chris@0:                         // Allow link tags within the long comment itself.
Chris@0:                         && ($tokens[$i]['content'] === '@link' || $tokens[$i]['content'] === '@endlink')
Chris@0:                     ) {
Chris@0:                         $longContent .= $tokens[$i]['content'];
Chris@0:                         $longEnd      = $i;
Chris@0:                     } else {
Chris@0:                         break;
Chris@0:                     }
Chris@0:                 }
Chris@0:             }//end for
Chris@0: 
Chris@0:             // Remove any trailing white spaces which are detected by other sniffs.
Chris@0:             $longContent = trim($longContent);
Chris@0: 
Chris@0:             if (preg_match('/[a-zA-Z]$/', $longContent) === 1) {
Chris@0:                 $error = 'Doc comment long description must end with a full stop';
Chris@0:                 $fix   = $phpcsFile->addFixableError($error, $longEnd, 'LongFullStop');
Chris@0:                 if ($fix === true) {
Chris@0:                     $phpcsFile->fixer->addContent($longEnd, '.');
Chris@0:                 }
Chris@0:             }
Chris@0:         }//end if
Chris@0: 
Chris@0:         if (empty($tokens[$commentStart]['comment_tags']) === true) {
Chris@0:             // No tags in the comment.
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         $firstTag = $tokens[$commentStart]['comment_tags'][0];
Chris@0:         $prev     = $phpcsFile->findPrevious($empty, ($firstTag - 1), $stackPtr, true);
Chris@0:         // This does not apply to @file, @code, @link and @endlink tags.
Chris@0:         if ($tokens[$firstTag]['line'] !== ($tokens[$prev]['line'] + 2)
Chris@0:             && isset($fileShort) === false
Chris@0:             && in_array($tokens[$firstTag]['content'], array('@code', '@link', '@endlink')) === false
Chris@0:         ) {
Chris@0:             $error = 'There must be exactly one blank line before the tags in a doc comment';
Chris@0:             $fix   = $phpcsFile->addFixableError($error, $firstTag, 'SpacingBeforeTags');
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->beginChangeset();
Chris@0:                 for ($i = ($prev + 1); $i < $firstTag; $i++) {
Chris@0:                     if ($tokens[$i]['line'] === $tokens[$firstTag]['line']) {
Chris@0:                         break;
Chris@0:                     }
Chris@0: 
Chris@0:                     $phpcsFile->fixer->replaceToken($i, '');
Chris@0:                 }
Chris@0: 
Chris@0:                 $indent = str_repeat(' ', $tokens[$stackPtr]['column']);
Chris@0:                 $phpcsFile->fixer->addContent($prev, $phpcsFile->eolChar.$indent.'*'.$phpcsFile->eolChar);
Chris@0:                 $phpcsFile->fixer->endChangeset();
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@0:         // Break out the tags into groups and check alignment within each.
Chris@0:         // A tag group is one where there are no blank lines between tags.
Chris@0:         // The param tag group is special as it requires all @param tags to be inside.
Chris@0:         $tagGroups    = array();
Chris@0:         $groupid      = 0;
Chris@0:         $paramGroupid = null;
Chris@0:         $currentTag   = null;
Chris@0:         $previousTag  = null;
Chris@0:         $isNewGroup   = null;
Chris@0:         foreach ($tokens[$commentStart]['comment_tags'] as $pos => $tag) {
Chris@0:             if ($pos > 0) {
Chris@0:                 $prev = $phpcsFile->findPrevious(
Chris@0:                     T_DOC_COMMENT_STRING,
Chris@0:                     ($tag - 1),
Chris@0:                     $tokens[$commentStart]['comment_tags'][($pos - 1)]
Chris@0:                 );
Chris@0: 
Chris@0:                 if ($prev === false) {
Chris@0:                     $prev = $tokens[$commentStart]['comment_tags'][($pos - 1)];
Chris@0:                 }
Chris@0: 
Chris@0:                 $isNewGroup = $tokens[$prev]['line'] !== ($tokens[$tag]['line'] - 1);
Chris@0:                 if ($isNewGroup === true) {
Chris@0:                     $groupid++;
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             $currentTag = $tokens[$tag]['content'];
Chris@0:             if ($currentTag === '@param') {
Chris@0:                 if (($paramGroupid === null
Chris@0:                     && empty($tagGroups[$groupid]) === false)
Chris@0:                     || ($paramGroupid !== null
Chris@0:                     && $paramGroupid !== $groupid)
Chris@0:                 ) {
Chris@0:                     $error = 'Parameter tags must be grouped together in a doc comment';
Chris@0:                     $phpcsFile->addError($error, $tag, 'ParamGroup');
Chris@0:                 }
Chris@0: 
Chris@0:                 if ($paramGroupid === null) {
Chris@0:                     $paramGroupid = $groupid;
Chris@0:                 }
Chris@0: 
Chris@0:                 // The @param, @return and @throws tag sections should be
Chris@0:                 // separated by a blank line both before and after these sections.
Chris@0:             } else if ($isNewGroup === false
Chris@0:                 && (in_array($currentTag, array('@param', '@return', '@throws')) === true
Chris@0:                 || in_array($previousTag, array('@param', '@return', '@throws')) === true)
Chris@0:                 && $previousTag !== $currentTag
Chris@0:             ) {
Chris@0:                 $error = 'Separate the %s and %s sections by a blank line.';
Chris@0:                 $fix   = $phpcsFile->addFixableError($error, $tag, 'TagGroupSpacing', array($previousTag, $currentTag));
Chris@0:                 if ($fix === true) {
Chris@0:                     $phpcsFile->fixer->replaceToken(($tag - 1), "\n".str_repeat(' ', ($tokens[$tag]['column'] - 3)).'* ');
Chris@0:                 }
Chris@0:             }//end if
Chris@0: 
Chris@0:             $previousTag           = $currentTag;
Chris@0:             $tagGroups[$groupid][] = $tag;
Chris@0:         }//end foreach
Chris@0: 
Chris@0:         foreach ($tagGroups as $group) {
Chris@0:             $maxLength = 0;
Chris@0:             $paddings  = array();
Chris@0:             foreach ($group as $pos => $tag) {
Chris@0:                 $tagLength = strlen($tokens[$tag]['content']);
Chris@0:                 if ($tagLength > $maxLength) {
Chris@0:                     $maxLength = $tagLength;
Chris@0:                 }
Chris@0: 
Chris@0:                 // Check for a value. No value means no padding needed.
Chris@0:                 $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd);
Chris@0:                 if ($string !== false && $tokens[$string]['line'] === $tokens[$tag]['line']) {
Chris@0:                     $paddings[$tag] = strlen($tokens[($tag + 1)]['content']);
Chris@0:                 }
Chris@0:             }
Chris@0: 
Chris@0:             // Check that there was single blank line after the tag block
Chris@0:             // but account for a multi-line tag comments.
Chris@0:             $lastTag = $group[$pos];
Chris@0:             $next    = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($lastTag + 3), $commentEnd);
Chris@0:             if ($next !== false) {
Chris@0:                 $prev = $phpcsFile->findPrevious(array(T_DOC_COMMENT_TAG, T_DOC_COMMENT_STRING), ($next - 1), $commentStart);
Chris@0:                 if ($tokens[$next]['line'] !== ($tokens[$prev]['line'] + 2)) {
Chris@0:                     $error = 'There must be a single blank line after a tag group';
Chris@0:                     $fix   = $phpcsFile->addFixableError($error, $lastTag, 'SpacingAfterTagGroup');
Chris@0:                     if ($fix === true) {
Chris@0:                         $phpcsFile->fixer->beginChangeset();
Chris@0:                         for ($i = ($prev + 1); $i < $next; $i++) {
Chris@0:                             if ($tokens[$i]['line'] === $tokens[$next]['line']) {
Chris@0:                                 break;
Chris@0:                             }
Chris@0: 
Chris@0:                             $phpcsFile->fixer->replaceToken($i, '');
Chris@0:                         }
Chris@0: 
Chris@0:                         $indent = str_repeat(' ', $tokens[$stackPtr]['column']);
Chris@0:                         $phpcsFile->fixer->addContent($prev, $phpcsFile->eolChar.$indent.'*'.$phpcsFile->eolChar);
Chris@0:                         $phpcsFile->fixer->endChangeset();
Chris@0:                     }
Chris@0:                 }
Chris@0:             }//end if
Chris@0: 
Chris@0:             // Now check paddings.
Chris@0:             foreach ($paddings as $tag => $padding) {
Chris@0:                 if ($padding !== 1) {
Chris@0:                     $error = 'Tag value indented incorrectly; expected 1 space but found %s';
Chris@0:                     $data  = array($padding);
Chris@0: 
Chris@0:                     $fix = $phpcsFile->addFixableError($error, ($tag + 1), 'TagValueIndent', $data);
Chris@0:                     if ($fix === true) {
Chris@0:                         $phpcsFile->fixer->replaceToken(($tag + 1), ' ');
Chris@0:                     }
Chris@0:                 }
Chris@0:             }
Chris@0:         }//end foreach
Chris@0: 
Chris@0:         // If there is a param group, it needs to be first; with the exception of
Chris@0:         // @code, @todo and link tags.
Chris@0:         if ($paramGroupid !== null && $paramGroupid !== 0
Chris@0:             && in_array($tokens[$tokens[$commentStart]['comment_tags'][0]]['content'], array('@code', '@todo', '@link', '@endlink', '@codingStandardsIgnoreStart')) === false
Chris@0:             // In JSDoc we can have many other valid tags like @function or
Chris@0:             // @constructor before the param tags.
Chris@0:             && $phpcsFile->tokenizerType !== 'JS'
Chris@0:         ) {
Chris@0:             $error = 'Parameter tags must be defined first in a doc comment';
Chris@0:             $phpcsFile->addError($error, $tagGroups[$paramGroupid][0], 'ParamNotFirst');
Chris@0:         }
Chris@0: 
Chris@0:         $foundTags = array();
Chris@0:         foreach ($tokens[$stackPtr]['comment_tags'] as $pos => $tag) {
Chris@0:             $tagName = $tokens[$tag]['content'];
Chris@0:             if (isset($foundTags[$tagName]) === true) {
Chris@0:                 $lastTag = $tokens[$stackPtr]['comment_tags'][($pos - 1)];
Chris@0:                 if ($tokens[$lastTag]['content'] !== $tagName) {
Chris@0:                     $error = 'Tags must be grouped together in a doc comment';
Chris@0:                     $phpcsFile->addError($error, $tag, 'TagsNotGrouped');
Chris@0:                 }
Chris@0: 
Chris@0:                 continue;
Chris@0:             }
Chris@0: 
Chris@0:             $foundTags[$tagName] = true;
Chris@0:         }
Chris@0: 
Chris@0:     }//end process()
Chris@0: 
Chris@0: 
Chris@0: }//end class