Skip to content

Commit

Permalink
Merge pull request #10 from zumba/lets-modernize
Browse files Browse the repository at this point in the history 
Updated the coding standard due to PHP 7 niceness.
  • Loading branch information
@young-steveo
young-steveo authored Feb 25, 2019
2 parents c6772c3 + edcb79d commit 12a4d03
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 28 deletions.
69 changes: 45 additions & 24 deletions Zumba/Sniffs/Commenting/FunctionCommentSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,9 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
// function has no doc comment.
$code = $tokens[$commentEnd]['code'];

$functionName = isset($tokens[$stackPtr + 2]) ? $tokens[$stackPtr + 2]['content'] : '';
$isMagic = strpos($functionName, '__') === 0;

if ($code === T_COMMENT) {
// The function might actually be missing a comment, and this last comment
// found is just commenting a bit of code on a line. So if it is not the
Expand All @@ -87,7 +90,7 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
$phpcsFile->addError($error, $stackPtr, 'WrongStyle');
}
return;
} else if ($code !== T_DOC_COMMENT) {
} else if ($code !== T_DOC_COMMENT && $functionName !== '__toString') {
$error = 'Missing function doc comment';
$phpcsFile->addError($error, $stackPtr, 'Missing');
return;
Expand All @@ -101,7 +104,7 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
$ignore[] = T_ABSTRACT;
$ignore[] = T_FINAL;
$prevToken = $phpcsFile->findPrevious($ignore, ($stackPtr - 1), null, true);
if ($prevToken !== $commentEnd) {
if ($prevToken !== $commentEnd && $functionName !== '__toString') {
$phpcsFile->addError('Missing function doc comment', $stackPtr, 'Missing');
return;
}
Expand Down Expand Up @@ -140,7 +143,7 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
// The first line of the comment should just be the /** code.
$eolPos = strpos($commentString, $phpcsFile->eolChar);
$firstLine = substr($commentString, 0, $eolPos);
if ($firstLine !== '/**') {
if ($firstLine !== '/**' && $functionName !== '__toString') {
$error = 'The open comment tag must be the only content on the line';
$phpcsFile->addError($error, $commentStart, 'ContentAfterOpen');
}
Expand All @@ -151,16 +154,16 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)

// Check for a comment description.
$short = $comment->getShortComment();
if (trim($short) === '') {
$error = 'Missing short description in function doc comment';
if (!$isMagic && trim($short) === '') {
$error = 'Missing short description in function doc comment ';
$phpcsFile->addError($error, $commentStart, 'MissingShort');
return;
}

// No extra newline before short description.
$newlineCount = 0;
$newlineSpan = strspn($short, $phpcsFile->eolChar);
if ($short !== '' && $newlineSpan > 0) {
if ($functionName !== '__toString' && $short !== '' && $newlineSpan > 0) {
$error = 'Extra newline(s) found before function comment short description';
$phpcsFile->addError($error, ($commentStart + 1), 'SpacingBeforeShort');
}
Expand Down Expand Up @@ -188,7 +191,7 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)

// Exactly one blank line before tags.
$params = $this->commentParser->getTagOrders();
if (count($params) > 1) {
if (count($params) > 1 && (trim($long) !== '' || trim($short) !== '')) {
$newlineSpan = $comment->getNewlineAfter();
if ($newlineSpan !== 2) {
$error = 'There must be exactly one blank line before the tags in function comment';
Expand All @@ -203,26 +206,29 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)

// Short description must be single line and end with a full stop.
$testShort = trim($short);
$lastChar = $testShort[(strlen($testShort) - 1)];
if (substr_count($testShort, $phpcsFile->eolChar) !== 0) {
$error = 'Function comment short description must be on a single line';
$phpcsFile->addError($error, ($commentStart + 1), 'ShortSingleLine');
}
if ($testShort !== '') {
$lastChar = $testShort[(strlen($testShort) - 1)];
if (substr_count($testShort, $phpcsFile->eolChar) !== 0) {
$error = 'Function comment short description must be on a single line';
$phpcsFile->addError($error, ($commentStart + 1), 'ShortSingleLine');
}

if (preg_match('|[A-Z]|', $testShort[0]) === 0) {
$error = 'Function comment short description must start with a capital letter';
$phpcsFile->addError($error, ($commentStart + 1), 'ShortNotCapital');
if (preg_match('|[A-Z]|', $testShort[0]) === 0) {
$error = 'Function comment short description must start with a capital letter';
$phpcsFile->addError($error, ($commentStart + 1), 'ShortNotCapital');
}
}

// The last content should be a newline and the content before
// that should not be blank. If there is more blank space
// then they have additional blank lines at the end of the comment.
$words = $this->commentParser->getWords();
$lastPos = (count($words) - 1);
if (trim($words[($lastPos - 1)]) !== ''
if ($functionName !== '__toString' && (
trim($words[($lastPos - 1)]) !== ''
|| strpos($words[($lastPos - 1)], $this->currentFile->eolChar) === false
|| trim($words[($lastPos - 2)]) === ''
) {
)) {
$error = 'Additional blank lines found at end of function comment';
$this->currentFile->addError($error, $commentEnd, 'SpacingAfter');
}
Expand Down Expand Up @@ -288,6 +294,7 @@ protected function processReturn($commentStart, $commentEnd)
$return = $this->commentParser->getReturn();

if ($isSpecialMethod === false && $methodName !== $className) {
$tokens = $this->currentFile->getTokens();
if ($return !== null) {
$tagOrder = $this->commentParser->getTagOrders();
$index = array_keys($tagOrder, 'return');
Expand Down Expand Up @@ -321,8 +328,6 @@ protected function processReturn($commentStart, $commentEnd)
$this->currentFile->addError($error, $errorPos, 'InvalidReturn', $data);
}

$tokens = $this->currentFile->getTokens();

// If the return type is void, make sure there is
// no return statement in the function.
if ($content === 'void') {
Expand Down Expand Up @@ -358,6 +363,18 @@ protected function processReturn($commentStart, $commentEnd)
}
}//end if
} else {
// only complain about missing return if no return was specified in the
// function signature.
// To do this, we check for the presence of a T_STRING between the
// parenthesis closer and the scope opener.
$functionDef = $tokens[$this->_functionToken];
$index = $functionDef['parenthesis_closer'];
$end = $functionDef['scope_opener'];
while ($index++ < $end) {
if ($tokens[$index]["code"] === \T_STRING) {
return; // we're good.
}
}
$error = 'Missing @return tag in function comment';
$this->currentFile->addError($error, $commentEnd, 'MissingReturn');
}//end if
Expand Down Expand Up @@ -388,7 +405,7 @@ protected function processParams($commentStart, $commentEnd)
{
$realParams = $this->currentFile->getMethodParameters($this->_functionToken);
$params = $this->commentParser->getParams();
$foundParams = array();
$untypedParams = array();

if (empty($params) === false) {

Expand Down Expand Up @@ -453,7 +470,9 @@ protected function processParams($commentStart, $commentEnd)
// actual parameter.
if (isset($realParams[($pos - 1)]) === true) {
$realName = $realParams[($pos - 1)]['name'];
$foundParams[] = $realName;
if (empty($realParams[($pos - 1)]['type_hint'])) {
$untypedParams[] = $realName;
}

// Append ampersand to name if passing by reference.
if ($realParams[($pos - 1)]['pass_by_reference'] === true) {
Expand Down Expand Up @@ -519,13 +538,15 @@ protected function processParams($commentStart, $commentEnd)

}//end if

// Report missing param comments if there is no type hint.
$realNames = array();
foreach ($realParams as $realParam) {
$realNames[] = $realParam['name'];
if ($realParam['type_hint'] === '') {
$realNames[] = $realParam['name'];
}
}

// Report missing comments.
$diff = array_diff($realNames, $foundParams);
$diff = array_diff($realNames, $untypedParams);
foreach ($diff as $neededParam) {
if (count($params) !== 0) {
$errorPos = ($params[(count($params) - 1)]->getLine() + $commentStart);
Expand Down
5 changes: 1 addition & 4 deletions Zumba/Sniffs/Commenting/VariableCommentSniff.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,6 @@ public function processMemberVar(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
$short = $comment->getShortComment();
$long = '';
if (trim($short) === '') {
$error = 'Missing short description in variable doc comment';
$phpcsFile->addError($error, $commentStart, 'MissingShort');
$newlineCount = 1;
} else {
// No extra newline before short description.
Expand Down Expand Up @@ -146,7 +144,7 @@ public function processMemberVar(PHP_CodeSniffer_File $phpcsFile, $stackPtr)

// Exactly one blank line before tags.
$tags = $this->commentParser->getTagOrders();
if (count($tags) > 1) {
if (count($tags) > 1 && trim($short) !== '') {
$newlineSpan = $comment->getNewlineAfter();
if ($newlineSpan !== 2) {
$error = 'There must be exactly one blank line before the tags in variable comment';
Expand Down Expand Up @@ -247,4 +245,3 @@ protected function processVar($commentStart, $commentEnd)


}//end class
?>

0 comments on commit 12a4d03

Please sign in to comment.