Skip to content

Commit cf4cace

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

File tree

10 files changed

+271
-101
lines changed

10 files changed

+271
-101
lines changed
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: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,29 +10,30 @@ tests/input/class-references.php 10 0
1010
tests/input/concatenation_spacing.php 49 0
1111
tests/input/constants-no-lsb.php 2 0
1212
tests/input/constants-var.php 4 0
13-
tests/input/ControlStructures.php 17 2
14-
tests/input/doc-comment-spacing.php 16 0
13+
tests/input/ControlStructures.php 18 2
14+
tests/input/doc-comment-spacing.php 17 0
1515
tests/input/doctrine-migration.php 18 6
1616
tests/input/duplicate-assignment-variable.php 1 0
17-
tests/input/EarlyReturn.php 6 0
18-
tests/input/example-class.php 38 0
17+
tests/input/EarlyReturn.php 7 0
18+
tests/input/example-class.php 43 0
1919
tests/input/forbidden-comments.php 14 0
2020
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
2728
tests/input/namespaces-spacing.php 12 0
28-
tests/input/NamingCamelCase.php 7 0
29+
tests/input/NamingCamelCase.php 10 0
2930
tests/input/negation-operator.php 2 0
3031
tests/input/new_with_parentheses.php 30 0
3132
tests/input/not_spacing.php 8 0
3233
tests/input/null_coalesce_operator.php 3 0
3334
tests/input/optimized-functions.php 1 0
34-
tests/input/return_type_on_closures.php 17 0
35-
tests/input/return_type_on_methods.php 13 0
35+
tests/input/return_type_on_closures.php 22 0
36+
tests/input/return_type_on_methods.php 18 0
3637
tests/input/semicolon_spacing.php 3 0
3738
tests/input/single-line-array-spacing.php 5 0
3839
tests/input/spread-operator.php 10 0
@@ -41,16 +42,16 @@ tests/input/strict-functions.php 4 0
4142
tests/input/test-case.php 7 0
4243
tests/input/trailing_comma_on_array.php 1 0
4344
tests/input/traits-uses.php 12 0
44-
tests/input/type-hints.php 5 0
45+
tests/input/type-hints.php 6 0
4546
tests/input/UnusedVariables.php 2 0
4647
tests/input/use-function.php 2 0
4748
tests/input/use-ordering.php 9 0
4849
tests/input/useless-semicolon.php 2 0
49-
tests/input/UselessConditions.php 23 0
50+
tests/input/UselessConditions.php 24 0
5051
----------------------------------------------------------------------
51-
A TOTAL OF 417 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
52+
A TOTAL OF 452 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
5253
----------------------------------------------------------------------
53-
PHPCBF CAN FIX 334 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
54+
PHPCBF CAN FIX 360 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+
}

0 commit comments

Comments
 (0)