Changeset 2816

Timestamp:

03/25/2016 06:28:58 PM (9 years ago)

Author:

coffee2code

Message:

developer.wordpress.org: Improve deprecation notice banner text generation.

• Add '()' to functions and methods on display, if dropped by parser.
• Fall back to @deprecated message if no @see is present.
• Append 'instead.' to string taken from @deprecated if not already present.

Fixes #1647.

File:

• sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php (modified) (3 diffs)

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php

@@ -742 +742 @@
 
     /**
-     * Retrieve deprecated flag
+     * Retrieve deprecated notice.
      *
      * @param int $post_id
@@ -749 +749 @@
      */
     function get_deprecated( $post_id = null ) {
-        if ( empty( $post_id ) ) {
+        if ( ! $post_id ) {
             $post_id = get_the_ID();
         }
@@ -757 +757 @@
         $tags           = get_post_meta( $post_id, '_wp-parser_tags', true );
         $deprecated = wp_filter_object_list( $tags, array( 'name' => 'deprecated' ) );
-
-        if ( empty( $deprecated ) ) {
+        $deprecated = array_shift( $deprecated );
+
+        if ( ! $deprecated ) {
             return '';
         }
+
+        $deprecation_info = '';
 
         $referral = wp_filter_object_list( $tags, array( 'name' => 'see' ) );
         $referral = array_shift( $referral );
 
+        // Construct message pointing visitor to preferred alternative, as provided
+        // via @see, if present.
         if ( ! empty( $referral['refers'] ) ) {
             $refers = sanitize_text_field( $referral['refers'] );
 
-            if ( ! empty( $refers ) ) {
-                /* translators: 1: Linked internal element name */
-                $alternative_string = sprintf( __( ' Use %s instead.', 'wporg' ), \DevHub_Formatting::link_internal_element( $refers ) );
-            }
-        } else {
-            $alternative_string = '';
-        }
-
-        /* translators: 1: String for alternative function (if one exists) */
+            if ( $refers ) {
+                // For some reason, the parser may have dropped the parentheses, so add them.
+                if ( in_array( $type, array( 'function', 'method' ) ) && false === strpos( $refers, '()' ) ) {
+                    $refers .= '()';
+                }
+                /* translators: %s: Linked internal element name */
+                $deprecation_info = ' ' . sprintf( __( 'Use %s instead.', 'wporg' ), \DevHub_Formatting::link_internal_element( $refers ) );
+            }
+        }
+
+        // If no alternative resource was referenced, use the deprecation string, if
+        // present.
+        if ( ! $deprecation_info && ! empty( $deprecated['content'] ) ) {
+            $deprecation_info = ' ' . sanitize_text_field ( $deprecated['content'] );
+            // Many deprecation strings use the syntax "Use function()" instead of the
+            // preferred "Use function() instead." Add it in if missing.
+            if ( false === strpos( $deprecation_info, 'instead' ) ) {
+                $deprecation_info .= ' instead.'; // Not making translatable since rest of string is not translatable.
+            }
+        }
+
+        /* translators: 1: parsed post post, 2: String for alternative function (if one exists) */
         $contents = sprintf( __( 'This %1$s has been deprecated.%2$s', 'wporg' ),
             $type,
-            $alternative_string
+            $deprecation_info
         );