diff options
Diffstat (limited to 'PMAStandard/Sniffs/Commenting/FunctionCommentSniff.php')
| -rw-r--r-- | PMAStandard/Sniffs/Commenting/FunctionCommentSniff.php | 490 |
1 files changed, 490 insertions, 0 deletions
diff --git a/PMAStandard/Sniffs/Commenting/FunctionCommentSniff.php b/PMAStandard/Sniffs/Commenting/FunctionCommentSniff.php new file mode 100644 index 0000000000..081c05d32b --- /dev/null +++ b/PMAStandard/Sniffs/Commenting/FunctionCommentSniff.php @@ -0,0 +1,490 @@ +<?php +/** + * Parses and verifies the doc comments for functions. + * + * PHP version 5 + * + * @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 + * @link http://pear.php.net/package/PHP_CodeSniffer + */ + +if (class_exists('PHP_CodeSniffer_CommentParser_FunctionCommentParser', true) === false) { + throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_CommentParser_FunctionCommentParser not found'); +} + +/** + * Parses and verifies the doc comments for functions. + * + * Verifies that : + * <ul> + * <li>A 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>Parameter names represent those in the method.</li> + * <li>Parameter comments are in the correct order</li> + * <li>Parameter comments are complete</li> + * <li>A space is present before the first and after the last parameter</li> + * <li>A return type exists</li> + * <li>There must be one blank line between body and headline comments.</li> + * <li>Any throw tag must have an exception class.</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 + * @link http://pear.php.net/package/PHP_CodeSniffer + */ +class PEAR_Sniffs_Commenting_FunctionCommentSniff implements PHP_CodeSniffer_Sniff +{ + + /** + * The name of the method that we are currently processing. + * + * @var string + */ + private $_methodName = ''; + + /** + * The position in the stack where the fucntion token was found. + * + * @var int + */ + private $_functionToken = null; + + /** + * The position in the stack where the class token was found. + * + * @var int + */ + private $_classToken = null; + + /** + * The function comment parser for the current method. + * + * @var PHP_CodeSniffer_Comment_Parser_FunctionCommentParser + */ + protected $commentParser = null; + + /** + * The current PHP_CodeSniffer_File object we are processing. + * + * @var PHP_CodeSniffer_File + */ + protected $currentFile = null; + + + /** + * Returns an array of tokens this test wants to listen for. + * + * @return array + */ + public function register() + { + return array(T_FUNCTION); + + }//end register() + + + /** + * Processes this test, when one of its tokens is encountered. + * + * @param PHP_CodeSniffer_File $phpcsFile The file being scanned. + * @param int $stackPtr The position of the current token + * in the stack passed in $tokens. + * + * @return void + */ + public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr) + { + $find = array( + T_COMMENT, + T_DOC_COMMENT, + T_CLASS, + T_FUNCTION, + T_OPEN_TAG, + ); + + $commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1)); + + if ($commentEnd === false) { + return; + } + + $this->currentFile = $phpcsFile; + $tokens = $phpcsFile->getTokens(); + + // If the token that we found was a class or a function, then this + // function has no doc comment. + $code = $tokens[$commentEnd]['code']; + + if ($code === T_COMMENT) { + $error = 'You must use "/**" style comments for a function comment'; + $phpcsFile->addError($error, $stackPtr, 'WrongStyle'); + return; + } else if ($code !== T_DOC_COMMENT) { + $phpcsFile->addError('Missing function doc comment', $stackPtr, 'Missing'); + return; + } + + // If there is any code between the function keyword and the doc block + // then the doc block is not for us. + $ignore = PHP_CodeSniffer_Tokens::$scopeModifiers; + $ignore[] = T_STATIC; + $ignore[] = T_WHITESPACE; + $ignore[] = T_ABSTRACT; + $ignore[] = T_FINAL; + $prevToken = $phpcsFile->findPrevious($ignore, ($stackPtr - 1), null, true); + if ($prevToken !== $commentEnd) { + $phpcsFile->addError('Missing function doc comment', $stackPtr, 'Missing'); + return; + } + + $this->_functionToken = $stackPtr; + + $this->_classToken = null; + foreach ($tokens[$stackPtr]['conditions'] as $condPtr => $condition) { + if ($condition === T_CLASS || $condition === T_INTERFACE) { + $this->_classToken = $condPtr; + break; + } + } + + // If the first T_OPEN_TAG is right before the comment, it is probably + // a file comment. + $commentStart = ($phpcsFile->findPrevious(T_DOC_COMMENT, ($commentEnd - 1), null, true) + 1); + $prevToken = $phpcsFile->findPrevious(T_WHITESPACE, ($commentStart - 1), null, true); + if ($tokens[$prevToken]['code'] === T_OPEN_TAG) { + // Is this the first open tag? + if ($stackPtr === 0 || $phpcsFile->findPrevious(T_OPEN_TAG, ($prevToken - 1)) === false) { + $phpcsFile->addError('Missing function doc comment', $stackPtr, 'Missing'); + return; + } + } + + $comment = $phpcsFile->getTokensAsString($commentStart, ($commentEnd - $commentStart + 1)); + $this->_methodName = $phpcsFile->getDeclarationName($stackPtr); + + try { + $this->commentParser = new PHP_CodeSniffer_CommentParser_FunctionCommentParser($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 = 'Function doc comment is empty'; + $phpcsFile->addError($error, $commentStart, 'Empty'); + return; + } + + $this->processParams($commentStart); + $this->processReturn($commentStart, $commentEnd); + $this->processThrows($commentStart); + + // 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 function comment short description'; + $phpcsFile->addError($error, ($commentStart + 1), 'SpacingBeforeShort'); + } + + $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 function comment'; + $phpcsFile->addError($error, ($commentStart + $newlineCount + 1), 'SpacingAfterShort'); + } + + $newlineCount += $newlineBetween; + } + + // Exactly one blank line before tags. + $params = $this->commentParser->getTagOrders(); + if (count($params) > 1) { + $newlineSpan = $comment->getNewlineAfter(); + if ($newlineSpan !== 2) { + $error = 'There must be exactly one blank line before the tags in function comment'; + if ($long !== '') { + $newlineCount += (substr_count($long, $phpcsFile->eolChar) - $newlineSpan + 1); + } + + $phpcsFile->addError($error, ($commentStart + $newlineCount), 'SpacingBeforeTags'); + $short = rtrim($short, $phpcsFile->eolChar.' '); + } + } + + }//end process() + + + /** + * Process any throw tags that this function comment has. + * + * @param int $commentStart The position in the stack where the + * comment started. + * + * @return void + */ + protected function processThrows($commentStart) + { + if (count($this->commentParser->getThrows()) === 0) { + return; + } + + foreach ($this->commentParser->getThrows() as $throw) { + + $exception = $throw->getValue(); + $errorPos = ($commentStart + $throw->getLine()); + + if ($exception === '') { + $error = '@throws tag must contain the exception class name'; + $this->currentFile->addError($error, $errorPos, 'EmptyThrows'); + } + } + + }//end processThrows() + + + /** + * Process the return comment of this function comment. + * + * @param int $commentStart The position in the stack where the comment started. + * @param int $commentEnd The position in the stack where the comment ended. + * + * @return void + */ + protected function processReturn($commentStart, $commentEnd) + { + // Skip constructor and destructor. + $className = ''; + if ($this->_classToken !== null) { + $className = $this->currentFile->getDeclarationName($this->_classToken); + $className = strtolower(ltrim($className, '_')); + } + + $methodName = strtolower(ltrim($this->_methodName, '_')); + $isSpecialMethod = ($this->_methodName === '__construct' || $this->_methodName === '__destruct'); + + if ($isSpecialMethod === false && $methodName !== $className) { + // Report missing return tag. + if ($this->commentParser->getReturn() === null) { + $error = 'Missing @return tag in function comment'; + $this->currentFile->addError($error, $commentEnd, 'MissingReturn'); + } else if (trim($this->commentParser->getReturn()->getRawContent()) === '') { + $error = '@return tag is empty in function comment'; + $errorPos = ($commentStart + $this->commentParser->getReturn()->getLine()); + $this->currentFile->addError($error, $errorPos, 'EmptyReturn'); + } + } + + }//end processReturn() + + + /** + * Process the function parameter comments. + * + * @param int $commentStart The position in the stack where + * the comment started. + * + * @return void + */ + protected function processParams($commentStart) + { + $realParams = $this->currentFile->getMethodParameters($this->_functionToken); + + $params = $this->commentParser->getParams(); + $foundParams = array(); + + if (empty($params) === false) { + + $lastParm = (count($params) - 1); + if (substr_count($params[$lastParm]->getWhitespaceAfter(), $this->currentFile->eolChar) !== 2) { + $error = 'Last parameter comment requires a blank newline after it'; + $errorPos = ($params[$lastParm]->getLine() + $commentStart); + $this->currentFile->addError($error, $errorPos, 'SpacingAfterParams'); + } + + // Parameters must appear immediately after the comment. + if ($params[0]->getOrder() !== 2) { + $error = 'Parameters must appear immediately after the comment'; + $errorPos = ($params[0]->getLine() + $commentStart); + $this->currentFile->addError($error, $errorPos, 'SpacingBeforeParams'); + } + + $previousParam = null; + $spaceBeforeVar = 10000; + $spaceBeforeComment = 10000; + $longestType = 0; + $longestVar = 0; + + foreach ($params as $param) { + + $paramComment = trim($param->getComment()); + $errorPos = ($param->getLine() + $commentStart); + + // Make sure that there is only one space before the var type. + if ($param->getWhitespaceBeforeType() !== ' ') { + $error = 'Expected 1 space before variable type'; + $this->currentFile->addError($error, $errorPos, 'SpacingBeforeParamType'); + } + + $spaceCount = substr_count($param->getWhitespaceBeforeVarName(), ' '); + if ($spaceCount < $spaceBeforeVar) { + $spaceBeforeVar = $spaceCount; + $longestType = $errorPos; + } + + $spaceCount = substr_count($param->getWhitespaceBeforeComment(), ' '); + + if ($spaceCount < $spaceBeforeComment && $paramComment !== '') { + $spaceBeforeComment = $spaceCount; + $longestVar = $errorPos; + } + + // Make sure they are in the correct order, + // and have the correct name. + $pos = $param->getPosition(); + + $paramName = ($param->getVarName() !== '') ? $param->getVarName() : '[ UNKNOWN ]'; + + if ($previousParam !== null) { + $previousName = ($previousParam->getVarName() !== '') ? $previousParam->getVarName() : 'UNKNOWN'; + + // Check to see if the parameters align properly. + if ($param->alignsVariableWith($previousParam) === false) { + $error = 'The variable names for parameters %s (%s) and %s (%s) do not align'; + $data = array( + $previousName, + ($pos - 1), + $paramName, + $pos, + ); + $this->currentFile->addError($error, $errorPos, 'ParameterNamesNotAligned', $data); + } + + if ($param->alignsCommentWith($previousParam) === false) { + $error = 'The comments for parameters %s (%s) and %s (%s) do not align'; + $data = array( + $previousName, + ($pos - 1), + $paramName, + $pos, + ); + $this->currentFile->addError($error, $errorPos, 'ParameterCommentsNotAligned', $data); + } + }//end if + + // Make sure the names of the parameter comment matches the + // actual parameter. + if (isset($realParams[($pos - 1)]) === true) { + $realName = $realParams[($pos - 1)]['name']; + $foundParams[] = $realName; + + // Append ampersand to name if passing by reference. + if ($realParams[($pos - 1)]['pass_by_reference'] === true) { + $realName = '&'.$realName; + } + + if ($realName !== $paramName) { + $code = 'ParamNameNoMatch'; + $data = array( + $paramName, + $realName, + $pos, + ); + + $error = 'Doc comment for var %s does not match '; + if (strtolower($paramName) === strtolower($realName)) { + $error .= 'case of '; + $code = 'ParamNameNoCaseMatch'; + } + + $error .= 'actual variable name %s at position %s'; + + $this->currentFile->addError($error, $errorPos, $code, $data); + } + } else { + // We must have an extra parameter comment. + $error = 'Superfluous doc comment at position '.$pos; + $this->currentFile->addError($error, $errorPos, 'ExtraParamComment'); + } + + if ($param->getVarName() === '') { + $error = 'Missing parameter name at position '.$pos; + $this->currentFile->addError($error, $errorPos, 'MissingParamName'); + } + + if ($param->getType() === '') { + $error = 'Missing type at position '.$pos; + $this->currentFile->addError($error, $errorPos, 'MissingParamType'); + } + + if ($paramComment === '') { + $error = 'Missing comment for param "%s" at position %s'; + $data = array( + $paramName, + $pos, + ); + $this->currentFile->addError($error, $errorPos, 'MissingParamComment', $data); + } + + $previousParam = $param; + + }//end foreach + + if ($spaceBeforeVar !== 1 && $spaceBeforeVar !== 10000 && $spaceBeforeComment !== 10000) { + $error = 'Expected 1 space after the longest type'; + $this->currentFile->addError($error, $longestType, 'SpacingAfterLongType'); + } + + if ($spaceBeforeComment !== 1 && $spaceBeforeComment !== 10000) { + $error = 'Expected 1 space after the longest variable name'; + $this->currentFile->addError($error, $longestVar, 'SpacingAfterLongName'); + } + + }//end if + + $realNames = array(); + foreach ($realParams as $realParam) { + $realNames[] = $realParam['name']; + } + + // Report and missing comments. + $diff = array_diff($realNames, $foundParams); + foreach ($diff as $neededParam) { + if (count($params) !== 0) { + $errorPos = ($params[(count($params) - 1)]->getLine() + $commentStart); + } else { + $errorPos = $commentStart; + } + + $error = 'Doc comment for "%s" missing'; + $data = array($neededParam); + $this->currentFile->addError($error, $errorPos, 'MissingParamTag', $data); + } + + }//end processParams() + + +}//end class + +?> |