From 3332dbaf8c33e5ad00bcf6fd8c209b28ba5fbe90 Mon Sep 17 00:00:00 2001
From: Lachlan Turner <lachlan.turner@aligent.com.au>
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 <lachlan.turner@aligent.com.au>
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 <lachlan.turner@aligent.com.au>
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 <ihor-sviziev@users.noreply.github.com>
---
.../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 <ihor-sviziev@users.noreply.github.com>
---
.../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;