Deprecated methods/functions/classes/hooks should be included in the @since tax archive for the version they were deprecated in

[pbiron]

For example ​wp_ajax_wp_fullscreen_save_post() was deprecated in 4.3.0 but does not show up in the @since tax archive for that version: ​https://developer.wordpress.org/reference/since/4.3.0/?post_type%5B0%5D=wp-parser-function.

Such deprecated items correctly have the deprecated callout and the version they were deprecated in correctly appears in the Changelog section.

I think this is necessary for consistency with how other "modifications" are handled.

For example, when viewing ​add_rewrite_endpoint(), if I click on the ​4.3.0 link in the Changelog section (and paginate far enough) I will find add_rewrite_endpoint(). I was suprised to find out that the same doesn't happen for the equivalent links when the Changelog entry is for deprecation.

The necessary fix is in ​phpdoc-parser. I'll do a PR against phpdoc-parser if folks agree the suggestion is a good one.

Related: #1926

[obenland]

I don't know, at first glance it feels like the since archive is meant to document functions etc that were first introduced in that release? You could argue that it would be like showing posts in date archives for both their publishing date and their last modified date.

What if we didn't link to the since archive except for when it was introduced?

[pbiron]

Replying to obenland:

I don't know, at first glance it feels like the since archive is meant to document functions etc that were first introduced in that release? You could argue that it would be like showing posts in date archives for both their publishing date and their last modified date.

Others may disagree (and I'll certainly accept that if my opinion is the minority one), but I don't think that analogy is a good one. I think developer documentation is different kind of animal!

Maybe the following was not the original intended use of the @since archive, but one of the ways I use it is similar to how I use the following PHP/Java documentation pages:

• ​PHP Changelog
• ​Migrating from PHP 7.1.x to PHP 7.2.x
  • ​New functions
  • ​Backward incompatible changes
  • ​Deprecated features in PHP 7.2.x
  • etc
• ​Deprecated API
  • altho in the Java documentation case, they are not as good at making it easy to see what has been deprecated in a specific version

That is, by letting me know what I might have to change in plugins/themes I've written as new versions come out.

That was part of the motivation behind #2847.

I came across this case of deprecations not being included in the @since archive while working on an update to the patch in #2847 (and the CLI plugin mentioned in 2847#comment:4).

Maybe I'm the only who uses the @since archive in that way, but I doubt it.

[pbiron]

Related: #2847

[pbiron]

see 2847#comment:9. The patch I just added there implements the idea in this ticket.

[obenland]

Can we merge this ticket with #2847?