From ff7831207c6e90764297a37482c54abba1f47f88 Mon Sep 17 00:00:00 2001
From: westi <westi@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Wed, 30 Dec 2009 16:23:39 +0000
Subject: [PATCH] Updates and improvements to _depreceated_argument. See #11386
 props nacin.

git-svn-id: http://svn.automattic.com/wordpress/trunk@12584 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/includes/image.php      |  3 +++
 wp-admin/includes/meta-boxes.php |  3 +++
 wp-admin/includes/upgrade.php    |  5 ++++-
 wp-app.php                       |  4 +++-
 wp-includes/author-template.php  | 14 ++++++++------
 wp-includes/comment-template.php | 32 ++++++++++++++++++++------------
 wp-includes/comment.php          |  6 +++---
 wp-includes/cron.php             |  2 +-
 wp-includes/formatting.php       |  3 +++
 wp-includes/functions.php        | 27 +++++++++++++++++++--------
 wp-includes/kses.php             |  3 +++
 wp-includes/link-template.php    |  5 ++++-
 wp-includes/post-template.php    |  9 ++++++---
 wp-includes/post.php             |  6 ++++--
 wp-includes/widgets.php          |  2 +-
 15 files changed, 85 insertions(+), 39 deletions(-)

diff --git a/wp-admin/includes/image.php b/wp-admin/includes/image.php
index f1cd972f34..cd88e4dc81 100644
--- a/wp-admin/includes/image.php
+++ b/wp-admin/includes/image.php
@@ -17,9 +17,12 @@
  *
  * @param mixed $file Filename of the original image, Or attachment id.
  * @param int $max_side Maximum length of a single side for the thumbnail.
+ * @param mixed $deprecated Not used.
  * @return string Thumbnail path on success, Error string on failure.
  */
 function wp_create_thumbnail( $file, $max_side, $deprecated = '' ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
 	$thumbpath = image_resize( $file, $max_side, $max_side );
 	return apply_filters( 'wp_create_thumbnail', $thumbpath );
 }
diff --git a/wp-admin/includes/meta-boxes.php b/wp-admin/includes/meta-boxes.php
index d5e9cb7e82..14052754b5 100644
--- a/wp-admin/includes/meta-boxes.php
+++ b/wp-admin/includes/meta-boxes.php
@@ -639,6 +639,9 @@ function link_target_meta_box($link) { ?>
 function xfn_check($class, $value = '', $deprecated = '') {
 	global $link;
 
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	$link_rel = isset( $link->link_rel ) ? $link->link_rel : ''; // In PHP 5.3: $link_rel = $link->link_rel ?: '';
 	$rels = preg_split('/\s+/', $link_rel);
 
diff --git a/wp-admin/includes/upgrade.php b/wp-admin/includes/upgrade.php
index 2e77099553..86fb467833 100644
--- a/wp-admin/includes/upgrade.php
+++ b/wp-admin/includes/upgrade.php
@@ -33,9 +33,12 @@ if ( !function_exists('wp_install') ) :
  * @param null $deprecated Optional. Not used.
  * @return array Array keys 'url', 'user_id', 'password', 'password_message'.
  */
-function wp_install($blog_title, $user_name, $user_email, $public, $deprecated='') {
+function wp_install( $blog_title, $user_name, $user_email, $public, $deprecated = '' ) {
 	global $wp_rewrite;
 
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '2.6' );
+
 	wp_check_mysql_version();
 	wp_cache_flush();
 	make_db_current_silent();
diff --git a/wp-app.php b/wp-app.php
index a792144681..d012026834 100644
--- a/wp-app.php
+++ b/wp-app.php
@@ -884,10 +884,12 @@ EOD;
 	 *
 	 * @since 2.2.0
 	 *
-	 * @param mixed $deprecated Optional, not used.
+	 * @param mixed $deprecated Not used.
 	 * @return string
 	 */
 	function get_categories_url($deprecated = '') {
+		if ( !empty( $deprecated ) )
+			_deprecated_argument( __FUNCTION__, '2.5' );
 		return $this->app_base . $this->CATEGORIES_PATH;
 	}
 
diff --git a/wp-includes/author-template.php b/wp-includes/author-template.php
index 89812324fa..056579c219 100644
--- a/wp-includes/author-template.php
+++ b/wp-includes/author-template.php
@@ -22,6 +22,10 @@
  */
 function get_the_author($deprecated = '') {
 	global $authordata;
+
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	return apply_filters('the_author', is_object($authordata) ? $authordata->display_name : null);
 }
 
@@ -44,11 +48,9 @@ function get_the_author($deprecated = '') {
  * @param string $deprecated_echo Deprecated. Use get_the_author(). Echo the string or return it.
  * @return string The author's display name, from get_the_author().
  */
-function the_author($deprecated = '', $deprecated_echo = true) {
-	if ( !empty($deprecated) )
-		_deprecated_argument(__FUNCTION__, 'deprecated', '1.5');
-	if ( $deprecated_echo !== true )
-		_deprecated_argument(__FUNCTION__, 'deprecated_echo', '1.5', __('Use get_the_author() instead if you do not want the value echoed.'));
+function the_author( $deprecated = '', $deprecated_echo = true ) {
+	if ( !empty( $deprecated ) || $deprecated_echo !== true )
+		_deprecated_argument( __FUNCTION__, '1.5', $deprecated_echo !== true ? __('Use get_the_author() instead if you do not want the value echoed.') : null );
 	if ( $deprecated_echo )
 		echo get_the_author();
 	return get_the_author();
@@ -182,7 +184,7 @@ function the_author_posts() {
  */
 function the_author_posts_link($deprecated = '') {
 	if ( !empty( $deprecated ) )
-		_deprecated_argument(__FUNCTION__, 'deprecated', '0.0');
+		_deprecated_argument( __FUNCTION__, '0.0' );
 
 	global $authordata;
 	$link = sprintf(
diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php
index 95c28adc6a..4c3e0e655f 100644
--- a/wp-includes/comment-template.php
+++ b/wp-includes/comment-template.php
@@ -503,15 +503,12 @@ function get_comments_link() {
  *
  * @since 0.71
  *
- * @param string $deprecated_1 Not Used
- * @param bool $deprecated_2 Not Used
+ * @param string $deprecated Not Used
+ * @param bool $deprecated Not Used
  */
-function comments_link( $deprecated_1 = '', $deprecated_2 = '' ) {
-	if ( !empty( $deprecated_1 ) )
-		_deprecated_argument(__FUNCTION__, 'deprecated_1', '0.0');
-	if ( !empty( $deprecated_2 ) )
-		_deprecated_argument(__FUNCTION__, 'deprecated_2', '0.0');
-
+function comments_link( $deprecated = '', $deprecated = '' ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
 	echo get_comments_link();
 }
 
@@ -554,6 +551,10 @@ function get_comments_number( $post_id = 0 ) {
  */
 function comments_number( $zero = false, $one = false, $more = false, $deprecated = '' ) {
 	global $id;
+
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	$number = get_comments_number($id);
 
 	if ( $number > 1 )
@@ -696,12 +697,16 @@ function get_trackback_url() {
  * @since 0.71
  * @uses get_trackback_url() Gets the trackback url for the current post
  *
- * @param bool $deprecated Remove backwards compat in 2.5
+ * @param bool $deprecated_echo Remove backwards compat in 2.5
  * @return void|string Should only be used to echo the trackback URL, use get_trackback_url() for the result instead.
  */
-function trackback_url($deprecated = true) {
-	if ($deprecated) echo get_trackback_url();
-	else return get_trackback_url();
+function trackback_url( $deprecated_echo = true ) {
+	if ( $deprecated_echo !== true )
+		_deprecated_argument( __FUNCTION__, '2.5', __('Use get_trackback_url() instead if you do not want the value echoed.') );
+	if ( $deprecated_echo )
+		echo get_trackback_url();
+	else
+		return get_trackback_url();
 }
 
 /**
@@ -712,6 +717,9 @@ function trackback_url($deprecated = true) {
  * @param int $deprecated Not used (Was $timezone = 0)
  */
 function trackback_rdf($deprecated = '') {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '2.5' );
+
 	if (stripos($_SERVER['HTTP_USER_AGENT'], 'W3C_Validator') === false) {
 		echo '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 				xmlns:dc="http://purl.org/dc/elements/1.1/"
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index 3c35459c14..36b71439e4 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -1511,9 +1511,9 @@ function wp_update_comment_count_now($post_id) {
  * @param int $deprecated Not Used.
  * @return bool|string False on failure, string containing URI on success.
  */
-function discover_pingback_server_uri($url, $deprecated = '') {
-	if ( !empty($deprecated) )
-		_deprecated_argument(__FUNCTION__, 'deprecated', '0.0');
+function discover_pingback_server_uri( $url, $deprecated = '' ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
 
 	$pingback_str_dquote = 'rel="pingback"';
 	$pingback_str_squote = 'rel=\'pingback\'';
diff --git a/wp-includes/cron.php b/wp-includes/cron.php
index 3c7c086fe8..d0f62d0e9e 100644
--- a/wp-includes/cron.php
+++ b/wp-includes/cron.php
@@ -136,7 +136,7 @@ function wp_clear_scheduled_hook( $hook, $args = array() ) {
 	// Backward compatibility
 	// Previously this function took the arguments as discrete vars rather than an array like the rest of the API
 	if ( !is_array($args) ) {
-		_deprecated_argument(__FUNCTION__, 'args', '3.0.0', __('This argument has changed to an array so as to match with the behaviour of all the other cron functions.') );
+		_deprecated_argument( __FUNCTION__, '3.0.0', __('This argument has changed to an array to match the behavior of the other cron functions.') );
 		$args = array_slice( func_get_args(), 1 );
 	}
 
diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php
index 246a5a3937..15ab20de05 100644
--- a/wp-includes/formatting.php
+++ b/wp-includes/formatting.php
@@ -866,6 +866,9 @@ function sanitize_html_class($class, $fallback){
  * @return string Converted string.
  */
 function convert_chars($content, $deprecated = '') {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	// Translation of invalid Unicode references range to valid range
 	$wp_htmltranswinuni = array(
 	'&#128;' => '&#8364;', // the Euro sign
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index 803daa93f5..1ddb17a856 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -570,6 +570,9 @@ function update_option( $option_name, $newvalue ) {
  * @return null returns when finished.
  */
 function add_option( $name, $value = '', $deprecated = '', $autoload = 'yes' ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '2.3' );
+
 	global $wpdb;
 
 	wp_protect_special_option( $name );
@@ -1203,6 +1206,9 @@ function do_enclose( $content, $post_ID ) {
  * @return bool|string False on failure and string of headers if HEAD request.
  */
 function wp_get_http( $url, $file_path = false, $deprecated = false ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	@set_time_limit( 60 );
 
 	$options = array();
@@ -1245,6 +1251,9 @@ function wp_get_http( $url, $file_path = false, $deprecated = false ) {
  * @return bool|string False on failure, headers on success.
  */
 function wp_get_http_headers( $url, $deprecated = false ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	$response = wp_remote_head( $url );
 
 	if ( is_wp_error( $response ) )
@@ -2187,6 +2196,9 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null )
  * @return array
  */
 function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	if ( empty( $name ) )
 		return array( 'error' => __( 'Empty filename' ) );
 
@@ -3039,7 +3051,7 @@ function _deprecated_file($file, $version, $replacement=null) {
  * For example:
  * <code>
  * if ( !empty($deprecated) )
- * 	_deprecated_argument( __FUNCTION__, 'deprecated', '0.0' );
+ * 	_deprecated_argument( __FUNCTION__, '0.0' );
  * </code>
  *
  * There is a hook deprecated_argument_run that will be called that can be used
@@ -3053,24 +3065,23 @@ function _deprecated_file($file, $version, $replacement=null) {
  * @since 3.0.0
  * @access private
  *
- * @uses do_action() Calls 'deprecated_argument_run' and passes the function and argument names and what to use instead.
+ * @uses do_action() Calls 'deprecated_argument_run' and passes the function name and what to use instead.
  * @uses apply_filters() Calls 'deprecated_argument_trigger_error' and expects boolean value of true to do trigger or false to not trigger error.
  *
  * @param string $function The function that was called
- * @param string $argument The name of the deprecated argument that was used
- * @param string $version The version of WordPress that deprecated the function
+ * @param string $version The version of WordPress that deprecated the argument used
  * @param string $message Optional. A message regarding the change.
  */
-function _deprecated_argument($function, $argument, $version, $message = null) {
+function _deprecated_argument($function, $version, $message = null) {
 
-	do_action('deprecated_argument_run', $function, $argument, $message);
+	do_action('deprecated_argument_run', $function, $message);
 
 	// Allow plugin to filter the output error trigger
 	if( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) {
 		if( !is_null($message) )
-			trigger_error( sprintf( __('The %1$s argument of %2$s is <strong>deprecated</strong> since version %3$s! %4$s'), $function, $argument, $version, $message ) );
+			trigger_error( sprintf( __('%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s'), $function, $version, $message ) );
 		else
-			trigger_error( sprintf( __('The %1$s argument of %2$s is <strong>deprecated</strong> since version %3$s with no alternative available.'), $function, $argument, $version ) );
+			trigger_error( sprintf( __('%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.'), $function, $version ) );
 	}
 }
 
diff --git a/wp-includes/kses.php b/wp-includes/kses.php
index 56176b4684..b0aa916916 100644
--- a/wp-includes/kses.php
+++ b/wp-includes/kses.php
@@ -1197,6 +1197,9 @@ add_action('init', 'kses_init');
 add_action('set_current_user', 'kses_init');
 
 function safecss_filter_attr( $css, $deprecated = '' ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	$css = wp_kses_no_null($css);
 	$css = str_replace(array("\n","\r","\t"), '', $css);
 
diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php
index 4d14c26bf2..5e0c14bcf4 100644
--- a/wp-includes/link-template.php
+++ b/wp-includes/link-template.php
@@ -168,7 +168,10 @@ function get_permalink($id = 0, $leavename = false) {
  * @param mixed $deprecated Not used.
  * @return string
  */
-function post_permalink($post_id = 0, $deprecated = '') {
+function post_permalink( $post_id = 0, $deprecated = '' ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	return get_permalink($post_id);
 }
 
diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php
index 62419bdce3..85258018b8 100644
--- a/wp-includes/post-template.php
+++ b/wp-includes/post-template.php
@@ -246,9 +246,9 @@ function the_excerpt() {
  * @param mixed $deprecated Not used.
  * @return string
  */
-function get_the_excerpt($deprecated = '') {
+function get_the_excerpt( $deprecated = '' ) {
 	if ( !empty( $deprecated ) )
-		_deprecated_argument(__FUNCTION__, 'deprecated', '2.3');
+		_deprecated_argument( __FUNCTION__, '2.3' );
 
 	global $post;
 	$output = $post->post_excerpt;
@@ -901,7 +901,10 @@ function walk_page_dropdown_tree() {
  * @param bool $deprecated Deprecated. Not used.
  * @param bool $permalink Optional, default is false. Whether to include permalink.
  */
-function the_attachment_link($id = 0, $fullsize = false, $deprecated = false, $permalink = false) {
+function the_attachment_link( $id = 0, $fullsize = false, $deprecated = false, $permalink = false ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
+
 	if ( $fullsize )
 		echo wp_get_attachment_link($id, 'full', $permalink);
 	else
diff --git a/wp-includes/post.php b/wp-includes/post.php
index a76ec59baa..4e8bc7e9af 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -3538,9 +3538,11 @@ function _transition_post_status($new_status, $old_status, $post) {
  * @param int $deprecated Not Used. Can be set to null.
  * @param object $post Object type containing the post information
  */
-function _future_post_hook($deprecated = '', $post) {
+function _future_post_hook( $deprecated = '', $post ) {
+	if ( !empty( $deprecated ) )
+		_deprecated_argument( __FUNCTION__, '0.0' );
 	wp_clear_scheduled_hook( 'publish_future_post', array( $post->ID ) );
-	wp_schedule_single_event(strtotime($post->post_date_gmt. ' GMT'), 'publish_future_post', array($post->ID));
+	wp_schedule_single_event( strtotime( $post->post_date_gmt. ' GMT' ), 'publish_future_post', array( $post->ID ) );
 }
 
 /**
diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php
index 9a29215c96..b6a71973c7 100644
--- a/wp-includes/widgets.php
+++ b/wp-includes/widgets.php
@@ -985,7 +985,7 @@ function is_active_sidebar( $index ) {
  */
 function wp_get_sidebars_widgets($deprecated = true) {
 	if ( $deprecated !== true )
-		_deprecated_argument(__FUNCTION__, 'deprecated', '0.0');
+		_deprecated_argument( __FUNCTION__, '0.0' );
 
 	global $wp_registered_widgets, $wp_registered_sidebars, $_wp_sidebars_widgets;