Skip to content

Commit 8d697d6

Browse files
author
roettigl
committed
#54: Add new Rule for PHPDoc formatting
1 parent f3a98ac commit 8d697d6

5 files changed

+70
-43
lines changed

‎Magento2/Sniffs/Commenting/FunctionPHPDocBlockParser.php

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ class FunctionPHPDocBlockParser
1717
*/
1818
public function execute(array $tokens, $docStart, $docEnd)
1919
{
20+
$is_empty = true;
2021
$description = false;
2122
for ($i = $docStart; $i <= $docEnd; $i++) {
2223
$token = $tokens[$i];
@@ -29,10 +30,12 @@ public function execute(array $tokens, $docStart, $docEnd)
2930

3031
if ($code === T_DOC_COMMENT_STRING && $content !== "\n") {
3132
$description = $content;
33+
$is_empty = false;
3234
}
3335
}
3436

3537
$functionDeclarations = [
38+
'is_empty' => $is_empty,
3639
'description' => $description,
3740
'tags' => [],
3841
'return' => '',
@@ -114,7 +117,7 @@ private function addParamTagValue(array $tokens, array $functionDeclarations)
114117
}
115118

116119
$functionDeclarations['parameters'][] = ['content' => $content, 'type' => $type,];
117-
120+
$functionDeclarations['is_empty'] = false;
118121
return $functionDeclarations;
119122
}
120123

@@ -126,6 +129,7 @@ private function addParamTagValue(array $tokens, array $functionDeclarations)
126129
private function addReturnTagValue(array $tokens, array $functionDeclarations)
127130
{
128131
$functionDeclarations['return'] = $tokens[0];
132+
$functionDeclarations['is_empty'] = false;
129133
return $functionDeclarations;
130134
}
131135

@@ -137,6 +141,7 @@ private function addReturnTagValue(array $tokens, array $functionDeclarations)
137141
private function addThrowsTagValue(array $tokens, array $functionDeclarations)
138142
{
139143
$functionDeclarations['throws'][] = $tokens[0];
144+
$functionDeclarations['is_empty'] = false;
140145
return $functionDeclarations;
141146
}
142147
}

‎Magento2/Sniffs/Commenting/FunctionsPHPDocFormattingSniff.php

Lines changed: 46 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ public function process(File $phpcsFile, $stackPtr)
4747
$funcReturnType = $this->analysePhp7ReturnDeclaration($phpcsFile, $stackPtr);
4848
$funcParamTypeList = $this->analysePhp7ParamDeclarations($phpcsFile, $stackPtr);
4949
$phpDocTokens = $this->getPhpDocTokens($phpcsFile, $stackPtr);
50-
$hasPhp7TypeDeclarations = $funcReturnType !== false || count($funcParamTypeList['missing_type']) === 0;
50+
$hasPhp7TypeDeclarations = $funcReturnType !== false && count($funcParamTypeList['missing_type']) === 0;
5151

5252
if ($phpDocTokens === false && $hasPhp7TypeDeclarations === true) {
5353
// NO check it use all php 7 type declarations and no php doc docblock
@@ -59,21 +59,44 @@ public function process(File $phpcsFile, $stackPtr)
5959

6060
return;
6161
}
62-
62+
$tokens = $phpcsFile->getTokens();
6363
$phpDocTokensList = $this->functionPHPDocBlock->execute(
64-
$phpcsFile->getTokens(),
64+
$tokens,
6565
$phpDocTokens[0],
6666
$phpDocTokens[1]
6767
);
6868

69+
if ($phpDocTokensList['is_empty']) {
70+
$phpcsFile->addWarning('Empty Docblock SHOULD NOT be used', $stackPtr, $this->warningCode);
71+
return;
72+
}
73+
74+
$description = $phpDocTokensList['description'];
75+
76+
if ($description !== false) {
77+
$functionNameToken = $phpcsFile->findNext(T_STRING, $stackPtr, $tokens[$stackPtr]['parenthesis_opener']);
78+
$functionName = str_replace(['_', ' ', '.', ','], '', strtolower($tokens[$functionNameToken]['content']));
79+
$description = str_replace(['_', ' ', '.', ','], '', strtolower($description));
80+
81+
if ($functionName === $description) {
82+
$phpcsFile->addWarning(
83+
sprintf(
84+
'%s description should contain additional information beyond the name already supplies.',
85+
ucfirst($phpDocTokensList['description'])
86+
),
87+
$stackPtr,
88+
'InvalidDescription'
89+
);
90+
}
91+
}
92+
6993
if (array_key_exists('@inheritdoc', array_flip($phpDocTokensList['tags']))) {
7094
$phpcsFile->addWarning('The @inheritdoc tag SHOULD NOT be used', $stackPtr, $this->warningCode);
71-
7295
return;
7396
}
7497

7598
if (count($phpDocTokensList['parameters']) > 0) {
76-
$phpcsFile = $this->comparePhp7WithDocBlock(
99+
$this->comparePhp7WithDocBlock(
77100
$funcParamTypeList,
78101
$phpDocTokensList['parameters'],
79102
$phpcsFile,
@@ -219,7 +242,7 @@ private function comparePhp7WithDocBlock(array $php7Tokens, array $docBlockToken
219242
$stackPtr,
220243
$this->warningCode
221244
);
222-
return $phpcsFile;
245+
return;
223246
}
224247

225248
$parsedDocToken[$parameterName] = $token['type'];
@@ -231,24 +254,32 @@ private function comparePhp7WithDocBlock(array $php7Tokens, array $docBlockToken
231254
$stackPtr,
232255
$this->warningCode
233256
);
234-
return $phpcsFile;
257+
return;
235258
}
236259

237-
$parsedDocTokenKeys = array_keys($parsedDocToken);
238260
$hasMissingTypes = count($php7Tokens['missing_type']) > 0;
239-
if ($hasMissingTypes === true && array_keys($php7Tokens['missing_type']) !== $parsedDocTokenKeys) {
261+
if ($hasMissingTypes === false) {
262+
return;
263+
}
264+
265+
$php7ParamKey = array_keys($php7Tokens['missing_type']);
266+
$parsedDocTokenKeys = array_keys($parsedDocToken);
267+
if ($php7ParamKey !== $parsedDocTokenKeys) {
240268
$phpcsFile->addWarning(
241269
'Documented parameter and real function parameter dont match',
242270
$stackPtr,
243271
$this->warningCode
244272
);
245-
246-
return $phpcsFile;
247273
}
248274

249-
$t = 12;
250-
251-
252-
return $phpcsFile;
275+
foreach ($php7ParamKey as $parameter) {
276+
if (!isset($parsedDocToken[$parameter]) || $parsedDocToken[$parameter] === false) {
277+
$phpcsFile->addWarning(
278+
sprintf('Type for parameter %s is missing', $parameter),
279+
$stackPtr,
280+
$this->warningCode
281+
);
282+
}
283+
}
253284
}
254285
}

‎Magento2/Tests/Commenting/FunctionsPHPDocFormattingUnitTest.2.inc

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,4 @@ class EverythingIsBadHere
6969
private function dockBlockIsEmpty(string $arg1, bool $arg2): bool
7070
{
7171
}
72-
73-
/**
74-
*
75-
*
76-
* @param string $arg1
77-
* @param bool $arg2
78-
*
79-
*/
80-
private function redundantLines($arg1, $arg2): bool
81-
{
82-
}
8372
}

‎Magento2/Tests/Commenting/FunctionsPHPDocFormattingUnitTest.php

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
* Copyright © Magento. All rights reserved.
44
* See COPYING.txt for license details.
55
*/
6+
67
namespace Magento2\Tests\Commenting;
78

89
use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
@@ -25,23 +26,20 @@ public function getErrorList()
2526
*/
2627
public function getWarningList($testFile = '')
2728
{
28-
29-
if($testFile === 'FunctionsPHPDocFormattingUnitTest.2.inc')
30-
{
31-
return [
32-
11,
33-
19,
34-
26,
35-
30,
36-
40,
37-
47,
38-
55,
39-
62,
40-
69,
41-
80
42-
];
29+
if ($testFile !== 'FunctionsPHPDocFormattingUnitTest.2.inc') {
30+
return [];
4331
}
4432

45-
return [];
33+
return [
34+
11 => 1,
35+
19 => 1,
36+
26 => 2,
37+
30 => 1,
38+
40 => 1,
39+
47 => 1,
40+
55 => 2,
41+
62 => 1,
42+
69 => 1,
43+
];
4644
}
4745
}

‎Magento2/ruleset.xml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -532,6 +532,10 @@
532532
<severity>5</severity>
533533
<type>warning</type>
534534
</rule>
535+
<rule ref="Magento2.Commenting.FunctionsPHPDocFormattingSniff">
536+
<severity>5</severity>
537+
<type>warning</type>
538+
</rule>
535539
<rule ref="Squiz.Commenting.DocCommentAlignment">
536540
<severity>5</severity>
537541
<type>warning</type>

0 commit comments

Comments
 (0)