Changeset 47122 for trunk/src/wp-admin/includes/template.php

Timestamp:

01/29/2020 12:43:23 AM (6 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-admin/includes/template.php (modified) (17 diffs)

trunk/src/wp-admin/includes/template.php

@@ -16 +16 @@
 
 //
-// Category Checklists
+// Category Checklists.
 //
 
@@ -166 +166 @@
 
     if ( $parsed_args['checked_ontop'] ) {
-        // Post process $categories rather than adding an exclude to the get_terms() query to keep the query the same across all posts (for any query cache)
+        // Post-process $categories rather than adding an exclude to the get_terms() query
+        // to keep the query the same across all posts (for any query cache).
         $checked_categories = array();
         $keys               = array_keys( $categories );
@@ -177 +178 @@
         }
 
-        // Put checked cats on top
+        // Put checked categories on top.
         $output .= $walker->walk( $checked_categories, 0, $args );
     }
-    // Then the rest of them
+    // Then the rest of them.
     $output .= $walker->walk( $categories, 0, $args );
 
@@ -266 +267 @@
     if ( $link_id ) {
         $checked_categories = wp_get_link_cats( $link_id );
-        // No selected categories, strange
+        // No selected categories, strange.
         if ( ! count( $checked_categories ) ) {
             $checked_categories[] = $default;
@@ -560 +561 @@
  */
 function list_meta( $meta ) {
-    // Exit if no meta
+    // Exit if no meta.
     if ( ! $meta ) {
         echo '
@@ -573 +574 @@
     <tr><td></td></tr>
     </tbody>
-</table>'; //TBODY needed for list-manipulation JS
+</table>'; // TBODY needed for list-manipulation JS.
         return;
     }
@@ -633 +634 @@
 
     $entry['meta_key']   = esc_attr( $entry['meta_key'] );
-    $entry['meta_value'] = esc_textarea( $entry['meta_value'] ); // using a <textarea />
+    $entry['meta_value'] = esc_textarea( $entry['meta_value'] ); // Using a <textarea />.
     $entry['meta_id']    = (int) $entry['meta_id'];
 
@@ -791 +792 @@
     }
 
-    // todo: Remove this?
+    // @todo Remove this?
     // echo '<label for="timestamp" style="display: block;"><input type="checkbox" class="checkbox" name="edit_date" value="1" id="timestamp"'.$tab_index_attribute.' /> '.__( 'Edit timestamp' ).'</label><br />';
 
@@ -926 +927 @@
     foreach ( $editable_roles as $role => $details ) {
         $name = translate_user_role( $details['name'] );
-        // preselect specified role
+        // Preselect specified role.
         if ( $selected == $role ) {
             $r .= "\n\t<option selected='selected' value='" . esc_attr( $role ) . "'>$name</option>";
@@ -1053 +1054 @@
             // If a core box was previously added or removed by a plugin, don't add.
             if ( 'core' == $priority ) {
-                // If core box previously deleted, don't add
+                // If core box previously deleted, don't add.
                 if ( false === $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] ) {
                     return;
@@ -1068 +1069 @@
                 return;
             }
-            // If no priority given and id already present, use existing priority.
+            // If no priority given and ID already present, use existing priority.
             if ( empty( $priority ) ) {
                 $priority = $a_priority;
@@ -1080 +1081 @@
                 $callback_args = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['args'];
             }
-            // An id can be in only one priority and one context.
+            // An ID can be in only one priority and one context.
             if ( $priority != $a_priority || $context != $a_context ) {
                 unset( $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] );
@@ -1246 +1247 @@
     printf( '<div id="%s-sortables" class="meta-box-sortables">', esc_attr( $context ) );
 
-    // Grab the ones the user has manually sorted. Pull them out of their previous context/priority and into the one the user chose
+    // Grab the ones the user has manually sorted.
+    // Pull them out of their previous context/priority and into the one the user chose.
     $sorted = get_user_option( "meta-box-order_$page" );
     if ( ! $already_sorted && $sorted ) {
@@ -2193 +2195 @@
             $header_image = get_header_image();
 
-            // Display "Header Image" if the image was ever used as a header image
+            // Display "Header Image" if the image was ever used as a header image.
             if ( ! empty( $meta_header ) && $meta_header == $stylesheet && $header_image !== wp_get_attachment_url( $post->ID ) ) {
                 $media_states[] = __( 'Header Image' );
             }
 
-            // Display "Current Header Image" if the image is currently the header image
+            // Display "Current Header Image" if the image is currently the header image.
             if ( $header_image && $header_image == wp_get_attachment_url( $post->ID ) ) {
                 $media_states[] = __( 'Current Header Image' );
@@ -2379 +2381 @@
     $text = $text ? $text : __( 'Save Changes' );
 
-    // Default the id attribute to $name unless an id was specifically provided in $other_attributes
+    // Default the id attribute to $name unless an id was specifically provided in $other_attributes.
     $id = $name;
     if ( is_array( $other_attributes ) && isset( $other_attributes['id'] ) ) {
@@ -2389 +2391 @@
     if ( is_array( $other_attributes ) ) {
         foreach ( $other_attributes as $attribute => $value ) {
-            $attributes .= $attribute . '="' . esc_attr( $value ) . '" '; // Trailing space is important
-        }
-    } elseif ( ! empty( $other_attributes ) ) { // Attributes provided as a string
+            $attributes .= $attribute . '="' . esc_attr( $value ) . '" '; // Trailing space is important.
+        }
+    } elseif ( ! empty( $other_attributes ) ) { // Attributes provided as a string.
         $attributes = $other_attributes;
     }
@@ -2534 +2536 @@
     $parsed_args = wp_parse_args( $args, $defaults );
 
-    // Non-English decimal places when the $rating is coming from a string
+    // Non-English decimal places when the $rating is coming from a string.
     $rating = (float) str_replace( ',', '.', $parsed_args['rating'] );
 
-    // Convert Percentage to star rating, 0..5 in .5 increments
+    // Convert percentage to star rating, 0..5 in .5 increments.
     if ( 'percent' === $parsed_args['type'] ) {
         $rating = round( $rating / 10, 0 ) / 2;
     }
 
-    // Calculate the number of each type of star needed
+    // Calculate the number of each type of star needed.
     $full_stars  = floor( $rating );
     $half_stars  = ceil( $rating - $full_stars );