Enforce @since tags in DocBlocks

[anton-vlasenko]

What?

This PR enhances support for checking @since tags within various code elements such as class, trait, interface, enum declarations, properties, and method declarations. Additionally, it extends support to check @since tags for WordPress functions that invoke hooks like 'do_action', 'do_action_ref_array', 'apply_filters', and 'apply_filters_ref_array'.

The sniff only checks /** style comments.
The sniffs supports multiple @since tags per token.

Fixes #1994
Note: this PR is a backport of WordPress/gutenberg#60007 to WPCS.

Why?

This PR improves the overall code adherence to WordPress coding standards. By enforcing @since tags, it ensures better documentation and version tracking, making it easier for developers to understand the evolution of the codebase over time.

How?

• Added support for checking @since tags for class, trait, interface, and enum declarations.
• Added support for checking @since tags for class and trait properties;
• Added support for checking @since tags for class, interface, and trait method declarations;
• Added support for checking @since tags for WordPress functions that invoke hooks: do_action(), do_action_ref_array(), apply_filters(), apply_filters_ref_array().

Testing Instructions

1. Define a class, trait, interface, and enum without a @since tag and ensure that the linter checks fail.
2. Define a function, class method, interface method, and trait method without a @since tag and ensure that the linter checks fail. Ensure that the sniff skips checking private methods.
3. Attempt to use one of the WordPress functions that invoke hooks such as do_action(), do_action_ref_array(), apply_filters(), apply_filters_ref_array() without specifying a @since tag. Confirm that the linter checks fail.
4. Define a class property or trait property without a @since tag and ensure that the linter checks fail.

Testing Instructions for Keyboard

Screenshots or screencast

[anton-vlasenko]

Question: should this sniff be disabled for files in this repository that expectedly cause the Basic QA checks CI jobs to fail due to the absence of @since tags?

[jrfnl]

@anton-vlasenko I have a feeling we will not be able to accept this PR as:

1. It was originally accepted into the Gutenberg repo, which is licensed under GPL, while this repo is licensed under MIT. Why was it pulled there anyway ? Why was this not pulled directly to this repo ?
2. Based on the conversation in the ticket in the GB repo, you have violated copyright on code in a number of places.

[azaozz]

@jrfnl Yes, you're right that generally GPL licensed code cannot be added (copied, forked, etc.) to a MIT licensed project. The opposite seems possible.

However thinking this is quite more complicated :)
I'm not sure if it makes any difference where that code was contributed first. Afaik the author of the code can decide how to license it. Think that also includes the possibility to contribute to different projects, release it "in the public domain", etc.

Also, afaik, in general one open source project can contribute code (usually bug-fixes?) to another open source project. Since both Gutenberg and WPCS are under the WordPress "umbrella" and are to benefit the WP community as a whole, thinking that such contributions would probably be welcome.

[dingo-d]

If I recall correctly, we (and by we I mean Juliette because she is realistically the only one writing sniffs atm) deliberately decided not to write docs-specific sniffs because WP docs are even more different than the proposed PSR-5 and PSR-19 (still in draft). Because of how WP doc blocks are parsed for documentation generation, how we write the array parameters in doc-blocks, etc..

Writing sniffs only to fix and modify them later would be a waste of time.

Plus, if we were to start writing sniffs specifically for doc-blocs, and its structure, I'd expect them to be in a separate namespace from Commenting. I'd prefer them to be in a Documentation namespace so that we could add different sniffs for different parts of the doc-block.

[jrfnl]

I'm not sure if it makes any difference where that code was contributed first. Afaik the author of the code can decide how to license it. Think that also includes the possibility to contribute to different projects, release it "in the public domain", etc.

@azaozz Where it was contributed first is exactly the problem. If the code had been pulled to both projects around the same time, there wouldn't be a problem.

However, the code/the PR has been accepted and merged into the GB repo before it was pulled here. This makes it effectively GPL code, which we cannot accept into an MIT licensed repo.

We've had discussions like this before regarding code I wrote to be used by both WPCS as well as PHPCompatibility, with PHPCompatibility being licensed under the lGPL license (this was before PHPCSUtils existed).
The conclusion was: pull the code to both repos at the same time as otherwise there is a licensing problem.

[jrfnl]

Closing as something we cannot even consider due to the licensing issues.