diff options
Diffstat (limited to 'PMAStandard/Sniffs/Commenting/FileCommentSniff.php')
| -rw-r--r-- | PMAStandard/Sniffs/Commenting/FileCommentSniff.php | 830 |
1 files changed, 294 insertions, 536 deletions
diff --git a/PMAStandard/Sniffs/Commenting/FileCommentSniff.php b/PMAStandard/Sniffs/Commenting/FileCommentSniff.php index fcca9928bd..19872af4c2 100644 --- a/PMAStandard/Sniffs/Commenting/FileCommentSniff.php +++ b/PMAStandard/Sniffs/Commenting/FileCommentSniff.php @@ -8,36 +8,21 @@ * @package PHP_CodeSniffer * @author Greg Sherwood <gsherwood@squiz.net> * @author Marc McIntyre <mmcintyre@squiz.net> - * @copyright 2006-2011 Squiz Pty Ltd (ABN 77 084 670 600) - * @license http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence + * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600) + * @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence * @link http://pear.php.net/package/PHP_CodeSniffer */ -if (class_exists('PHP_CodeSniffer_CommentParser_ClassCommentParser', true) === false) { - throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_CommentParser_ClassCommentParser not found'); -} - /** * Parses and verifies the doc comments for files. * - * Verifies that : - * <ul> - * <li>A doc comment exists.</li> - * <li>There is a blank newline after the short description.</li> - * <li>There is a blank newline between the long and short description.</li> - * <li>There is a blank newline between the long description and tags.</li> - * <li>Check the order of the tags.</li> - * <li>Check the indentation of each tag.</li> - * <li>Check required and optional tags and the format of their content.</li> - * </ul> - * * @category PHP * @package PHP_CodeSniffer * @author Greg Sherwood <gsherwood@squiz.net> * @author Marc McIntyre <mmcintyre@squiz.net> - * @copyright 2006-2011 Squiz Pty Ltd (ABN 77 084 670 600) - * @license http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence - * @version Release: 1.3.3 + * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600) + * @license https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence + * @version Release: 2.2.0 * @link http://pear.php.net/package/PHP_CodeSniffer */ @@ -45,81 +30,56 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ { /** - * The header comment parser for the current file. - * - * @var PHP_CodeSniffer_Comment_Parser_ClassCommentParser - */ - protected $commentParser = null; - - /** - * The current PHP_CodeSniffer_File object we are processing. - * - * @var PHP_CodeSniffer_File - */ - protected $currentFile = null; - - /** * Tags in correct order and related info. * * @var array */ protected $tags = array( - 'category' => array( - 'required' => false, - 'allow_multiple' => false, - 'order_text' => 'precedes @package', - ), - 'package' => array( - 'required' => true, - 'allow_multiple' => false, - 'order_text' => 'follows @category', - ), - 'subpackage' => array( - 'required' => false, - 'allow_multiple' => false, - 'order_text' => 'follows @package', - ), - 'author' => array( - 'required' => false, - 'allow_multiple' => true, - 'order_text' => 'follows @subpackage (if used) or @package', - ), - 'copyright' => array( - 'required' => false, - 'allow_multiple' => true, - 'order_text' => 'follows @author', - ), - 'license' => array( - 'required' => false, - 'allow_multiple' => false, - 'order_text' => 'follows @copyright (if used) or @author', - ), - 'version' => array( - 'required' => false, - 'allow_multiple' => false, - 'order_text' => 'follows @license', - ), - 'link' => array( - 'required' => false, - 'allow_multiple' => true, - 'order_text' => 'follows @version', - ), - 'see' => array( - 'required' => false, - 'allow_multiple' => true, - 'order_text' => 'follows @link', - ), - 'since' => array( - 'required' => false, - 'allow_multiple' => false, - 'order_text' => 'follows @see (if used) or @link', - ), - 'deprecated' => array( - 'required' => false, - 'allow_multiple' => false, - 'order_text' => 'follows @since (if used) or @see (if used) or @link', - ), - ); + '@category' => array( + 'required' => false, + 'allow_multiple' => false, + ), + '@package' => array( + 'required' => true, + 'allow_multiple' => false, + ), + '@subpackage' => array( + 'required' => false, + 'allow_multiple' => false, + ), + '@author' => array( + 'required' => false, + 'allow_multiple' => true, + ), + '@copyright' => array( + 'required' => false, + 'allow_multiple' => true, + ), + '@license' => array( + 'required' => false, + 'allow_multiple' => false, + ), + '@version' => array( + 'required' => false, + 'allow_multiple' => false, + ), + '@link' => array( + 'required' => false, + 'allow_multiple' => true, + ), + '@see' => array( + 'required' => false, + 'allow_multiple' => true, + ), + '@since' => array( + 'required' => false, + 'allow_multiple' => false, + ), + '@deprecated' => array( + 'required' => false, + 'allow_multiple' => false, + ), + ); /** @@ -141,30 +101,19 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ * @param int $stackPtr The position of the current token * in the stack passed in $tokens. * - * @return void + * @return int */ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr) { - $this->currentFile = $phpcsFile; - - // We are only interested if this is the first open tag. - if ($stackPtr !== 0) { - if ($phpcsFile->findPrevious(T_OPEN_TAG, ($stackPtr - 1)) !== false) { - return; - } - } - $tokens = $phpcsFile->getTokens(); // Find the next non whitespace token. - $commentStart - = $phpcsFile->findNext(T_WHITESPACE, ($stackPtr + 1), null, true); + $commentStart = $phpcsFile->findNext(T_WHITESPACE, ($stackPtr + 1), null, true); // Allow declare() statements at the top of the file. if ($tokens[$commentStart]['code'] === T_DECLARE) { - $semicolon = $phpcsFile->findNext(T_SEMICOLON, ($commentStart + 1)); - $commentStart - = $phpcsFile->findNext(T_WHITESPACE, ($semicolon + 1), null, true); + $semicolon = $phpcsFile->findNext(T_SEMICOLON, ($commentStart + 1)); + $commentStart = $phpcsFile->findNext(T_WHITESPACE, ($semicolon + 1), null, true); } // Ignore vim header. @@ -186,133 +135,27 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ if ($tokens[$commentStart]['code'] === T_CLOSE_TAG) { // We are only interested if this is the first open tag. - return; + return ($phpcsFile->numTokens + 1); } else if ($tokens[$commentStart]['code'] === T_COMMENT) { $error = 'You must use "/**" style comments for a file comment'; $phpcsFile->addError($error, $errorToken, 'WrongStyle'); - return; + $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'yes'); + return ($phpcsFile->numTokens + 1); } else if ($commentStart === false - || $tokens[$commentStart]['code'] !== T_DOC_COMMENT + || $tokens[$commentStart]['code'] !== T_DOC_COMMENT_OPEN_TAG ) { $phpcsFile->addError('Missing file doc comment', $errorToken, 'Missing'); - return; + $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'no'); + return ($phpcsFile->numTokens + 1); } else { + $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'yes'); + } - // Extract the header comment docblock. - $commentEnd = $phpcsFile->findNext( - T_DOC_COMMENT, - ($commentStart + 1), - null, - true - ); - - $commentEnd--; - - // Check if there is only 1 doc comment between the - // open tag and class token. - $nextToken = array( - T_ABSTRACT, - T_CLASS, - T_FUNCTION, - T_DOC_COMMENT, - ); - - $commentNext = $phpcsFile->findNext($nextToken, ($commentEnd + 1)); - if ($commentNext !== false - && $tokens[$commentNext]['code'] !== T_DOC_COMMENT - ) { - // Found a class token right after comment doc block. - $newlineToken = $phpcsFile->findNext( - T_WHITESPACE, - ($commentEnd + 1), - $commentNext, - false, - $phpcsFile->eolChar - ); - - if ($newlineToken !== false) { - $newlineToken = $phpcsFile->findNext( - T_WHITESPACE, - ($newlineToken + 1), - $commentNext, - false, - $phpcsFile->eolChar - ); - - if ($newlineToken === false) { - // No blank line between the class token and the doc block. - // The doc block is most likely a class comment. - $error = 'Missing file doc comment'; - $phpcsFile->addError($error, $errorToken, 'Missing'); - return; - } - } - }//end if - - $comment = $phpcsFile->getTokensAsString( - $commentStart, - ($commentEnd - $commentStart + 1) - ); - - // Parse the header comment docblock. - try { - $this->commentParser = new PHP_CodeSniffer_CommentParser_ClassCommentParser($comment, $phpcsFile); - $this->commentParser->parse(); - } catch (PHP_CodeSniffer_CommentParser_ParserException $e) { - $line = ($e->getLineWithinComment() + $commentStart); - $phpcsFile->addError($e->getMessage(), $line, 'FailedParse'); - return; - } - - $comment = $this->commentParser->getComment(); - if (is_null($comment) === true) { - $error = 'File doc comment is empty'; - $phpcsFile->addError($error, $commentStart, 'Empty'); - return; - } - - // No extra newline before short description. - $short = $comment->getShortComment(); - $newlineCount = 0; - $newlineSpan = strspn($short, $phpcsFile->eolChar); - if ($short !== '' && $newlineSpan > 0) { - $error = 'Extra newline(s) found before file comment short description'; - $phpcsFile->addError($error, ($commentStart + 1), 'SpacingBefore'); - } - - $newlineCount = (substr_count($short, $phpcsFile->eolChar) + 1); - - // Exactly one blank line between short and long description. - $long = $comment->getLongComment(); - if (empty($long) === false) { - $between = $comment->getWhiteSpaceBetween(); - $newlineBetween = substr_count($between, $phpcsFile->eolChar); - if ($newlineBetween !== 2) { - $error = 'There must be exactly one blank line between descriptions in file comment'; - $phpcsFile->addError($error, ($commentStart + $newlineCount + 1), 'DescriptionSpacing'); - } - - $newlineCount += $newlineBetween; - } - - // Exactly one blank line before tags. - $tags = $this->commentParser->getTagOrders(); - if (count($tags) > 1) { - $newlineSpan = $comment->getNewlineAfter(); - if ($newlineSpan !== 2) { - $error = 'There must be exactly one blank line before the tags in file comment'; - if ($long !== '') { - $newlineCount += (substr_count($long, $phpcsFile->eolChar) - $newlineSpan + 1); - } - - $phpcsFile->addError($error, ($commentStart + $newlineCount), 'SpacingBeforeTags'); - $short = rtrim($short, $phpcsFile->eolChar.' '); - } - } + // Check each tag. + $this->processTags($phpcsFile, $stackPtr, $commentStart); - // Check each tag. - $this->processTags($commentStart, $commentEnd); - }//end if + // Ignore the rest of the file. + return ($phpcsFile->numTokens + 1); }//end process() @@ -320,233 +163,140 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ /** * Processes each required or optional tag. * - * @param int $commentStart Position in the stack where the comment started. - * @param int $commentEnd Position in the stack where the comment ended. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param int $stackPtr The position of the current token + * in the stack passed in $tokens. + * @param int $commentStart Position in the stack where the comment started. * * @return void */ - protected function processTags($commentStart, $commentEnd) + protected function processTags(PHP_CodeSniffer_File $phpcsFile, $stackPtr, $commentStart) { - $docBlock = (get_class($this) === 'PMAStandard_Sniffs_Commenting_FileCommentSniff') ? 'file' : 'class'; - $foundTags = $this->commentParser->getTagOrders(); - $orderIndex = 0; - $indentation = array(); - $longestTag = 0; - $errorPos = 0; - - foreach ($this->tags as $tag => $info) { - - // Required tag missing. - if ($info['required'] === true && in_array($tag, $foundTags) === false) { - $error = 'Missing @%s tag in %s comment'; - $data = array( - $tag, - $docBlock, - ); - $this->currentFile->addError($error, $commentEnd, 'MissingTag', $data); - continue; - } + $tokens = $phpcsFile->getTokens(); - // Get the line number for current tag. - $tagName = ucfirst($tag); - if ($info['allow_multiple'] === true) { - $tagName .= 's'; - } + if (get_class($this) === 'PMAStandard_Sniffs_Commenting_FileCommentSniff') { + $docBlock = 'file'; + } else { + $docBlock = 'class'; + } - $getMethod = 'get'.$tagName; - $tagElement = $this->commentParser->$getMethod(); - if (is_null($tagElement) === true || empty($tagElement) === true) { + $commentEnd = $tokens[$commentStart]['comment_closer']; + + $foundTags = array(); + $tagTokens = array(); + foreach ($tokens[$commentStart]['comment_tags'] as $tag) { + $name = $tokens[$tag]['content']; + if (isset($this->tags[$name]) === false) { continue; } - $errorPos = $commentStart; - if (is_array($tagElement) === false) { - $errorPos = ($commentStart + $tagElement->getLine()); + if ($this->tags[$name]['allow_multiple'] === false && isset($tagTokens[$name]) === true) { + $error = 'Only one %s tag is allowed in a %s comment'; + $data = array( + $name, + $docBlock, + ); + $phpcsFile->addError($error, $tag, 'Duplicate'.ucfirst($name).'Tag', $data); } - // Get the tag order. - $foundIndexes = array_keys($foundTags, $tag); + $foundTags[] = $name; + $tagTokens[$name][] = $tag; + + $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd); + if ($string === false || $tokens[$string]['line'] !== $tokens[$tag]['line']) { + $error = 'Content missing for %s tag in %s comment'; + $data = array( + $name, + $docBlock, + ); + $phpcsFile->addError($error, $tag, 'Empty'.ucfirst($name).'Tag', $data); + continue; + } + }//end foreach - if (count($foundIndexes) > 1) { - // Multiple occurance not allowed. - if ($info['allow_multiple'] === false) { - $error = 'Only 1 @%s tag is allowed in a %s comment'; + // Check if the tags are in the correct position. + $pos = 0; + foreach ($this->tags as $tag => $tagData) { + if (isset($tagTokens[$tag]) === false) { + if ($tagData['required'] === true) { + $error = 'Missing %s tag in %s comment'; $data = array( $tag, $docBlock, ); - $this->currentFile->addError($error, $errorPos, 'DuplicateTag', $data); - } else { - // Make sure same tags are grouped together. - $i = 0; - $count = $foundIndexes[0]; - foreach ($foundIndexes as $index) { - if ($index !== $count) { - $errorPosIndex - = ($errorPos + $tagElement[$i]->getLine()); - $error = '@%s tags must be grouped together'; - $data = array($tag); - $this->currentFile->addError($error, $errorPosIndex, 'TagsNotGrouped', $data); - } - - $i++; - $count++; - } + $phpcsFile->addError($error, $commentEnd, 'Missing'.ucfirst(substr($tag, 1)).'Tag', $data); } - }//end if - // Check tag order. - if ($foundIndexes[0] > $orderIndex) { - $orderIndex = $foundIndexes[0]; + continue; } else { - if (is_array($tagElement) === true && empty($tagElement) === false) { - $errorPos += $tagElement[0]->getLine(); + $method = 'process'.substr($tag, 1); + if (method_exists($this, $method) === true) { + // Process each tag if a method is defined. + call_user_func(array($this, $method), $phpcsFile, $tagTokens[$tag]); } - - $error = 'The @%s tag is in the wrong order; the tag %s'; - $data = array( - $tag, - $info['order_text'], - ); - $this->currentFile->addError($error, $errorPos, 'WrongTagOrder', $data); } - // Store the indentation for checking. - $len = strlen($tag); - if ($len > $longestTag) { - $longestTag = $len; + if (isset($foundTags[$pos]) === false) { + break; } - if (is_array($tagElement) === true) { - foreach ($tagElement as $key => $element) { - $indentation[] = array( - 'tag' => $tag, - 'space' => $this->getIndentation($tag, $element), - 'line' => $element->getLine(), - ); - } - } else { - $indentation[] = array( - 'tag' => $tag, - 'space' => $this->getIndentation($tag, $tagElement), - ); + if ($foundTags[$pos] !== $tag) { + $error = 'The tag in position %s should be the %s tag'; + $data = array( + ($pos + 1), + $tag, + ); + $phpcsFile->addError($error, $tokens[$commentStart]['comment_tags'][$pos], ucfirst($tag).'TagOrder', $data); } - $method = 'process'.$tagName; - if (method_exists($this, $method) === true) { - // Process each tag if a method is defined. - call_user_func(array($this, $method), $errorPos); - } else { - if (is_array($tagElement) === true) { - foreach ($tagElement as $key => $element) { - $element->process( - $this->currentFile, - $commentStart, - $docBlock - ); - } - } else { - $tagElement->process( - $this->currentFile, - $commentStart, - $docBlock - ); - } + // Account for multiple tags. + $pos++; + while (isset($foundTags[$pos]) === true && $foundTags[$pos] === $tag) { + $pos++; } }//end foreach - foreach ($indentation as $indentInfo) { - if ($indentInfo['space'] !== 0 - && $indentInfo['space'] !== ($longestTag + 1) - ) { - $expected = (($longestTag - strlen($indentInfo['tag'])) + 1); - $space = ($indentInfo['space'] - strlen($indentInfo['tag'])); - $error = '@%s tag comment indented incorrectly; expected %s spaces but found %s'; - $data = array( - $indentInfo['tag'], - $expected, - $space, - ); - - $getTagMethod = 'get'.ucfirst($indentInfo['tag']); - - if ($this->tags[$indentInfo['tag']]['allow_multiple'] === true) { - $line = $indentInfo['line']; - } else { - $tagElem = $this->commentParser->$getTagMethod(); - $line = $tagElem->getLine(); - } - - $this->currentFile->addError($error, ($commentStart + $line), 'TagIndent', $data); - } - } - }//end processTags() /** - * Get the indentation information of each tag. - * - * @param string $tagName The name of the - * doc comment - * element. - * @param PHP_CodeSniffer_CommentParser_DocElement $tagElement The doc comment - * element. - * - * @return string|int - */ - protected function getIndentation($tagName, $tagElement) - { - if ($tagElement instanceof PHP_CodeSniffer_CommentParser_SingleElement) { - if ($tagElement->getContent() !== '') { - return (strlen($tagName) + substr_count($tagElement->getWhitespaceBeforeContent(), ' ')); - } - } else if ($tagElement instanceof PHP_CodeSniffer_CommentParser_PairElement) { - if ($tagElement->getValue() !== '') { - return (strlen($tagName) + substr_count($tagElement->getWhitespaceBeforeValue(), ' ')); - } - } - - return 0; - - }//end getIndentation() - - - /** * Process the category tag. * - * @param int $errorPos The line number where the error occurs. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processCategory($errorPos) + protected function processCategory(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $category = $this->commentParser->getCategory(); - if ($category !== null) { - $content = $category->getContent(); - if ($content !== '') { - if (PHP_CodeSniffer::isUnderscoreName($content) !== true) { - $newContent = str_replace(' ', '_', $content); - $nameBits = explode('_', $newContent); - $firstBit = array_shift($nameBits); - $newName = ucfirst($firstBit).'_'; - foreach ($nameBits as $bit) { + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } + + $content = $tokens[($tag + 2)]['content']; + if (PHP_CodeSniffer::isUnderscoreName($content) !== true) { + $newContent = str_replace(' ', '_', $content); + $nameBits = explode('_', $newContent); + $firstBit = array_shift($nameBits); + $newName = ucfirst($firstBit).'_'; + foreach ($nameBits as $bit) { + if ($bit !== '') { $newName .= ucfirst($bit).'_'; } - - $error = 'Category name "%s" is not valid; consider "%s" instead'; - $validName = trim($newName, '_'); - $data = array( - $content, - $validName, - ); - $this->currentFile->addError($error, $errorPos, 'InvalidCategory', $data); } - } else { - $error = '@category tag must contain a name'; - $this->currentFile->addError($error, $errorPos, 'EmptyCategory'); + + $error = 'Category name "%s" is not valid; consider "%s" instead'; + $validName = trim($newName, '_'); + $data = array( + $content, + $validName, + ); + $phpcsFile->addError($error, $tag, 'InvalidCategory', $data); } - } + }//end foreach }//end processCategory() @@ -554,38 +304,45 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ /** * Process the package tag. * - * @param int $errorPos The line number where the error occurs. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processPackage($errorPos) + protected function processPackage(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $package = $this->commentParser->getPackage(); - if ($package !== null) { - $content = $package->getContent(); - if ($content !== '') { - if (PHP_CodeSniffer::isUnderscoreName($content) !== true) { - $newContent = str_replace(' ', '_', $content); - $nameBits = explode('_', $newContent); - $firstBit = array_shift($nameBits); - $newName = strtoupper($firstBit{0}).substr($firstBit, 1).'_'; - foreach ($nameBits as $bit) { - $newName .= strtoupper($bit{0}).substr($bit, 1).'_'; - } + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } - $error = 'Package name "%s" is not valid; consider "%s" instead'; - $validName = trim($newName, '_'); - $data = array( - $content, - $validName, - ); - $this->currentFile->addError($error, $errorPos, 'InvalidPackage', $data); + $content = $tokens[($tag + 2)]['content']; + if (PHP_CodeSniffer::isUnderscoreName($content) === true) { + continue; + } + + $newContent = str_replace(' ', '_', $content); + $newContent = trim($newContent, '_'); + $newContent = preg_replace('/[^A-Za-z_]/', '', $newContent); + $nameBits = explode('_', $newContent); + $firstBit = array_shift($nameBits); + $newName = strtoupper($firstBit{0}).substr($firstBit, 1).'_'; + foreach ($nameBits as $bit) { + if ($bit !== '') { + $newName .= strtoupper($bit{0}).substr($bit, 1).'_'; } - } else { - $error = '@package tag must contain a name'; - $this->currentFile->addError($error, $errorPos, 'EmptyPackage'); } - } + + $error = 'Package name "%s" is not valid; consider "%s" instead'; + $validName = trim($newName, '_'); + $data = array( + $content, + $validName, + ); + $phpcsFile->addError($error, $tag, 'InvalidPackage', $data); + }//end foreach }//end processPackage() @@ -593,38 +350,43 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ /** * Process the subpackage tag. * - * @param int $errorPos The line number where the error occurs. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processSubpackage($errorPos) + protected function processSubpackage(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $package = $this->commentParser->getSubpackage(); - if ($package !== null) { - $content = $package->getContent(); - if ($content !== '') { - if (PHP_CodeSniffer::isUnderscoreName($content) !== true) { - $newContent = str_replace(' ', '_', $content); - $nameBits = explode('_', $newContent); - $firstBit = array_shift($nameBits); - $newName = strtoupper($firstBit{0}).substr($firstBit, 1).'_'; - foreach ($nameBits as $bit) { - $newName .= strtoupper($bit{0}).substr($bit, 1).'_'; - } + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } - $error = 'Subpackage name "%s" is not valid; consider "%s" instead'; - $validName = trim($newName, '_'); - $data = array( - $content, - $validName, - ); - $this->currentFile->addError($error, $errorPos, 'InvalidSubpackage', $data); + $content = $tokens[($tag + 2)]['content']; + if (PHP_CodeSniffer::isUnderscoreName($content) === true) { + continue; + } + + $newContent = str_replace(' ', '_', $content); + $nameBits = explode('_', $newContent); + $firstBit = array_shift($nameBits); + $newName = strtoupper($firstBit{0}).substr($firstBit, 1).'_'; + foreach ($nameBits as $bit) { + if ($bit !== '') { + $newName .= strtoupper($bit{0}).substr($bit, 1).'_'; } - } else { - $error = '@subpackage tag must contain a name'; - $this->currentFile->addError($error, $errorPos, 'EmptySubpackage'); } - } + + $error = 'Subpackage name "%s" is not valid; consider "%s" instead'; + $validName = trim($newName, '_'); + $data = array( + $content, + $validName, + ); + $phpcsFile->addError($error, $tag, 'InvalidSubpackage', $data); + }//end foreach }//end processSubpackage() @@ -632,102 +394,97 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ /** * Process the author tag(s) that this header comment has. * - * This function is different from other _process functions - * as $authors is an array of SingleElements, so we work out - * the errorPos for each element separately - * - * @param int $commentStart The position in the stack where - * the comment started. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processAuthors($commentStart) + protected function processAuthor(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $authors = $this->commentParser->getAuthors(); - // Report missing return. - if (empty($authors) === false) { - foreach ($authors as $author) { - $errorPos = ($commentStart + $author->getLine()); - $content = $author->getContent(); - if ($content !== '') { - $local = '\da-zA-Z-_+'; - // Dot character cannot be the first or last character - // in the local-part. - $localMiddle = $local.'.\w'; - if (preg_match('/^([^<]*)\s+<(['.$local.']['.$localMiddle.']*['.$local.']@[\da-zA-Z][-.\w]*[\da-zA-Z]\.[a-zA-Z]{2,7})>$/', $content) === 0) { - $error = 'Content of the @author tag must be in the form "Display Name <username@example.com>"'; - $this->currentFile->addError($error, $errorPos, 'InvalidAuthors'); - } - } else { - $error = 'Content missing for @author tag in %s comment'; - $docBlock = (get_class($this) === 'PMAStandard_Sniffs_Commenting_FileCommentSniff') ? 'file' : 'class'; - $data = array($docBlock); - $this->currentFile->addError($error, $errorPos, 'EmptyAuthors', $data); - } + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } + + $content = $tokens[($tag + 2)]['content']; + $local = '\da-zA-Z-_+'; + // Dot character cannot be the first or last character in the local-part. + $localMiddle = $local.'.\w'; + if (preg_match('/^([^<]*)\s+<(['.$local.'](['.$localMiddle.']*['.$local.'])*@[\da-zA-Z][-.\w]*[\da-zA-Z]\.[a-zA-Z]{2,7})>$/', $content) === 0) { + $error = 'Content of the @author tag must be in the form "Display Name <username@example.com>"'; + $phpcsFile->addError($error, $tag, 'InvalidAuthors'); } } - }//end processAuthors() + }//end processAuthor() /** * Process the copyright tags. * - * @param int $commentStart The position in the stack where - * the comment started. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processCopyrights($commentStart) + protected function processCopyright(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $copyrights = $this->commentParser->getCopyrights(); - foreach ($copyrights as $copyright) { - $errorPos = ($commentStart + $copyright->getLine()); - $content = $copyright->getContent(); - if ($content !== '') { - $matches = array(); - if (preg_match('/^([0-9]{4})((.{1})([0-9]{4}))? (.+)$/', $content, $matches) !== 0) { - // Check earliest-latest year order. - if ($matches[3] !== '') { - if ($matches[3] !== '-') { - $error = 'A hyphen must be used between the earliest and latest year'; - $this->currentFile->addError($error, $errorPos, 'CopyrightHyphen'); - } - - if ($matches[4] !== '' && $matches[4] < $matches[1]) { - $error = "Invalid year span \"$matches[1]$matches[3]$matches[4]\" found; consider \"$matches[4]-$matches[1]\" instead"; - $this->currentFile->addWarning($error, $errorPos, 'InvalidCopyright'); - } + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } + + $content = $tokens[($tag + 2)]['content']; + $matches = array(); + if (preg_match('/^([0-9]{4})((.{1})([0-9]{4}))? (.+)$/', $content, $matches) !== 0) { + // Check earliest-latest year order. + if ($matches[3] !== '') { + if ($matches[3] !== '-') { + $error = 'A hyphen must be used between the earliest and latest year'; + $phpcsFile->addError($error, $tag, 'CopyrightHyphen'); + } + + if ($matches[4] !== '' && $matches[4] < $matches[1]) { + $error = "Invalid year span \"$matches[1]$matches[3]$matches[4]\" found; consider \"$matches[4]-$matches[1]\" instead"; + $phpcsFile->addWarning($error, $tag, 'InvalidCopyright'); } - } else { - $error = '@copyright tag must contain a year and the name of the copyright holder'; - $this->currentFile->addError($error, $errorPos, 'EmptyCopyright'); } } else { $error = '@copyright tag must contain a year and the name of the copyright holder'; - $this->currentFile->addError($error, $errorPos, 'EmptyCopyright'); - }//end if - }//end if + $phpcsFile->addError($error, $tag, 'IncompleteCopyright'); + } + }//end foreach - }//end processCopyrights() + }//end processCopyright() /** * Process the license tag. * - * @param int $errorPos The line number where the error occurs. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processLicense($errorPos) + protected function processLicense(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $license = $this->commentParser->getLicense(); - if ($license !== null) { - $value = $license->getValue(); - $comment = $license->getComment(); - if ($value === '' || $comment === '') { + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } + + $content = $tokens[($tag + 2)]['content']; + $matches = array(); + preg_match('/^([^\s]+)\s+(.*)/', $content, $matches); + if (count($matches) !== 3) { $error = '@license tag must contain a URL and a license name'; - $this->currentFile->addError($error, $errorPos, 'EmptyLicense'); + $phpcsFile->addError($error, $tag, 'IncompleteLicense'); } } @@ -737,26 +494,29 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ /** * Process the version tag. * - * @param int $errorPos The line number where the error occurs. + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param array $tags The tokens for these tags. * * @return void */ - protected function processVersion($errorPos) + protected function processVersion(PHP_CodeSniffer_File $phpcsFile, array $tags) { - $version = $this->commentParser->getVersion(); - if ($version !== null) { - $content = $version->getContent(); - $matches = array(); - if (empty($content) === true) { - $error = 'Content missing for @version tag in file comment'; - $this->currentFile->addError($error, $errorPos, 'EmptyVersion'); - } else if (strstr($content, 'CVS:') === false + $tokens = $phpcsFile->getTokens(); + foreach ($tags as $tag) { + if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) { + // No content. + continue; + } + + $content = $tokens[($tag + 2)]['content']; + if (strstr($content, 'CVS:') === false && strstr($content, 'SVN:') === false && strstr($content, 'GIT:') === false + && strstr($content, 'HG:') === false ) { - $error = 'Invalid version "%s" in file comment; consider "CVS: <cvs_id>" or "SVN: <svn_id>" or "GIT: <git_id>" instead'; + $error = 'Invalid version "%s" in file comment; consider "CVS: <cvs_id>" or "SVN: <svn_id>" or "GIT: <git_id>" or "HG: <hg_id>" instead'; $data = array($content); - $this->currentFile->addWarning($error, $errorPos, 'InvalidVersion', $data); + $phpcsFile->addWarning($error, $tag, 'InvalidVersion', $data); } } @@ -764,5 +524,3 @@ class PMAStandard_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_ }//end class - -?> |