Skip to content

Commit 4431054

Browse files
colinodellcolinodell
committed
Require inheritdoc comments to follow a set style
1 parent b6a6576 commit 4431054

File tree

10 files changed

+241
-26
lines changed

10 files changed

+241
-26
lines changed

‎src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Unleashed\Sniffs\Commenting;
6+
7+
use PHP_CodeSniffer\Files\File;
8+
use PHP_CodeSniffer\Sniffs\Sniff;
9+
10+
final class InheritDocFormatSniff implements Sniff
11+
{
12+
public const CODE_INVALID_INHERITDOC_STYLE = 'InvalidInheritDocStyle';
13+
14+
/**
15+
* The required style
16+
*
17+
* @var string
18+
*/
19+
public $style = '{@inheritDoc}';
20+
21+
/**
22+
* @return array<int, (int|string)>
23+
*/
24+
public function register(): array
25+
{
26+
return [
27+
T_DOC_COMMENT_OPEN_TAG,
28+
];
29+
}
30+
31+
/**
32+
* @param int $stackPtr
33+
*
34+
* @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
35+
*/
36+
public function process(File $phpcsFile, $stackPtr): void
37+
{
38+
$tokens = $phpcsFile->getTokens();
39+
40+
for ($i = $stackPtr + 1; $i < $tokens[$stackPtr]['comment_closer']; $i++) {
41+
if (\in_array($tokens[$i]['code'], [T_DOC_COMMENT_WHITESPACE, T_DOC_COMMENT_STAR], true)) {
42+
continue;
43+
}
44+
45+
$content = $tokens[$i]['content'];
46+
47+
if (\preg_match('~^(?:{@inheritDoc}|@inheritDoc)$~i', $content) === 0) {
48+
continue;
49+
}
50+
51+
$fixed = \preg_replace('~({@inheritDoc}|@inheritDoc)~i', $this->style, $content);
52+
if ($content === $fixed) {
53+
continue;
54+
}
55+
56+
$fix = $phpcsFile->addFixableError(
57+
\sprintf('Incorrect formatting of "%s"', $this->style),
58+
$i,
59+
self::CODE_INVALID_INHERITDOC_STYLE
60+
);
61+
62+
if (! $fix) {
63+
return;
64+
}
65+
66+
$phpcsFile->fixer->beginChangeset();
67+
$phpcsFile->fixer->replaceToken($i, $fixed);
68+
$phpcsFile->fixer->endChangeset();
69+
}
70+
}
71+
}

‎src/Unleashed/Sniffs/DoctrineMigrations/DescriptionRequiredSniff.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,15 @@ final class DescriptionRequiredSniff implements Sniff
1919
/**
2020
* Returns an array of tokens this test wants to listen for.
2121
*
22-
* @inheritDoc
22+
* {@inheritDoc}
2323
*/
2424
public function register()
2525
{
2626
return [\T_EXTENDS];
2727
}
2828

2929
/**
30-
* @inheritDoc
30+
* {@inheritDoc}
3131
*/
3232
public function process(File $phpcsFile, $stackPtr)
3333
{

‎src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ final class FullyQualifiedGlobalFunctionsSniff implements Sniff
6464
* Returns an array of tokens this test wants to listen for.
6565
* We're looking for all functions, so use T_STRING.
6666
*
67-
* @inheritDoc
67+
* {@inheritDoc}
6868
*/
6969
public function register()
7070
{
@@ -78,7 +78,7 @@ public function register()
7878
*
7979
* @link https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php#L118
8080
*
81-
* @inheritDoc
81+
* {@inheritDoc}
8282
*/
8383
public function process(File $phpcsFile, $stackPtr)
8484
{

‎src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,15 +35,15 @@ final class ForbiddenClassesSniff implements Sniff
3535
/**
3636
* Returns an array of tokens this test wants to listen for.
3737
*
38-
* @inheritDoc
38+
* {@inheritDoc}
3939
*/
4040
public function register(): array
4141
{
4242
return [\T_OPEN_TAG];
4343
}
4444

4545
/**
46-
* @inheritDoc
46+
* {@inheritDoc}
4747
*/
4848
public function process(File $phpcsFile, $stackPtr)
4949
{

‎src/Unleashed/ruleset.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,11 @@
293293
</property>
294294
</properties>
295295
</rule>
296+
<rule ref="Unleashed.Commenting.InheritDocFormat">
297+
<properties>
298+
<property name="style" value="{@inheritDoc}"/>
299+
</properties>
300+
</rule>
296301
<!-- Require a description for all deprecations -->
297302
<rule ref="SlevomatCodingStandard.Commenting.DeprecatedAnnotationDeclaration"/>
298303
<!-- Report invalid format of inline phpDocs with @var -->

‎tests/expected_report.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ tests/input/forbidden-functions.php 13 0
2121
tests/input/ForbiddenClasses.php 7 0
2222
tests/input/fully-qualified-and-fallbacks.php 1 0
2323
tests/input/fully-qualified-without-namespace.php 3 0
24+
tests/input/inheritdoc.php 12 1
2425
tests/input/inline_type_hint_assertions.php 7 0
2526
tests/input/LowCaseTypes.php 3 0
2627
tests/input/merge-conflict.php 6 0
@@ -48,9 +49,9 @@ tests/input/use-ordering.php 9 0
4849
tests/input/useless-semicolon.php 2 0
4950
tests/input/UselessConditions.php 23 0
5051
----------------------------------------------------------------------
51-
A TOTAL OF 417 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
52+
A TOTAL OF 429 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
5253
----------------------------------------------------------------------
53-
PHPCBF CAN FIX 334 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
54+
PHPCBF CAN FIX 337 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
5455
----------------------------------------------------------------------
5556

5657

‎tests/fixed/inheritdoc.php‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Test;
6+
7+
interface Foo
8+
{
9+
/**
10+
* @param array<int, string> $foo
11+
*/
12+
public function foo(array $foo): void;
13+
}
14+
15+
class A implements Foo
16+
{
17+
/**
18+
* {@inheritDoc}
19+
*/
20+
public function foo(array $foo): void
21+
{
22+
}
23+
}
24+
25+
class B implements Foo
26+
{
27+
/**
28+
* {@inheritDoc}
29+
*/
30+
public function foo(array $foo): void
31+
{
32+
}
33+
}
34+
35+
class C implements Foo
36+
{
37+
/**
38+
* {@inheritDoc}
39+
*/
40+
public function foo(array $foo): void
41+
{
42+
}
43+
}
44+
45+
class D implements Foo
46+
{
47+
/**
48+
* {@inheritDoc}
49+
*/
50+
public function foo(array $foo): void
51+
{
52+
}
53+
}

‎tests/input/inheritdoc.php‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Test;
6+
7+
interface Foo
8+
{
9+
/**
10+
* @param array<int, string> $foo
11+
*/
12+
public function foo(array $foo): void;
13+
}
14+
15+
class A implements Foo
16+
{
17+
/**
18+
* {@inheritDoc}
19+
*/
20+
public function foo(array $foo): void
21+
{
22+
}
23+
}
24+
25+
class B implements Foo
26+
{
27+
/**
28+
* {@inheritdoc}
29+
*/
30+
public function foo(array $foo): void
31+
{
32+
}
33+
}
34+
35+
class C implements Foo
36+
{
37+
/**
38+
* @inheritDoc
39+
*/
40+
public function foo(array $foo): void
41+
{
42+
}
43+
}
44+
45+
class D implements Foo
46+
{
47+
/**
48+
* @inheritdoc
49+
*/
50+
public function foo(array $foo): void
51+
{
52+
}
53+
}

‎tests/php74-compatibility.patch‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,26 @@ index 3bed058..94d3a48 100644
2222
- public $forbiddenCommentPatterns = [];
2323
+ public array $forbiddenCommentPatterns = [];
2424

25+
/**
26+
* @return array<int, (int|string)>
27+
diff --git a/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php b/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
28+
index 9f7d180..f77cf2e 100644
29+
--- a/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
30+
+++ b/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
31+
@@ -13,10 +13,8 @@ final class InheritDocFormatSniff implements Sniff
32+
33+
/**
34+
* The required style
35+
- *
36+
- * @var string
37+
*/
38+
- public $style = '{@inheritDoc}';
39+
+ public string $style = '{@inheritDoc}';
40+
2541
/**
2642
* @return array<int, (int|string)>
2743
diff --git a/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php b/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
28-
index 71be9a5..f9492c7 100644
44+
index ef06dc6..3106f19 100644
2945
--- a/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
3046
+++ b/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
3147
@@ -11,11 +11,10 @@ use Unleashed\Helpers\UseStatements;
@@ -43,7 +59,7 @@ index 71be9a5..f9492c7 100644
4359
'array_key_exists' => true,
4460
'array_slice' => true,
4561
diff --git a/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php b/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
46-
index 80a42a6..dd2fcb7 100644
62+
index 674faad..943722a 100644
4763
--- a/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
4864
+++ b/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
4965
@@ -19,7 +19,7 @@ final class ForbiddenClassesSniff implements Sniff
@@ -68,7 +84,7 @@ index 80a42a6..dd2fcb7 100644
6884
/**
6985
* Returns an array of tokens this test wants to listen for.
7086
diff --git a/tests/expected_report.txt b/tests/expected_report.txt
71-
index 94f1b60..fa0a0f9 100644
87+
index 5c9c68f..a17bed3 100644
7288
--- a/tests/expected_report.txt
7389
+++ b/tests/expected_report.txt
7490
@@ -11,11 +11,11 @@ tests/input/concatenation_spacing.php 49 0
@@ -85,7 +101,7 @@ index 94f1b60..fa0a0f9 100644
85101
tests/input/forbidden-comments.php 14 0
86102
tests/input/forbidden-functions.php 13 0
87103
tests/input/ForbiddenClasses.php 7 0
88-
@@ -41,16 +41,16 @@ tests/input/strict-functions.php 4 0
104+
@@ -42,16 +42,16 @@ tests/input/strict-functions.php 4 0
89105
tests/input/test-case.php 7 0
90106
tests/input/trailing_comma_on_array.php 1 0
91107
tests/input/traits-uses.php 12 0
@@ -97,11 +113,11 @@ index 94f1b60..fa0a0f9 100644
97113
tests/input/useless-semicolon.php 2 0
98114
tests/input/UselessConditions.php 23 0
99115
----------------------------------------------------------------------
100-
-A TOTAL OF 417 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
101-
+A TOTAL OF 422 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
116+
-A TOTAL OF 429 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
117+
+A TOTAL OF 434 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
102118
----------------------------------------------------------------------
103-
-PHPCBF CAN FIX 334 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
104-
+PHPCBF CAN FIX 339 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
119+
-PHPCBF CAN FIX 337 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
120+
+PHPCBF CAN FIX 342 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
105121
----------------------------------------------------------------------
106122

107123

0 commit comments

Comments
 (0)