Generic/CallTimePassByReference: add support for self, parent and static

[rodrigoprimo]

Description

This PR changes the Generic.Functions.CallTimePassByReference sniff to trigger an error when the parent, self, or static tokens are used to instantiate a class containing a variable passed by reference. In a separate commit, it also sorts alphabetically the list of tokens this sniff listens to.

Suggested changelog entry

Generic.Functions.CallTimePassByReference: flag call-time pass-by-reference when instantiating a class using parent, self, or static.

Related issues/external references

Suggested in #394 (review)

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]

Thanks @rodrigoprimo LGTM.

As a side-note: I'm not a fan of always sorting the tokens in register() alphabetically.
On the one hand it makes history tracing more difficult; on the other hand, the tokens are often sorted by the kind of language structure they represent, so sorting them alphabetically increases the cognitive load.

Sorting makes sense when all tokens represent the same type of language structure, but that's not the case here.

[rodrigoprimo]

Thanks for the review, @jrfnl!

As a side-note: I'm not a fan of always sorting the tokens in register() alphabetically.
On the one hand it makes history tracing more difficult; on the other hand, the tokens are often sorted by the kind of language structure they represent, so sorting them increases the cognitive load.

Sorting makes sense when all tokens represent the same type of language structure, but that's not the case here.

Noted. Let me know if you prefer that I drop the commit that sorts the tokens in this PR.

[jrfnl]

Let me know if you prefer that I drop the commit that sorts the tokens in this PR.

Well, I've said what I had to say about it. It's now up to you to decide what to do with it.

[rodrigoprimo]

My impression is that it is better to sort the tokens alphabetically for all the sniffs. That being said, I have way less experience than you, so I trust your opinion more than mine on this matter. I went ahead and dropped the commit. I added the tokens to the end of the list grouped together with the T_ANON_CLASS as all those tokens relate to classes and objects. I'm not sure if that is the organization that you had in mind.

[jrfnl]

Rebased without changes. Merging once the build passes.