Hook docblocks

[szepeviktor]

Describe the bug

Hook docblocks are not standard (compared to WordPress core, PHPStan)

safe-redirect-manager/inc/functions.php

Lines 112 to 119 in fb74c57

	/**
	* Valid status codes to redirect with.
	*
	* @hook srm_valid_status_codes
	* @param {array} $status_codes Valid status codes to redirect with. Default array( 301, 302, 303, 307, 403, 404, 410 ) and other codes returned by `srm_additional_status_codes` filter hook.
	* @returns {array} Filtered valid status codes.
	*/
	return apply_filters( 'srm_valid_status_codes', array_keys( srm_get_valid_status_codes_data() ) );

Steps to Reproduce

• There is no need to declare the hook name in the docblock
• The first @param is the third parameter of apply_filters, the first one is the hook name, the second one is the initial value
• Current docblock is a JSDoc block, not PHPDoc

Would you merge a PR fixing all those?

Screenshots, screen recording, code snippet

No response

Environment information

No response

WordPress information

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[dkotter]

• There is no need to declare the hook name in the docblock
• The first @param is the third parameter of apply_filters, the first one is the hook name, the second one is the initial value
• Current docblock is a JSDoc block, not PHPDoc

All of these are expected as we use the wp-hookdoc tool to automatically create a documentation site (see https://10up.github.io/safe-redirect-manager/).

wp-hookdoc utilizes JSDoc to process these comments, which is why these docblocks are different from what we use on functions or methods.

We are exploring a new tool to automate this documentation but there's no timeline on when that will happen, so going to close this out.

[szepeviktor]

I see. That project is abandoned 6 years ago.