WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#28806 closed defect (bug) (fixed)

More complete and consistent @deprecated inline docs/tags

Reported by: Alphawolf Owned by: DrewAPicture
Milestone: 4.4 Priority: low
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description (last modified by DrewAPicture)

Hey folks, I noticed some @deprecated inline docs were inconsistent and/or incorrect for various functions so I went and did the following things:

  • Changed the @deprecated inline tag(s) to follow the new inline docs standard written last year
  • Added version information if missing but known
  • Added fourth parameter (what to use instead) to _deprecated_function() if missing but known
  • More consistent wording throughout the @deprecated inline docs

Patch attached.

ps. First patch (AFAIR). :)

Attachments (5)

28806.diff (58.6 KB) - added by Alphawolf 7 years ago.
28806.2.diff (58.4 KB) - added by Alphawolf 7 years ago.
Re-uploaded the patch with a few typos fixed.
28806.3.diff (58.2 KB) - added by Alphawolf 7 years ago.
Re-upload with more incorrect data fixed. Sry. :)
28806.4.diff (64.4 KB) - added by Alphawolf 7 years ago.
Fixed issues found by @jdgrimes
28806.5.diff (59.4 KB) - added by Alphawolf 7 years ago.
To self: Don't touch lines of code just for the thrill of it.

Download all attachments as: .zip

Change History (30)

@Alphawolf
7 years ago

#1 @Alphawolf
7 years ago

  • Keywords has-patch added
  • Severity changed from normal to minor
  • Type changed from defect (bug) to enhancement

@Alphawolf
7 years ago

Re-uploaded the patch with a few typos fixed.

@Alphawolf
7 years ago

Re-upload with more incorrect data fixed. Sry. :)

#2 follow-up: @jdgrimes
7 years ago

A few issues in 28806.3.diff:

  • A second closing parenthesis is missing on line 957 of /wp-admin/includes/deprecated.php.
  • deactivate_sitewide_plugin() should be replaced with deactivate_plugin(), right now it is deprecated in favor of itself.
  • Some coding standards fixes in /wp-includes/deprecated.php. E.g.: * @deprecated 2.8.0 Use the_author_meta('description') should be the_author_meta( 'description' )

@Alphawolf
7 years ago

Fixed issues found by @jdgrimes

#3 in reply to: ↑ 2 ; follow-up: @Alphawolf
7 years ago

Replying to jdgrimes:

  • Some coding standards fixes in /wp-includes/deprecated.php. E.g.: * @deprecated 2.8.0 Use the_author_meta('description') should be the_author_meta( 'description' )

Some occurrences of _deprecated_function did not meet the coding standards it seems (while some did throughout the code), e.g.
_deprecated_function( __FUNCTION__, '2.8', 'get_the_author_meta(\'description\')' );
which (among others) I changed to
_deprecated_function( __FUNCTION__, '2.8', 'get_the_author_meta( \'description\' )' );

Or did you only refer to the doc blocks? :)

#4 in reply to: ↑ 3 ; follow-up: @jdgrimes
7 years ago

Replying to Alphawolf:

Or did you only refer to the doc blocks? :)

Yes, that's what I was meaning. :)

#5 @SergeyBiryukov
7 years ago

  • Milestone changed from Awaiting Review to 4.0

#6 in reply to: ↑ 4 ; follow-up: @Alphawolf
7 years ago

Replying to jdgrimes:

Replying to Alphawolf:

Or did you only refer to the doc blocks? :)

Yes, that's what I was meaning. :)

Okay, so ignore the different notations of _deprecated_function's fourth parameter with some having whitespaces while others don't? :)

#7 in reply to: ↑ 6 ; follow-up: @jdgrimes
7 years ago

Replying to Alphawolf:

Okay, so ignore the different notations of _deprecated_function's fourth parameter with some having whitespaces while others don't? :)

Yeah, I wouldn't change them. Except, maybe if there are any where you are editing the other parameters as well, you might change those. Usually we try to avoid changing things just for coding standards unless we're making other changes around it. So if you're editing that line anyway, you can clean up the spacing, but otherwise they will generally want to leave it be.

Last edited 7 years ago by jdgrimes (previous) (diff)

#8 in reply to: ↑ 7 @Alphawolf
7 years ago

Replying to jdgrimes:

Yeah, I wouldn't change them. Except, maybe if there are any where you are editing the other parameters as well, you might change those. Usually we try to avoid changing things just for coding standards unless we're making other changes around it. So if you're editing that line anyway, you can clean up the spacing, but otherwise they will generally want to leave it be.

Alright, will leave them be unless I changed the lines anways. New patch incoming soon. :)

ps. Sorry for spamming patches.

Last edited 7 years ago by Alphawolf (previous) (diff)

#9 @DrewAPicture
7 years ago

  • Type changed from enhancement to defect (bug)

@Alphawolf
7 years ago

To self: Don't touch lines of code just for the thrill of it.

#10 @DrewAPicture
7 years ago

  • Milestone changed from 4.0 to Future Release

This will likely span beyond 4.0.

#11 @johnbillion
7 years ago

  • Version trunk deleted

#12 @DrewAPicture
7 years ago

  • Severity changed from minor to normal

#13 @DrewAPicture
6 years ago

  • Priority changed from normal to low

This ticket was mentioned in Slack in #core by drew. View the logs.


6 years ago

#15 @DrewAPicture
6 years ago

  • Description modified (diff)
Last edited 6 years ago by DrewAPicture (previous) (diff)

#16 @DrewAPicture
6 years ago

In 33671:

Docs: Standardize @deprecated tag formatting and add missing DocBlocks to deprecated functions in wp-admin/includes/deprecated.php.

Opted not to use the multi-function DocBlock syntax in the name of not taking shortcuts in documentation for the sake of brevity.

Props Alphawolf for the initial patch.
See #28806

#17 @DrewAPicture
6 years ago

In 33673:

Docs: Standardize @deprecated tag formatting and add missing DocBlock summaries to deprecated functions in wp-includes/deprecated.php.

Props Alphawolf for the initial patch.
Props DrewAPicture.

See #28806.

#18 @DrewAPicture
6 years ago

In 33674:

Docs: Standardize @deprecated tag formatting for deprecated functions in wp-includes/pluggable-deprecated.php.

Props Alphawolf for the initial patch.
Props DrewAPicture.

See #28806.

#19 @DrewAPicture
6 years ago

In 33675:

Docs: Standardize @deprecated tag formatting for deprecated functions in wp-admin/includes/ms-deprecated.php.

Props Alphawolf for the initial patch
Props DrewAPicture

See #28806.

#20 @DrewAPicture
6 years ago

In 33676:

Docs: Standardize @deprecated tag formatting and add missing summaries to deprecated functions in wp-includes/ms-deprecated.php.

Props Alphawolf for the initial patch.
Props DrewAPicture

See #28806.

#21 @DrewAPicture
6 years ago

In 33677:

Docs: Standardize @deprecated tag formatting in the DocBlock for wp_xmlrpc_server::login_pass_ok().

Props Alphawolf.
See #28806.

#22 @DrewAPicture
6 years ago

In 33678:

Docs: Standardize @deprecated tag formatting in the DocBlock for WP_Object_Cache:reset().

Props Alphawolf.
See #28806.

#23 @DrewAPicture
6 years ago

In 33679:

Docs: Standardize @deprecated tag formatting in the DocBlocks for several wpdb methods.

Props Alphawolf.
See #28806.

#24 @DrewAPicture
6 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 33680:

Docs: Standardize @deprecated tag formatting in the DocBlock for the logIO() function.

Props Alphawolf.
Fixes #28806.

#25 @DrewAPicture
6 years ago

  • Milestone changed from Future Release to 4.4

New tickets for new issues. @Alphawolf: Thanks for the initial work!

Note: See TracTickets for help on using tickets.