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 );