Handle hook deprecation in the DevHub theme

[DrewAPicture]

In ​#core10441, the core team is working on adding proper hook deprecation in the form of two new functions: apply_filters_deprecated() and do_action_deprecated().

We'll obviously need to make some adjustments to ​the parser to properly route the new function calls, but we also might need to adjust some minor things in the DevHub theme, such as ensuring the deprecation callout box can handle a notice for hooks and corresponding replacement hook links.

Looks like we use link_internal_element() inside of get_deprecated() to handle linking replacements, so in the interest of simplicity, we might need to add an additional case for hooks referenced simply with 'hook_name'. This would be for the context of deprecated hook docs that look like this:

<?php
/**
 * Some now-deprecated hook.
 *
 * @since 2.6.0
 * @deprecated 4.6.0 Use 'replacement_hook' instead.
 * @see 'replacement_hook'

We may very well already be in the clear, but it doesn't hurt to have a tracking ticket here in case there's something we're missing.

[DrewAPicture]

1766.diff​ adds some handling for a few things:

• A new string label for archive results: "Action Hook (deprecated)" or "Filter Hook (deprecated)". Since we have the opportunity to indicate deprecated status in the archive view, we should take it. Nothing worse than clicking through to what you think is a legit hook only to discover it's deprecated. I feel like we should do this for other stuff too, but that's another ticket :-)

• Adds an optional parameter to link_internal_element() that allows us to selectively preg_match() against arbitrary content for a hook reference in the form of 'hook_name'. Currently it only handles inline @see references, e.g. {@see 'hook_name'} which come through encoded as ‘hook_name’ This is important for handling linking for the deprecated notice, so if we do @see 'hook_name' as top-level DocBlock tag, it's still possible to parse that as a linkable hook instead of just a string.

• Leverages two new hook types that will have to be implemented at the parser level: 'action_deprecated' and 'filter_deprecated' to make much of the above possible

• Display deprecated hooks with apply_filters_deprecrated or do_action_deprecated in the reference single page

[DrewAPicture]

PR created for the corresponding parser changes: ​#178.

[DrewAPicture]

Refresh

[DrewAPicture]

Now that we actually have deprecated hooks in core, it's time to commit this. I've just merged the PR on the parser repo and refreshed the patch here. We're good to go.

@coffee2code, can you please review the patch?

[coffee2code]

In 5598:

developer.wordpress.org: Handle hook deprecation.

Props DrewAPicture.
Fixes #1766.

[DrewAPicture]

RegEx fix

[coffee2code]

In 5606:

developer.wordpress.org: Revert functional changes to link_internal_element() from [5598] as the need was handled in [5577].

See #1766.