Skip to content

Commit 037b4cb

Browse files
lenaorobeiudovicic
lenaorobei
authored and
udovicic
committed
Merge branch 'develop' into feature/#131-deprecated-description
2 parents 13ceb9a + c15d174 commit 037b4cb

10 files changed

+123
-69
lines changed

‎Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

+4-18
Original file line numberDiff line numberDiff line change
@@ -56,23 +56,8 @@ public function process(File $phpcsFile, $stackPtr)
5656

5757
$namePtr = $phpcsFile->findNext(T_STRING, $stackPtr + 1, null, false, null, true);
5858

59-
$commentStartPtr = $phpcsFile->findPrevious(
60-
[
61-
T_WHITESPACE,
62-
T_DOC_COMMENT_STAR,
63-
T_DOC_COMMENT_WHITESPACE,
64-
T_DOC_COMMENT_TAG,
65-
T_DOC_COMMENT_STRING,
66-
T_DOC_COMMENT_CLOSE_TAG
67-
],
68-
$stackPtr - 1,
69-
null,
70-
true,
71-
null,
72-
true
73-
);
74-
75-
if ($tokens[$commentStartPtr]['code'] !== T_DOC_COMMENT_OPEN_TAG) {
59+
$commentStartPtr = $this->PHPDocFormattingValidator->findPHPDoc($stackPtr, $phpcsFile);
60+
if ($commentStartPtr === -1) {
7661
return;
7762
}
7863

@@ -90,7 +75,8 @@ public function process(File $phpcsFile, $stackPtr)
9075
if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
9176
$phpcsFile->addWarning(
9277
'Motivation behind the added @deprecated tag MUST be explained. '
93-
. '@see tag MUST be used with reference to new implementation.',
78+
. '@see tag MUST be used with reference to new implementation when code is deprecated '
79+
. 'and there is a new alternative.',
9480
$stackPtr,
9581
'InvalidDeprecatedTagUsage'
9682
);

‎Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php

+4-3
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,8 @@ public function process(File $phpcsFile, $stackPtr)
5959
true
6060
);
6161

62-
$commentStartPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_OPEN_TAG, $stackPtr - 1, null, false, null, true);
63-
if ($commentStartPtr === false) {
62+
$commentStartPtr = $this->PHPDocFormattingValidator->findPHPDoc($stackPtr, $phpcsFile);
63+
if ($commentStartPtr === -1) {
6464
return;
6565
}
6666

@@ -75,7 +75,8 @@ public function process(File $phpcsFile, $stackPtr)
7575
if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
7676
$phpcsFile->addWarning(
7777
'Motivation behind the added @deprecated tag MUST be explained. '
78-
. '@see tag MUST be used with reference to new implementation.',
78+
. '@see tag MUST be used with reference to new implementation when code is deprecated '
79+
. 'and there is a new alternative.',
7980
$stackPtr,
8081
'InvalidDeprecatedTagUsage'
8182
);

‎Magento2/Sniffs/Commenting/PHPDocFormattingValidator.php

+69-28
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,47 @@
66
*/
77
namespace Magento2\Sniffs\Commenting;
88

9+
use PHP_CodeSniffer\Files\File;
10+
911
/**
1012
* Helper class for common DocBlock validations
1113
*/
1214
class PHPDocFormattingValidator
1315
{
16+
/**
17+
* Finds matching PHPDoc for current pointer
18+
*
19+
* @param int $startPtr
20+
* @param File $phpcsFile
21+
* @return int
22+
*/
23+
public function findPHPDoc($startPtr, $phpcsFile)
24+
{
25+
$tokens = $phpcsFile->getTokens();
26+
27+
$commentStartPtr = $phpcsFile->findPrevious(
28+
[
29+
T_WHITESPACE,
30+
T_DOC_COMMENT_STAR,
31+
T_DOC_COMMENT_WHITESPACE,
32+
T_DOC_COMMENT_TAG,
33+
T_DOC_COMMENT_STRING,
34+
T_DOC_COMMENT_CLOSE_TAG
35+
],
36+
$startPtr - 1,
37+
null,
38+
true,
39+
null,
40+
true
41+
);
42+
43+
if ($tokens[$commentStartPtr]['code'] !== T_DOC_COMMENT_OPEN_TAG) {
44+
return -1;
45+
}
46+
47+
return $commentStartPtr;
48+
}
49+
1450
/**
1551
* Determines if the comment identified by $commentStartPtr provides additional meaning to origin at $namePtr
1652
*
@@ -81,44 +117,49 @@ public function providesMeaning($namePtr, $commentStartPtr, $tokens)
81117
*/
82118
public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
83119
{
84-
$commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
120+
$deprecatedPtr = $this->getTagPosition('@deprecated', $commentStartPtr, $tokens);
121+
if ($deprecatedPtr === -1) {
122+
return true;
123+
}
124+
125+
if ($tokens[$deprecatedPtr + 2]['code'] !== T_DOC_COMMENT_STRING) {
126+
return false;
127+
}
85128

86-
$hasDeprecated = false;
87-
$hasSee = false;
129+
$seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
130+
if ($seePtr === -1) {
131+
return true;
132+
}
133+
if ($tokens[$seePtr + 2]['code'] !== T_DOC_COMMENT_STRING) {
134+
return false;
135+
}
136+
137+
return true;
138+
}
139+
140+
/**
141+
* Searches for tag within comment
142+
*
143+
* @param string $tag
144+
* @param int $commentStartPtr
145+
* @param array $tokens
146+
* @return int
147+
*/
148+
private function getTagPosition($tag, $commentStartPtr, $tokens)
149+
{
150+
$commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
88151

89152
for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
90153
$token = $tokens[$i];
91154

92155
// Not interesting
93-
if ($token['code'] !== T_DOC_COMMENT_TAG) {
156+
if ($token['code'] !== T_DOC_COMMENT_TAG || $token['content'] !== $tag) {
94157
continue;
95158
}
96159

97-
$tag = $token['content'];
98-
99-
// Not an interesting tag
100-
if ($tag !== '@deprecated' && $tag !== '@see') {
101-
continue;
102-
}
103-
104-
if ($tag === '@deprecated') {
105-
$hasDeprecated = true;
106-
}
107-
108-
if ($tag === '@see') {
109-
$hasSee = true;
110-
}
111-
112-
// Tag not followed by description
113-
if ($tokens[$i + 2]['code'] !== T_DOC_COMMENT_STRING) {
114-
return false;
115-
}
160+
return $i;
116161
}
117162

118-
if ($hasDeprecated === true && $hasSee !== true) {
119-
return false;
120-
}
121-
122-
return true;
163+
return -1;
123164
}
124165
}

‎Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc

+8-1
Original file line numberDiff line numberDiff line change
@@ -141,8 +141,15 @@ class OldHandler
141141
/**
142142
* @see Magento\Framework\NewHandler
143143
*/
144-
interface SomethingHandler
144+
class SomethingHandler
145145
{
146146

147147
}
148148

149+
/**
150+
* @see
151+
*/
152+
class DoNotCareHandler
153+
{
154+
155+
}

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

+8
Original file line numberDiff line numberDiff line change
@@ -145,3 +145,11 @@ interface SomethingHandler
145145
{
146146

147147
}
148+
149+
/**
150+
* @see
151+
*/
152+
interface DoNotCareHandler
153+
{
154+
155+
}

‎Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php

-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ public function getWarningList($testFile = '')
3333
65 => 1,
3434
66 => 1,
3535
101 => 1,
36-
109 => 1,
3736
118 => 1,
3837
127 => 1,
3938
];

‎Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.1.inc

+15
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ define('DS', DIRECTORY_SEPARATOR);
77

88
define('BP', dirname(__FILE__));
99

10+
/**
11+
* @deprecated It is a lie
12+
*/
13+
define('THERE IS', 'cake');
14+
1015
/**
1116
* @deprecated New implementation available
1217
* @see \Ascii\Asterisk
@@ -22,9 +27,19 @@ class Profiler
2227
*/
2328
const NUMBER_TWO = 2;
2429

30+
/**
31+
* @deprecated Why not
32+
*/
33+
const YES = false;
34+
2535
/**
2636
* @deprecated Unable to identify the question, replaced
2737
* @see \ComputationalMatrix\Earth
2838
*/
2939
const COMPUTER = 'Deep Thought';
40+
41+
/**
42+
* @see
43+
*/
44+
const SOMETHING = 'else';
3045
}

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

-10
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,6 @@ define('NUMBER_ONE', 1);
1313
*/
1414
define('A', 65);
1515

16-
/**
17-
* @deprecated Slightly better, but no see tag
18-
*/
19-
define('B', 66);
20-
2116
/**
2217
* @deprecated
2318
* @see
@@ -47,11 +42,6 @@ class Profiler
4742
*/
4843
const a = 97;
4944

50-
/**
51-
* @deprecated Slightly better, but no see tag
52-
*/
53-
const b = 98;
54-
5545
/**
5646
* @deprecated
5747
* @see

‎Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.3.inc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
3+
/**
4+
* Profiler
5+
*/
6+
class Profiler
7+
{
8+
const PROFILER = true;
9+
}

‎Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php

+6-8
Original file line numberDiff line numberDiff line change
@@ -22,23 +22,21 @@ public function getErrorList()
2222
*/
2323
public function getWarningList($testFile = '')
2424
{
25-
if ($testFile === 'ConstantsPHPDocFormattingUnitTest.1.inc') {
25+
if ($testFile !== 'ConstantsPHPDocFormattingUnitTest.2.inc') {
2626
return [];
2727
}
2828

2929
return [
3030
6 => 1,
3131
9 => 1,
3232
14 => 1,
33-
19 => 1,
34-
25 => 1,
35-
31 => 1,
33+
20 => 1,
34+
26 => 1,
35+
33 => 1,
3636
38 => 1,
3737
43 => 1,
38-
48 => 1,
39-
53 => 1,
40-
59 => 1,
41-
65 => 1
38+
49 => 1,
39+
55 => 1
4240
];
4341
}
4442
}

0 commit comments

Comments
 (0)