#162 Modified @deprecated validator to consider it valid if comment is absent but @see tag is set

[sinisa86]

Modified @deprecated validator to consider it valid if a comment is absent but @see tag is set.
see #162

[m2-community-project]

@sinisa86 unfortunately, only members of the maintainers team are allowed to assign developers to the pull request

[m2-community-project]

@sinisa86 unfortunately, only members of the maintainers team are allowed to assign developers to the pull request

[lenaorobei]

else can be eliminated here.

[sinisa86]

If we remove "else" branch there, it could lead to unexpected behavior because of the next IF condition:
if ($tokens[$seePtr + 2]['code'] !== T_DOC_COMMENT_STRING) { return false; }
That happens because $seePtr could be -1, so $seePtr + 2 points to how-knows-what.
"Else" part is required because it covers behavior when @see is not present at all.

[sinisa86]

Actually, it really fails on some regular tests when I remove "else" branch.

[lenaorobei]

$seeTagRequired is boolean and if it is false, execution will drop to else or directly to the return.

I propose to simplify code even more:

        $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
        if ($seePtr === -1) {
            return !$seeTagRequired;
        }
        return $tokens[$seePtr + 2]['code'] === T_DOC_COMMENT_STRING;

[lenaorobei]

@sinisa86 could you please address review comments?

[sinisa86]

@sinisa86 could you please address review comments?

Done.
I'm still a little bit more for an option before applying the last changes because it gives you information about whether @deprecated is well-formatted (true/false). Now, when it returns !seeTagRequired, it doesn't tell clearly what's returned in that case (it returns the information that seeTagIsRequired or not, which may seem unrelated to the function name and its purpose). Although this provides the same functionality, it doesn't provide the same level of clarity.
On the bottom line - it's a just one "IF" condition :)

[ihor-sviziev]

@lenaorobei could you check this PR?

[lenaorobei]

@sinisa86 thanks for this contribution and your patience!