From 3332dbaf8c33e5ad00bcf6fd8c209b28ba5fbe90 Mon Sep 17 00:00:00 2001 From: Lachlan Turner Date: Fri, 24 Jun 2022 10:58:00 +0930 Subject: [PATCH 1/5] Class properties that have types should not require a DocBlock --- .../ClassPropertyPHPDocFormattingSniff.php | 49 +++++++++++++++++-- .../ClassPropertyPHPDocFormattingUnitTest.inc | 2 + 2 files changed, 46 insertions(+), 5 deletions(-) diff --git a/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php index f05cc78b..d5b4726d 100644 --- a/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php +++ b/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php @@ -37,6 +37,16 @@ class ClassPropertyPHPDocFormattingSniff extends AbstractVariableSniff */ private $PHPDocFormattingValidator; + /** + * @var array + */ + private $invalidTypes = [ + 'null', + 'false', + 'true', + 'self' + ]; + /** * Constructs an ClassPropertyPHPDocFormattingSniff. */ @@ -62,7 +72,12 @@ public function processMemberVar(File $phpcsFile, $stackPtr) ); if ($commentEnd === false || $tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG) { - $phpcsFile->addWarning('Missing PHP DocBlock for class property.', $stackPtr, 'Missing'); + // if the property has a valid type definition, we don't require a doc block + if (!$this->hasValidType($phpcsFile, $stackPtr)) { + $phpcsFile->addWarning( + 'Missing PHP DocBlock for class property without valid type.', $stackPtr, 'Missing'); + } + // no comment, so nothing further to process return; } @@ -121,10 +136,10 @@ public function processMemberVar(File $phpcsFile, $stackPtr) ); if ($this->PHPDocFormattingValidator->providesMeaning( - $shortDescriptionAfterVarPosition, - $commentStart, - $tokens - ) !== true) { + $shortDescriptionAfterVarPosition, + $commentStart, + $tokens + ) !== true) { preg_match( '`^((?:\|?(?:array\([^\)]*\)|[\\\\\[\]]+))*)( .*)?`i', $tokens[($varAnnotationPosition + 2)]['content'], @@ -143,6 +158,30 @@ public function processMemberVar(File $phpcsFile, $stackPtr) $this->processPropertyShortDescription($phpcsFile, $stackPtr, $varAnnotationPosition, $commentStart); } + /** + * Check if class property has a valid (not specifically invalid) type + * + * @param File $phpcsFile + * @param int $propertyPosition + * @return bool + */ + private function hasValidType(File $phpcsFile, int $propertyPosition): bool + { + // type token should be 2 before property. If not present, visibility token should be in its place + $typePosition = $phpcsFile->findPrevious( + [T_STRING], + $propertyPosition, + $propertyPosition - 2 + ); + + if (!$typePosition) { + return false; + } + + $type = $phpcsFile->getTokensAsString($typePosition, 1); + return !in_array(strtolower($type), $this->invalidTypes); + } + /** * Check if class has already have meaningful description before var tag * diff --git a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc index 62e9688f..d026ef87 100644 --- a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc +++ b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc @@ -194,4 +194,6 @@ class correctlyFormattedClassMemberDocBlock * @see Message with some reference */ protected string $itIsCorrect; + + private string $typedPropertyWithoutComment; } From 9c71dd29b04b04c00eed979482f56e69f975c7a0 Mon Sep 17 00:00:00 2001 From: Lachlan Turner Date: Fri, 24 Jun 2022 11:07:33 +0930 Subject: [PATCH 2/5] Revert accidental indenting --- .../Commenting/ClassPropertyPHPDocFormattingSniff.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php index d5b4726d..46ab55b3 100644 --- a/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php +++ b/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php @@ -136,10 +136,10 @@ public function processMemberVar(File $phpcsFile, $stackPtr) ); if ($this->PHPDocFormattingValidator->providesMeaning( - $shortDescriptionAfterVarPosition, - $commentStart, - $tokens - ) !== true) { + $shortDescriptionAfterVarPosition, + $commentStart, + $tokens + ) !== true) { preg_match( '`^((?:\|?(?:array\([^\)]*\)|[\\\\\[\]]+))*)( .*)?`i', $tokens[($varAnnotationPosition + 2)]['content'], From 4518aedbf2b5bc8fa552b648daa2b08004f05875 Mon Sep 17 00:00:00 2001 From: Lachlan Turner Date: Fri, 24 Jun 2022 11:12:45 +0930 Subject: [PATCH 3/5] Fix multi-line function formatting --- .../Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php index 46ab55b3..571eab08 100644 --- a/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php +++ b/Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php @@ -75,7 +75,10 @@ public function processMemberVar(File $phpcsFile, $stackPtr) // if the property has a valid type definition, we don't require a doc block if (!$this->hasValidType($phpcsFile, $stackPtr)) { $phpcsFile->addWarning( - 'Missing PHP DocBlock for class property without valid type.', $stackPtr, 'Missing'); + 'Missing PHP DocBlock for class property without valid type.', + $stackPtr, + 'Missing' + ); } // no comment, so nothing further to process return; From 661145bb3f7c1a265c0fbda0db96f3f2f27a5f86 Mon Sep 17 00:00:00 2001 From: Lachlan Turner <40189797+aligent-lturner@users.noreply.github.com> Date: Thu, 14 Jul 2022 16:39:49 +0930 Subject: [PATCH 4/5] Add extra use cases for typed class properties Co-authored-by: Ihor Sviziev --- .../ClassPropertyPHPDocFormattingUnitTest.inc | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc index d026ef87..10f01731 100644 --- a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc +++ b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc @@ -195,5 +195,18 @@ class correctlyFormattedClassMemberDocBlock */ protected string $itIsCorrect; + private string $typedPropertyWithoutComment; + + private string $typedPropertyWithoutComment2; + + private ?string $typedPropertyWithoutComment3; + + private string|int $typedPropertyWithoutComment4; + + private Test $typedPropertyWithoutComment5; + + private Test|Test2 $typedPropertyWithoutComment6; + + private ?Test $typedPropertyWithoutComment7; } From 1e608001ea2ad7858d227b64bebf1ae0c923265e Mon Sep 17 00:00:00 2001 From: Lachlan Turner <40189797+aligent-lturner@users.noreply.github.com> Date: Thu, 14 Jul 2022 21:06:32 +0930 Subject: [PATCH 5/5] Remove extra line Co-authored-by: Ihor Sviziev --- .../Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc | 2 -- 1 file changed, 2 deletions(-) diff --git a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc index 10f01731..fa06bdc9 100644 --- a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc +++ b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc @@ -194,8 +194,6 @@ class correctlyFormattedClassMemberDocBlock * @see Message with some reference */ protected string $itIsCorrect; - - private string $typedPropertyWithoutComment; private string $typedPropertyWithoutComment2;