Skip to content

Commit ee3ddb3

Browse files
committedAug 16, 2023
Member variables and methods should not require DocBlock when properly typed
https://developer.adobe.com/commerce/php/coding-standards/docblock/ > Include all necessary information without duplication. Example 1: ``` private ?ObjectManagerInterface $objectManager; ``` should not require a comment ``` /** @var ObjectManagerInterface|null $objectManager */ ``` because all of that information is duplicated. (Though the nullable is actually harder to read in DocBlock standard.) Example 2: ``` public function getWeakMap() : WeakMap { return $this->weakMap; } ``` This method is expressive. It is obvious what it does. It is strictly typed. There is no reason that it should need a DocBlock. This change no longer requires DocBlock in these cases: 1: member variables that have defined types 2: methods where all parameters have defined types AND method has defined return type (__construct and __destruct won't require return type, since it isn't allowed)
1 parent 99e3ae2 commit ee3ddb3

File tree

2 files changed

+23
-0
lines changed

2 files changed

+23
-0
lines changed
 

Diff for: ‎Magento2/Sniffs/Annotation/MethodArgumentsSniff.php

+19
Original file line numberDiff line numberDiff line change
@@ -568,6 +568,25 @@ public function process(File $phpcsFile, $stackPtr)
568568
$previousCommentClosePtr = $phpcsFile->findPrevious(T_DOC_COMMENT_CLOSE_TAG, $stackPtr - 1, 0);
569569
if ($previousCommentClosePtr && $previousCommentOpenPtr) {
570570
if (!$this->validateCommentBlockExists($phpcsFile, $previousCommentClosePtr, $stackPtr)) {
571+
$foundAllParameterTypes = true;
572+
$methodParameters = $phpcsFile->getMethodParameters($stackPtr);
573+
foreach ($methodParameters as $parameter) {
574+
if (!$parameter['type_hint']) {
575+
$foundAllParameterTypes = false;
576+
break;
577+
}
578+
}
579+
if ($foundAllParameterTypes) {
580+
$methodProperties = $phpcsFile->getMethodProperties($stackPtr);
581+
$foundReturnType = !!$methodProperties['return_type'];
582+
if ($foundReturnType) {
583+
return; // We don't need comment if all parameters and return value are typed
584+
}
585+
$methodName = $phpcsFile->getDeclarationName($stackPtr);
586+
if ('__construct' == $methodName || '__destruct' == $methodName) {
587+
return; // __construct and __destruct can't have return types, so they don't need comment
588+
}
589+
}
571590
$phpcsFile->addError('Comment block is missing', $stackPtr, 'NoCommentBlock');
572591
return;
573592
}

Diff for: ‎Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php

+4
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@ public function processMemberVar(File $phpcsFile, $stackPtr)
6464
);
6565

6666
if ($commentEnd === false || $tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG) {
67+
$propertyInfo = $phpcsFile->getMemberProperties($stackPtr);
68+
if ($propertyInfo['type']) {
69+
return; // If variable has a type, it is okay to not have a DocBlock
70+
}
6771
$phpcsFile->addWarning('Missing PHP DocBlock for class property.', $stackPtr, 'Missing');
6872
return;
6973
}

0 commit comments

Comments
 (0)