Making WordPress.org

Opened 6 years ago

Last modified 5 years ago

#3699 new enhancement

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

Reported by: pbiron's profile pbiron Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords: 2nd-opinion
Cc:

Description

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

Change History (6)

#1 follow-up: @obenland
6 years ago

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?

#2 in reply to: ↑ 1 @pbiron
6 years ago

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:

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.

Last edited 6 years ago by pbiron (previous) (diff)

#3 @pbiron
6 years ago

Related: #2847

#4 @pbiron
6 years ago

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

Last edited 6 years ago by pbiron (previous) (diff)

#5 @obenland
6 years ago

Can we merge this ticket with #2847?

This ticket was mentioned in Slack in #meta-devhub by keesiemeijer. View the logs.


5 years ago

Note: See TracTickets for help on using tickets.