Generics: Add support for generic type hints in comments

[Karpec]

Description

Enhanced the FunctionCommentSniff to recognize and correctly suggest generic type hints by extracting the main type from parameter annotations. Added corresponding unit tests to verify this functionality, ensuring better adherence to modern PHPDoc standards with generic collections.

Suggested changelog entry

Related issues/external references

Fixes #746

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
  • This change is only breaking for integrators, not for external standards or end-users.
• Documentation improvement

PR checklist

• I have checked there is no other PR open for the same change.
• I have read the Contribution Guidelines.
• I grant the project the right to include and distribute the code under the BSD-3-Clause license (and I have the right to grant these rights).
• I have added tests to cover my changes.
• I have verified that the code complies with the projects coding standards.
• [Required for new sniffs] I have added XML documentation for the sniff.

[jrfnl]

@Karpec Thanks for creating this PR and for your willingness to contribute.

Looking at this PR though, it seems like it is a literal copy of upstream PR squizlabs/PHP_CodeSniffer#3544 ?
This violates copyright and does not do justice to the original author. I cannot and will not accept that.
I suggest you read the CONTRIBUTING GUIDE, in particular the explicit section about not violating copyright.

There was a reason why I pinged the original author @tm1000, asking them to port the PR over. If they are not available to do so, cherrypicking their commit and then adding to it would be an acceptable alternative. What you've done now, is not.

Aside from that, the PR also doesn't address my remark about the need for some additional tests.

All in all, this PR can unfortunately not be accepted this way.

[tm1000]

@jrfnl thanks for that kind and OSS response. This totally slipped my mind. I have issued a new PR and I am working on upgrading it now: #750

[jrfnl]

Much appreciated @tm1000!

[Karpec]

@jrfnl Thank you for your feedback and for pointing this out. I sincerely apologize for the oversight. I didn’t expect that @tm1000 would have the time and willingness to address this issue after such a long time, and I truly appreciate his effort in resolving it.

It was never my intention to take credit for someone else’s work. If a similar situation arises in the future, I agree that cherrypicking the commit and building upon it would be a much better approach.

I hope @tm1000 isn’t upset about this, and I’m genuinely grateful that he found the time to help resolve this matter. If there’s any way I can assist further, please let me know.