Viewing file: FunctionCommentSniff.php (18.4 KB) -rw-rw-rw- Select action/file-type: (+) | (+) | (+) | Code (+) | Session (+) | (+) | SDB (+) | (+) | (+) | (+) | (+) | (+) |
<?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
?>
|