Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit d971068

Browse filesBrowse files
lenaorobeilenaorobei
authored
Merge pull request #134 from udovicic/feature/#131-deprecated-description
Implement rule from #131
2 parents c15d174 + 037b4cb commit d971068
Copy full SHA for d971068
Expand file treeCollapse file tree

9 files changed

+278
-8
lines changed

‎Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

Copy file name to clipboardExpand all lines: Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
+10Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,16 @@ public function process(File $phpcsFile, $stackPtr)
7272
);
7373
}
7474

75+
if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
76+
$phpcsFile->addWarning(
77+
'Motivation behind the added @deprecated tag MUST be explained. '
78+
. '@see tag MUST be used with reference to new implementation when code is deprecated '
79+
. 'and there is a new alternative.',
80+
$stackPtr,
81+
'InvalidDeprecatedTagUsage'
82+
);
83+
}
84+
7585
$this->validateTags($phpcsFile, $commentStartPtr, $tokens);
7686
}
7787

‎Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php

Copy file name to clipboardExpand all lines: Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php
+10Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,5 +71,15 @@ public function process(File $phpcsFile, $stackPtr)
7171
'MissingConstantPHPDoc'
7272
);
7373
}
74+
75+
if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
76+
$phpcsFile->addWarning(
77+
'Motivation behind the added @deprecated tag MUST be explained. '
78+
. '@see tag MUST be used with reference to new implementation when code is deprecated '
79+
. 'and there is a new alternative.',
80+
$stackPtr,
81+
'InvalidDeprecatedTagUsage'
82+
);
83+
}
7484
}
7585
}

‎Magento2/Sniffs/Commenting/PHPDocFormattingValidator.php

Copy file name to clipboardExpand all lines: Magento2/Sniffs/Commenting/PHPDocFormattingValidator.php
+55Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,4 +107,59 @@ public function providesMeaning($namePtr, $commentStartPtr, $tokens)
107107

108108
return false;
109109
}
110+
111+
/**
112+
* In case comment has deprecated tag, it must be explained and followed by see tag with details
113+
*
114+
* @param int $commentStartPtr
115+
* @param array $tokens
116+
* @return bool
117+
*/
118+
public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
119+
{
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+
}
128+
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'];
151+
152+
for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
153+
$token = $tokens[$i];
154+
155+
// Not interesting
156+
if ($token['code'] !== T_DOC_COMMENT_TAG || $token['content'] !== $tag) {
157+
continue;
158+
}
159+
160+
return $i;
161+
}
162+
163+
return -1;
164+
}
110165
}

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

Copy file name to clipboardExpand all lines: Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
+63-1Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ class EmptyHandler
5959
*
6060
* @api is ok here
6161
* @deprecated can be used in this context
62+
* @see is ok here
6263
* @author is actually ok
6364
* @category is irrelevant
6465
* @package is not ment to be used
@@ -90,4 +91,65 @@ class AsyncApiHandler
9091
* @SuppressWarnings(PHPMD.CouplingBetweenObjects)
9192
*/
9293
class GroupRepositoryHandler
93-
{}
94+
{
95+
96+
}
97+
98+
/**
99+
* @deprecated
100+
*/
101+
class DeprecatedHandler
102+
{
103+
104+
}
105+
106+
/**
107+
* @deprecated Should not be used
108+
*/
109+
class AncientHandler
110+
{
111+
112+
}
113+
114+
/**
115+
* @deprecated
116+
* @see
117+
*/
118+
class AgedHandler
119+
{
120+
121+
}
122+
123+
/**
124+
* @deprecated Should not be used
125+
* @see
126+
*/
127+
class ArhaicHandler
128+
{
129+
130+
}
131+
132+
/**
133+
* @deprecated Should not be used
134+
* @see Magento\Framework\NewHandler
135+
*/
136+
class OldHandler
137+
{
138+
139+
}
140+
141+
/**
142+
* @see Magento\Framework\NewHandler
143+
*/
144+
class SomethingHandler
145+
{
146+
147+
}
148+
149+
/**
150+
* @see
151+
*/
152+
class DoNotCareHandler
153+
{
154+
155+
}

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

Copy file name to clipboardExpand all lines: Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
+64-2Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ interface EmptyHandler
5959
*
6060
* @api is ok here
6161
* @deprecated can be used in this context
62+
* @see is ok here
6263
* @author is actually ok
6364
* @category is irrelevant
6465
* @package is not ment to be used
@@ -89,5 +90,66 @@ interface AsyncApiHandler
8990
/**
9091
* @SuppressWarnings(PHPMD.CouplingBetweenObjects)
9192
*/
92-
class GroupRepositoryHandler
93-
{}
93+
interface GroupRepositoryHandler
94+
{
95+
96+
}
97+
98+
/**
99+
* @deprecated
100+
*/
101+
interface DeprecatedHandler
102+
{
103+
104+
}
105+
106+
/**
107+
* @deprecated Should not be used
108+
*/
109+
interface AncientHandler
110+
{
111+
112+
}
113+
114+
/**
115+
* @deprecated
116+
* @see
117+
*/
118+
interface AgedHandler
119+
{
120+
121+
}
122+
123+
/**
124+
* @deprecated Should not be used
125+
* @see
126+
*/
127+
interface ArhaicHandler
128+
{
129+
130+
}
131+
132+
/**
133+
* @deprecated Should not be used
134+
* @see Magento\Framework\NewHandler
135+
*/
136+
interface OldHandler
137+
{
138+
139+
}
140+
141+
/**
142+
* @see Magento\Framework\NewHandler
143+
*/
144+
interface SomethingHandler
145+
{
146+
147+
}
148+
149+
/**
150+
* @see
151+
*/
152+
interface DoNotCareHandler
153+
{
154+
155+
}

‎Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php

Copy file name to clipboardExpand all lines: Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php
+4-1Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,12 @@ public function getWarningList($testFile = '')
2929
35 => 1,
3030
44 => 1,
3131
52 => 1,
32-
63 => 1,
3332
64 => 1,
3433
65 => 1,
34+
66 => 1,
35+
101 => 1,
36+
118 => 1,
37+
127 => 1,
3538
];
3639
}
3740
}

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

Copy file name to clipboardExpand all lines: Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.1.inc
+27Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,17 @@ 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+
15+
/**
16+
* @deprecated New implementation available
17+
* @see \Ascii\Asterisk
18+
*/
19+
define('ANSWER', '42');
20+
1021
class Profiler
1122
{
1223
const NESTING_SEPARATOR = '->';
@@ -15,4 +26,20 @@ class Profiler
1526
* Unlike first const, this one is not self explanatory.
1627
*/
1728
const NUMBER_TWO = 2;
29+
30+
/**
31+
* @deprecated Why not
32+
*/
33+
const YES = false;
34+
35+
/**
36+
* @deprecated Unable to identify the question, replaced
37+
* @see \ComputationalMatrix\Earth
38+
*/
39+
const COMPUTER = 'Deep Thought';
40+
41+
/**
42+
* @see
43+
*/
44+
const SOMETHING = 'else';
1845
}

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

Copy file name to clipboardExpand all lines: Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
+35Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
<?php
2+
23
/**
34
* Nesting separator.
45
*/
@@ -7,6 +8,23 @@ define("NESTING_SEPARATOR", '->0');
78
/** */
89
define('NUMBER_ONE', 1);
910

11+
/**
12+
* @deprecated
13+
*/
14+
define('A', 65);
15+
16+
/**
17+
* @deprecated
18+
* @see
19+
*/
20+
define('C', 67);
21+
22+
/**
23+
* @deprecated No reference specified
24+
* @see
25+
*/
26+
define('D', 68);
27+
1028
class Profiler
1129
{
1230
/**
@@ -18,4 +36,21 @@ class Profiler
1836
*
1937
*/
2038
const NUMBER_TWO = 2;
39+
40+
/**
41+
* @deprecated
42+
*/
43+
const a = 97;
44+
45+
/**
46+
* @deprecated
47+
* @see
48+
*/
49+
const c = 99;
50+
51+
/**
52+
* @deprecated No reference specified
53+
* @see
54+
*/
55+
const d = 100;
2156
}

‎Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php

Copy file name to clipboardExpand all lines: Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php
+10-4Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,16 @@ public function getWarningList($testFile = '')
2727
}
2828

2929
return [
30-
5 => 1,
31-
8 => 1,
32-
15 => 1,
33-
20 => 1
30+
6 => 1,
31+
9 => 1,
32+
14 => 1,
33+
20 => 1,
34+
26 => 1,
35+
33 => 1,
36+
38 => 1,
37+
43 => 1,
38+
49 => 1,
39+
55 => 1
3440
];
3541
}
3642
}

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.