Plugin: Fix WooCommerce hook comment phpcs reports

[reykjalin]

Part of #8437.

Description

Remove all the WooCommerce.Commenting excludes from phpcs.xml.dist and fix the issues reported when running npm run lint:php in the following files:

• src/Internal/Proxy/HooksProxy.php
• tests/unit/src/Internal/Proxy/HooksProxyTest.php
• tests/unit/helpers/class-wc-helper-product.php
• includes/core/class-mode.php
• src/Internal/Payment/Router.php
• tests/unit/core/server/request/test-class-get-request.php
• includes/class-wc-payments-dependency-service.php
• tests/unit/core/server/request/test-class-core-request.php
• includes/class-wc-payments-features.php
• includes/class-database-cache.php
• includes/core/server/class-request.php
• includes/wc-payment-api/class-wc-payments-api-client.php
• includes/class-wc-payments-webhook-processing-service.php
• tests/unit/test-class-wc-payments.php
• includes/class-wc-payments.php

[vbelolapotkov]

@reykjalin have you searched for a reference on how doc block for hooks should look like to be valuable? In particular, how @since attribute should be configured?

In some cases we hook into filters/action introduced somewhere else, e.g. Woo core, and sometimes we call/trigger hooks introduced somewhere else (outside WooPayments). In other cases we call/trigger hooks created by ourselves.

Those are different scenarios and should be documented differently.

[reykjalin]

The documentation standards are documented for WP in general here. The most salient parts:

Both action and filter hooks should be documented on the line immediately preceding the call to do_action() or do_action_ref_array(), or apply_filters() or apply_filters_ref_array(), and formatted as follows:

• Summary: A brief, one line explanation of the purpose of the hook. Use a period at the end.
• Description: A supplemental description to the summary, if warranted.
• **@ignore**: Used when a hook is meant only for internal use and should be skipped from parsing.
• **@since x.x.x**: Should always be 3-digit (e.g. @since 3.9.0). Exception is @since MU (3.0.0).
• **@param**: If the parameter is an array of arguments, document each argument using a hash notation (described above in the Parameters That Are Arrays section), and include a period at the end of each line.

Note that @return is not used for hook documentation, because action hooks return nothing, and filter hooks always return their first parameter.

[…]

Occasionally, hooks will be used multiple times in the same or separate core files. In these cases, rather than list the entire DocBlock every time, only the first-added or most logically-placed version of an action or filter will be fully documented. Subsequent versions should have a single-line comment.

For actions:

/** This action is documented in path/to/filename.php */

For filters:

/** This filter is documented in path/to/filename.php */

The example doc block provided looks like this:

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Short description about this hash.
 *
 *     @type type $var Description.
 *     @type type $var Description.
 * }
 * @param type  $var Description.
 */

---

In some cases we hook into filters/action introduced somewhere else, e.g. Woo core, and sometimes we call/trigger hooks introduced somewhere else (outside WooPayments).

Then we should use a comment like

/** This (action|filter) is documented in path/to/filename.php */

e.g.

/** This action is documented in https://github.com/woocommerce/woocommerce/permalink/to/file.php */

or

/** This action is documented in /woocommerce/permalink/to/file.php */
                                 ^ arbitrary forward slash we could use to indicate "not this repository".

---

In other cases we call/trigger hooks created by ourselves.

We should document these hooks where they're first added (or where it makes most sense according to what the dev doing the changes deems makes "most sense"), and other places should add a comment like

/** This (action|filter) is documented in path/to/filename.php */

---

particular, how @since attribute should be configured?

This should have the first release version of WooPayments that included this action/hook.