Improves PHPDoc of template_redirect hook, following the example of the official documentation.

​https://developer.wordpress.org/reference/hooks/template_redirect/

Trac ticket: https://core.trac.wordpress.org/ticket/64018#ticket

In 60791:

Thanks for the ticket!

Replying to apermo:

The inline documentation of template_redirect is minimalistic at best

It is perhaps worth noting for future reference that this is actually encouraged by the ​documentation standards:

Summaries should be clear, simple, and brief. Avoid describing “why” an element exists, rather, focus on documenting “what” and “when” it does something.
...
Actions: When does an action fire?

• Good: Fires after most of core is loaded, and the user is authenticated.
• Bad: Allows you to register custom post types, custom taxonomies, and other general housekeeping tasks after a lot of WordPress core has loaded.

...
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.

However, I also noticed that some hooks do include an extended description, e.g. mce_external_plugins, exit_on_http_head, enable_wp_debug_mode_checks, etc. So [60791] adds that for template_redirect.

Thanks @SergeyBiryukov for the merge and for the point to the doc standards.

As mentioned above, I realized that the hook was regularly misunderstood, and the added documentation is a shortened version of the official documentation of the filter.

And as you quoted:

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.

In that case I found it is warranted to describe a bit further what to use it for, and what alternative filter you should look for, for the regular misuse.

Replying to apermo:

As mentioned above, I realized that the hook was regularly misunderstood, and the added documentation is a shortened version of the official documentation of the filter.

Thanks! I chose to include the full version of it, so that all the context is available after this DocBlock is imported to the developer reference following the 6.9 release. (I think the existing More Information block on that page should then be removed to avoid duplicate information.)