Skip to content

Allow to skip see tag in annotation with specific deprecated comment #419

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 5 commits into from
Sep 1, 2022
Merged

Allow to skip see tag in annotation with specific deprecated comment #419

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2cf24b3
Implement changes approved to @see tag in Dev guild
loginesta Aug 31, 2022
922e108
Add without replacement
loginesta Aug 31, 2022
30bed95
Update condition for stripos
loginesta Aug 31, 2022
180c510
Update boolean comparison on condition
loginesta Aug 31, 2022
246c67b
Refactor: Use preg_match
loginesta Sep 1, 2022
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
7 changes: 7 additions & 0 deletions Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@
*/
class PHPDocFormattingValidator
{
private const REMOVED_IN_VERSION = 'removed in version';
private const WITHOUT_REPLACEMENT = 'without replacement';

/**
* Finds matching PHPDoc for current pointer
*
Expand Down Expand Up @@ -123,6 +126,10 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
}
$seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
if ($seePtr === -1) {
if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) !== false &&
Copy link
Member

@sivaschenko sivaschenko Sep 1, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Expected:
@deprecated This method will be removed in version 2.x.x without replacement

Actual:

  1. @deprecated removed in versionwithout replacement
  2. @deprecated without replacementremoved in version

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the useful comment! I've done a refactor to use preg_match instead

stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0) !== false) {
return true;
}
return false;
}

Expand Down
20 changes: 20 additions & 0 deletions Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,4 +369,24 @@ class MethodAnnotationFixture
{
return true;
}

/**
* This deprecated function is correct even though it only contains the @deprecated tag.
*
* @deprecated It will be removed in version 1.0.0 without replacement
*/
public function correctBecauseOfKeywordPhrase()
{
return false;
}

/**
* This deprecated function is correct even though it only contains the @deprecated tag.
*
* @deprecated WOW! It will be removed in version 1.0.0 without replacement
*/
public function alsoCorrectBecauseOfKeywordPhrase()
{
return false;
}
}
17 changes: 17 additions & 0 deletions Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,3 +162,20 @@ class OldHandler
{

}

/**
* @deprecated It will be removed in version 1.0.0 without replacement
*/
class DeprecatedButHandler
{

}

/**
* @deprecated It's also deprecated, but it will be removed in version 1.0.0 without replacement
*/
class AlsoDeprecatedButHandler
{

}

16 changes: 16 additions & 0 deletions Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,3 +153,19 @@ interface DoNotCareHandler
{

}

/**
* @deprecated This interface will be removed in version 1.0.0 without replacement
*/
interface DeprecatedButHandler
{

}

/**
* @deprecated Yeah! This interface will be removed in version 1.0.0 without replacement
*/
interface AlsoDeprecatedButHandler
{

}
6 changes: 6 additions & 0 deletions Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,4 +194,10 @@ class correctlyFormattedClassMemberDocBlock
* @see Message with some reference
*/
protected string $itIsCorrect;

/**
* @var string
* @deprecated This property will be removed in version 1.0.0 without replacement
*/
protected string $deprecatedWithKeyword;
}
10 changes: 10 additions & 0 deletions Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,14 @@ class Profiler
* @see
*/
const d = 100;

/**
* @deprecated This constant will be removed in version 1.0.0 without replacement
*/
const KEYWORD_PHRASE = false;

/**
* @deprecated It's awesome - This constant will be removed in version 1.0.0 without replacement
*/
const WITH_KEYWORD_PHRASE = false;
}