Skip to content

Require inheritdoc comments to follow a set style #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 6, 2021
Merged

Require inheritdoc comments to follow a set style #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
<?php

declare(strict_types=1);

namespace Unleashed\Sniffs\Commenting;

use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Sniffs\Sniff;

final class InheritDocFormatSniff implements Sniff
{
public const CODE_INVALID_INHERITDOC_STYLE = 'InvalidInheritDocStyle';

/**
* The required style
*
* @var string
*/
public $style = '{@inheritDoc}';

/**
* @return array<int, (int|string)>
*/
public function register(): array
{
return [
T_DOC_COMMENT_OPEN_TAG,
];
}

/**
* @param int $stackPtr
*
* @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
*/
public function process(File $phpcsFile, $stackPtr): void
{
$tokens = $phpcsFile->getTokens();

for ($i = $stackPtr + 1; $i < $tokens[$stackPtr]['comment_closer']; $i++) {
if (\in_array($tokens[$i]['code'], [T_DOC_COMMENT_WHITESPACE, T_DOC_COMMENT_STAR], true)) {
continue;
}

$content = $tokens[$i]['content'];

if (\preg_match('~^(?:{@inheritDoc}|@inheritDoc)$~i', $content) === 0) {
continue;
}

$fixed = \preg_replace('~({@inheritDoc}|@inheritDoc)~i', $this->style, $content);
if ($content === $fixed) {
continue;
}

$fix = $phpcsFile->addFixableError(
\sprintf('Incorrect formatting of "%s"', $this->style),
$i,
self::CODE_INVALID_INHERITDOC_STYLE
);

if (! $fix) {
return;
}

$phpcsFile->fixer->beginChangeset();
$phpcsFile->fixer->replaceToken($i, $fixed);
$phpcsFile->fixer->endChangeset();
}
}
}
4 changes: 2 additions & 2 deletions src/Unleashed/Sniffs/DoctrineMigrations/DescriptionRequiredSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ final class DescriptionRequiredSniff implements Sniff
/**
* Returns an array of tokens this test wants to listen for.
*
* @inheritDoc
* {@inheritDoc}
*/
public function register()
{
return [\T_EXTENDS];
}

/**
* @inheritDoc
* {@inheritDoc}
*/
public function process(File $phpcsFile, $stackPtr)
{
Expand Down
4 changes: 2 additions & 2 deletions src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ final class FullyQualifiedGlobalFunctionsSniff implements Sniff
* Returns an array of tokens this test wants to listen for.
* We're looking for all functions, so use T_STRING.
*
* @inheritDoc
* {@inheritDoc}
*/
public function register()
{
Expand All @@ -78,7 +78,7 @@ public function register()
*
* @link https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Sniffs/PHP/ForbiddenFunctionsSniff.php#L118
*
* @inheritDoc
* {@inheritDoc}
*/
public function process(File $phpcsFile, $stackPtr)
{
Expand Down
4 changes: 2 additions & 2 deletions src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,15 @@ final class ForbiddenClassesSniff implements Sniff
/**
* Returns an array of tokens this test wants to listen for.
*
* @inheritDoc
* {@inheritDoc}
*/
public function register(): array
{
return [\T_OPEN_TAG];
}

/**
* @inheritDoc
* {@inheritDoc}
*/
public function process(File $phpcsFile, $stackPtr)
{
Expand Down
5 changes: 5 additions & 0 deletions src/Unleashed/ruleset.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,11 @@
</property>
</properties>
</rule>
<rule ref="Unleashed.Commenting.InheritDocFormat">
<properties>
<property name="style" value="{@inheritDoc}"/>
</properties>
</rule>
<!-- Require a description for all deprecations -->
<rule ref="SlevomatCodingStandard.Commenting.DeprecatedAnnotationDeclaration"/>
<!-- Report invalid format of inline phpDocs with @var -->
Expand Down
5 changes: 3 additions & 2 deletions tests/expected_report.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ tests/input/forbidden-functions.php 13 0
tests/input/ForbiddenClasses.php 7 0
tests/input/fully-qualified-and-fallbacks.php 1 0
tests/input/fully-qualified-without-namespace.php 3 0
tests/input/inheritdoc.php 12 1
tests/input/inline_type_hint_assertions.php 7 0
tests/input/LowCaseTypes.php 3 0
tests/input/merge-conflict.php 6 0
Expand Down Expand Up @@ -48,9 +49,9 @@ tests/input/use-ordering.php 9 0
tests/input/useless-semicolon.php 2 0
tests/input/UselessConditions.php 23 0
----------------------------------------------------------------------
A TOTAL OF 417 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
A TOTAL OF 429 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
----------------------------------------------------------------------
PHPCBF CAN FIX 334 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
PHPCBF CAN FIX 337 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------


53 changes: 53 additions & 0 deletions tests/fixed/inheritdoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php

declare(strict_types=1);

namespace Test;

interface Foo
{
/**
* @param array<int, string> $foo
*/
public function foo(array $foo): void;
}

class A implements Foo
{
/**
* {@inheritDoc}
*/
public function foo(array $foo): void
{
}
}

class B implements Foo
{
/**
* {@inheritDoc}
*/
public function foo(array $foo): void
{
}
}

class C implements Foo
{
/**
* {@inheritDoc}
*/
public function foo(array $foo): void
{
}
}

class D implements Foo
{
/**
* {@inheritDoc}
*/
public function foo(array $foo): void
{
}
}
53 changes: 53 additions & 0 deletions tests/input/inheritdoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php

declare(strict_types=1);

namespace Test;

interface Foo
{
/**
* @param array<int, string> $foo
*/
public function foo(array $foo): void;
}

class A implements Foo
{
/**
* {@inheritDoc}
*/
public function foo(array $foo): void
{
}
}

class B implements Foo
{
/**
* {@inheritdoc}
*/
public function foo(array $foo): void
{
}
}

class C implements Foo
{
/**
* @inheritDoc
*/
public function foo(array $foo): void
{
}
}

class D implements Foo
{
/**
* @inheritdoc
*/
public function foo(array $foo): void
{
}
}
32 changes: 24 additions & 8 deletions tests/php74-compatibility.patch
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,26 @@ index 3bed058..94d3a48 100644
- public $forbiddenCommentPatterns = [];
+ public array $forbiddenCommentPatterns = [];

/**
* @return array<int, (int|string)>
diff --git a/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php b/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
index 9f7d180..f77cf2e 100644
--- a/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
+++ b/src/Unleashed/Sniffs/Commenting/InheritDocFormatSniff.php
@@ -13,10 +13,8 @@ final class InheritDocFormatSniff implements Sniff

/**
* The required style
- *
- * @var string
*/
- public $style = '{@inheritDoc}';
+ public string $style = '{@inheritDoc}';

/**
* @return array<int, (int|string)>
diff --git a/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php b/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
index 71be9a5..f9492c7 100644
index ef06dc6..3106f19 100644
--- a/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
+++ b/src/Unleashed/Sniffs/Namespaces/FullyQualifiedGlobalFunctionsSniff.php
@@ -11,11 +11,10 @@ use Unleashed\Helpers\UseStatements;
Expand All @@ -43,7 +59,7 @@ index 71be9a5..f9492c7 100644
'array_key_exists' => true,
'array_slice' => true,
diff --git a/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php b/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
index 80a42a6..dd2fcb7 100644
index 674faad..943722a 100644
--- a/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
+++ b/src/Unleashed/Sniffs/PHP/ForbiddenClassesSniff.php
@@ -19,7 +19,7 @@ final class ForbiddenClassesSniff implements Sniff
Expand All @@ -68,7 +84,7 @@ index 80a42a6..dd2fcb7 100644
/**
* Returns an array of tokens this test wants to listen for.
diff --git a/tests/expected_report.txt b/tests/expected_report.txt
index 94f1b60..fa0a0f9 100644
index 5c9c68f..a17bed3 100644
--- a/tests/expected_report.txt
+++ b/tests/expected_report.txt
@@ -11,11 +11,11 @@ tests/input/concatenation_spacing.php 49 0
Expand All @@ -85,7 +101,7 @@ index 94f1b60..fa0a0f9 100644
tests/input/forbidden-comments.php 14 0
tests/input/forbidden-functions.php 13 0
tests/input/ForbiddenClasses.php 7 0
@@ -41,16 +41,16 @@ tests/input/strict-functions.php 4 0
@@ -42,16 +42,16 @@ tests/input/strict-functions.php 4 0
tests/input/test-case.php 7 0
tests/input/trailing_comma_on_array.php 1 0
tests/input/traits-uses.php 12 0
Expand All @@ -97,11 +113,11 @@ index 94f1b60..fa0a0f9 100644
tests/input/useless-semicolon.php 2 0
tests/input/UselessConditions.php 23 0
----------------------------------------------------------------------
-A TOTAL OF 417 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
+A TOTAL OF 422 ERRORS AND 8 WARNINGS WERE FOUND IN 44 FILES
-A TOTAL OF 429 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
+A TOTAL OF 434 ERRORS AND 9 WARNINGS WERE FOUND IN 45 FILES
----------------------------------------------------------------------
-PHPCBF CAN FIX 334 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
+PHPCBF CAN FIX 339 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
-PHPCBF CAN FIX 337 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
+PHPCBF CAN FIX 342 OF THESE SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------


Expand Down
Loading