Changeset 47084

Timestamp:

01/18/2020 12:52:28 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve comments in some wp-admin files per the documentation standards.

Props passoniate.
Fixes #49215, #49216.

Location:

trunk/src/wp-admin/includes

Files:

• comment.php (modified) (1 diff)
• dashboard.php (modified) (12 diffs)
• deprecated.php (modified) (9 diffs)
• file.php (modified) (39 diffs)
• image-edit.php (modified) (3 diffs)
• image.php (modified) (9 diffs)
• import.php (modified) (4 diffs)
• list-table.php (modified) (2 diffs)
• media.php (modified) (13 diffs)
• menu.php (modified) (5 diffs)

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

@@ -166 +166 @@
     $pending_keyed = array();
 
-    // Default to zero pending for all posts in request
+    // Default to zero pending for all posts in request.
     foreach ( $post_id_array as $id ) {
         $pending_keyed[ $id ] = 0;

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

@@ -57 +57 @@
     }
 
-    // Right Now
+    // Right Now.
     if ( is_blog_admin() && current_user_can( 'edit_posts' ) ) {
         wp_add_dashboard_widget( 'dashboard_right_now', __( 'At a Glance' ), 'wp_dashboard_right_now' );
@@ -66 +66 @@
     }
 
-    // Activity Widget
+    // Activity Widget.
     if ( is_blog_admin() ) {
         wp_add_dashboard_widget( 'dashboard_activity', __( 'Activity' ), 'wp_dashboard_site_activity' );
     }
 
-    // QuickPress Widget
+    // QuickPress Widget.
     if ( is_blog_admin() && current_user_can( get_post_type_object( 'post' )->cap->create_posts ) ) {
         $quick_draft_title = sprintf( '<span class="hide-if-no-js">%1$s</span> <span class="hide-if-js">%2$s</span>', __( 'Quick Draft' ), __( 'Your Recent Drafts' ) );
@@ -77 +77 @@
     }
 
-    // WordPress Events and News
+    // WordPress Events and News.
     wp_add_dashboard_widget( 'dashboard_primary', __( 'WordPress Events and News' ), 'wp_dashboard_events_news' );
 
@@ -140 +140 @@
     if ( 'POST' == $_SERVER['REQUEST_METHOD'] && isset( $_POST['widget_id'] ) ) {
         check_admin_referer( 'edit-dashboard-widget_' . $_POST['widget_id'], 'dashboard-widget-nonce' );
-        ob_start(); // hack - but the same hack wp-admin/widgets.php uses
+        ob_start(); // Hack - but the same hack wp-admin/widgets.php uses.
         wp_dashboard_trigger_widget_control( $_POST['widget_id'] );
         ob_end_clean();
@@ -279 +279 @@
     <ul>
     <?php
-    // Posts and Pages
+    // Posts and Pages.
     foreach ( array( 'post', 'page' ) as $post_type ) {
         $num_posts = wp_count_posts( $post_type );
@@ -299 +299 @@
         }
     }
-    // Comments
+    // Comments.
     $num_comm = wp_count_comments();
     if ( $num_comm && ( $num_comm->approved || $num_comm->moderated ) ) {
@@ -507 +507 @@
 
     /* Check if a new auto-draft (= no new post_ID) is needed or if the old can be used */
-    $last_post_id = (int) get_user_option( 'dashboard_quick_press_last_post_id' ); // Get the last post_ID
+    $last_post_id = (int) get_user_option( 'dashboard_quick_press_last_post_id' ); // Get the last post_ID.
     if ( $last_post_id ) {
         $post = get_post( $last_post_id );
-        if ( empty( $post ) || $post->post_status != 'auto-draft' ) { // auto-draft doesn't exists anymore
+        if ( empty( $post ) || $post->post_status != 'auto-draft' ) { // auto-draft doesn't exists anymore.
             $post = get_default_post_to_edit( 'post', true );
-            update_user_option( get_current_user_id(), 'dashboard_quick_press_last_post_id', (int) $post->ID ); // Save post_ID
+            update_user_option( get_current_user_id(), 'dashboard_quick_press_last_post_id', (int) $post->ID ); // Save post_ID.
         } else {
-            $post->post_title = ''; // Remove the auto draft title
+            $post->post_title = ''; // Remove the auto draft title.
         }
     } else {
@@ -521 +521 @@
         // Don't create an option if this is a super admin who does not belong to this site.
         if ( in_array( get_current_blog_id(), array_keys( get_blogs_of_user( $user_id ) ) ) ) {
-            update_user_option( $user_id, 'dashboard_quick_press_last_post_id', (int) $post->ID ); // Save post_ID
+            update_user_option( $user_id, 'dashboard_quick_press_last_post_id', (int) $post->ID ); // Save post_ID.
         }
     }
@@ -761 +761 @@
             ( ( ( 'approve' == $action || 'unapprove' == $action ) && 2 === $i ) || 1 === $i ) ? $sep = '' : $sep = ' | ';
 
-            // Reply and quickedit need a hide-if-no-js span
+            // Reply and quickedit need a hide-if-no-js span.
             if ( 'reply' == $action || 'quickedit' == $action ) {
                 $action .= ' hide-if-no-js';
@@ -1109 +1109 @@
         ob_start();
         call_user_func_array( $callback, $args );
-        set_transient( $cache_key, ob_get_flush(), 12 * HOUR_IN_SECONDS ); // Default lifetime in cache of 12 hours (same as the feeds)
+        // Default lifetime in cache of 12 hours (same as the feeds).
+        set_transient( $cache_key, ob_get_flush(), 12 * HOUR_IN_SECONDS );
     }
 
@@ -1164 +1165 @@
     }
 
-    $number                                 = 1; // Hack to use wp_widget_rss_form()
+    $number = 1; // Hack to use wp_widget_rss_form().
+
     $widget_options[ $widget_id ]['number'] = $number;
 
@@ -1663 +1665 @@
     $response = get_site_transient( 'browser_' . $key );
     if ( false === $response ) {
-        // include an unmodified $wp_version
+        // Include an unmodified $wp_version.
         include( ABSPATH . WPINC . '/version.php' );
 

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

@@ -234 +234 @@
         $level_key = $wpdb->get_blog_prefix() . 'user_level';
     else
-        $level_key = $wpdb->get_blog_prefix() . 'capabilities'; // wpmu site admins don't have user_levels
+        $level_key = $wpdb->get_blog_prefix() . 'capabilities'; // WPMU site admins don't have user_levels.
 
     return $wpdb->get_col( $wpdb->prepare("SELECT user_id FROM $wpdb->usermeta WHERE meta_key = %s AND meta_value != '0'", $level_key) );
@@ -296 +296 @@
         $level_key = $wpdb->get_blog_prefix() . 'user_level';
     else
-        $level_key = $wpdb->get_blog_prefix() . 'capabilities'; // wpmu site admins don't have user_levels
+        $level_key = $wpdb->get_blog_prefix() . 'capabilities'; // WPMU site admins don't have user_levels.
 
     $query = $wpdb->prepare("SELECT user_id FROM $wpdb->usermeta WHERE meta_key = %s", $level_key);
@@ -320 +320 @@
         $level_key = $wpdb->get_blog_prefix() . 'user_level';
     else
-        $level_key = $wpdb->get_blog_prefix() . 'capabilities'; // wpmu site admins don't have user_levels
+        $level_key = $wpdb->get_blog_prefix() . 'capabilities'; // WPMU site admins don't have user_levels.
 
     return $wpdb->get_col( $wpdb->prepare("SELECT user_id FROM $wpdb->usermeta WHERE meta_key = %s AND meta_value = '0'", $level_key) );
@@ -545 +545 @@
             $this->query_where .= $wpdb->prepare(" AND $wpdb->usermeta.meta_key = '{$wpdb->prefix}capabilities' AND $wpdb->usermeta.meta_value LIKE %s", '%' . $this->role . '%');
         } elseif ( is_multisite() ) {
-            $level_key = $wpdb->prefix . 'capabilities'; // wpmu site admins don't have user_levels
+            $level_key = $wpdb->prefix . 'capabilities'; // WPMU site admins don't have user_levels.
             $this->query_from .= ", $wpdb->usermeta";
             $this->query_where .= " AND $wpdb->users.ID = $wpdb->usermeta.user_id AND meta_key = '{$level_key}'";
@@ -565 +565 @@
 
         if ( $this->results )
-            $this->total_users_for_query = $wpdb->get_var("SELECT COUNT(DISTINCT($wpdb->users.ID))" . $this->query_from . $this->query_where); // no limit
+            $this->total_users_for_query = $wpdb->get_var("SELECT COUNT(DISTINCT($wpdb->users.ID))" . $this->query_from . $this->query_where); // No limit.
         else
             $this->search_errors = new WP_Error('no_matching_users_found', __('No users found.'));
@@ -585 +585 @@
      */
     public function do_paging() {
-        if ( $this->total_users_for_query > $this->users_per_page ) { // have to page the results
+        if ( $this->total_users_for_query > $this->users_per_page ) { // Have to page the results.
             $args = array();
             if ( ! empty($this->search_term) )
@@ -1320 +1320 @@
     _deprecated_function( __FUNCTION__, '4.8.0' );
 
-    // Plugin feeds plus link to install them
+    // Plugin feeds plus link to install them.
     $popular = fetch_feed( $args['url']['popular'] );
 
@@ -1336 +1336 @@
         $items = $feed->get_items(0, 5);
 
-        // Pick a random, non-installed plugin
+        // Pick a random, non-installed plugin.
         while ( true ) {
-            // Abort this foreach loop iteration if there's no plugins left of this type
+            // Abort this foreach loop iteration if there's no plugins left of this type.
             if ( 0 == count($items) )
                 continue 2;
@@ -1368 +1368 @@
         }
 
-        // Eliminate some common badly formed plugin descriptions
+        // Eliminate some common badly formed plugin descriptions.
         while ( ( null !== $item_key = array_rand($items) ) && false !== strpos( $items[$item_key]->get_description(), 'Plugin Name:' ) )
             unset($items[$item_key]);

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

@@ -22 +22 @@
     '404.php'               => __( '404 Template' ),
     'link.php'              => __( 'Links Template' ),
-    // Archives
+    // Archives.
     'index.php'             => __( 'Main Index Template' ),
     'archive.php'           => __( 'Archives' ),
@@ -32 +32 @@
     'search.php'            => __( 'Search Results' ),
     'date.php'              => __( 'Date Template' ),
-    // Content
+    // Content.
     'singular.php'          => __( 'Singular Template' ),
     'single.php'            => __( 'Single Post' ),
@@ -38 +38 @@
     'front-page.php'        => __( 'Homepage' ),
     'privacy-policy.php'    => __( 'Privacy Policy Page' ),
-    // Attachments
+    // Attachments.
     'attachment.php'        => __( 'Attachment Template' ),
     'image.php'             => __( 'Image Attachment Template' ),
@@ -44 +44 @@
     'audio.php'             => __( 'Audio Attachment Template' ),
     'application.php'       => __( 'Application Attachment Template' ),
-    // Embeds
+    // Embeds.
     'embed.php'             => __( 'Embed Template' ),
     'embed-404.php'         => __( 'Embed 404 Template' ),
@@ -50 +50 @@
     'header-embed.php'      => __( 'Embed Header Template' ),
     'footer-embed.php'      => __( 'Embed Footer Template' ),
-    // Stylesheets
+    // Stylesheets.
     'style.css'             => __( 'Stylesheet' ),
     'editor-style.css'      => __( 'Visual Editor Stylesheet' ),
     'editor-style-rtl.css'  => __( 'Visual Editor RTL Stylesheet' ),
     'rtl.css'               => __( 'RTL Stylesheet' ),
-    // Other
+    // Other.
     'my-hacks.php'          => __( 'my-hacks.php (legacy hacks support)' ),
     '.htaccess'             => __( '.htaccess (for rewrite rules )' ),
-    // Deprecated files
+    // Deprecated files.
     'wp-layout.css'         => __( 'Stylesheet' ),
     'wp-comments.php'       => __( 'Comments Template' ),
@@ -456 +456 @@
         }
 
-        // Compare based on relative paths
+        // Compare based on relative paths.
         if ( 0 !== validate_file( $file, array_keys( $allowed_files ) ) ) {
             return new WP_Error( 'disallowed_theme_file', __( 'Sorry, that file cannot be edited.' ) );
@@ -508 +508 @@
         $transient    = 'scrape_key_' . $scrape_key;
         $scrape_nonce = strval( rand() );
-        set_transient( $transient, $scrape_nonce, 60 ); // It shouldn't take more than 60 seconds to make the two loopback requests.
+        // It shouldn't take more than 60 seconds to make the two loopback requests.
+        set_transient( $transient, $scrape_nonce, 60 );
 
         $cookies       = wp_unslash( $_COOKIE );
@@ -645 +646 @@
     }
 
-    // Use the basename of the given file without the extension as the name for the temporary directory
+    // Use the basename of the given file without the extension as the name for the temporary directory.
     $temp_filename = basename( $filename );
     $temp_filename = preg_replace( '|\.[^.]*$|', '', $temp_filename );
@@ -654 +655 @@
     }
 
-    // Suffix some random data to avoid filename conflicts
+    // Suffix some random data to avoid filename conflicts.
     $temp_filename .= '-' . wp_generate_password( 6, false );
     $temp_filename .= '.tmp';
@@ -736 +737 @@
     $file = apply_filters( "{$action}_prefilter", $file );
 
-    // You may define your own function and pass the name in $overrides['upload_error_handler']
+    // You may define your own function and pass the name in $overrides['upload_error_handler'].
     $upload_error_handler = 'wp_handle_upload_error';
     if ( isset( $overrides['upload_error_handler'] ) ) {
@@ -749 +750 @@
     // Install user overrides. Did we mention that this voids your warranty?
 
-    // You may define your own function and pass the name in $overrides['unique_filename_callback']
+    // You may define your own function and pass the name in $overrides['unique_filename_callback'].
     $unique_filename_callback = null;
     if ( isset( $overrides['unique_filename_callback'] ) ) {
@@ -823 +824 @@
         $proper_filename = empty( $wp_filetype['proper_filename'] ) ? '' : $wp_filetype['proper_filename'];
 
-        // Check to see if wp_check_filetype_and_ext() determined the filename was incorrect
+        // Check to see if wp_check_filetype_and_ext() determined the filename was incorrect.
         if ( $proper_filename ) {
             $file['name'] = $proper_filename;
@@ -870 +871 @@
             $move_new_file = @move_uploaded_file( $file['tmp_name'], $new_file );
         } else {
-            // use copy and unlink because rename breaks streams.
+            // Use copy and unlink because rename breaks streams.
             // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
             $move_new_file = @copy( $file['tmp_name'], $new_file );
@@ -1002 +1003 @@
  */
 function download_url( $url, $timeout = 300, $signature_verification = false ) {
-    //WARNING: The file is not automatically deleted, The script must unlink() the file.
+    // WARNING: The file is not automatically deleted, the script must unlink() the file.
     if ( ! $url ) {
         return new WP_Error( 'http_no_url', __( 'Invalid URL Provided.' ) );
@@ -1083 +1084 @@
         if ( ! $signature ) {
             // Retrieve signatures from a file if the header wasn't included.
-            // WordPress.org stores signatures at $package_url.sig
+            // WordPress.org stores signatures at $package_url.sig.
 
             $signature_url = false;
@@ -1105 +1106 @@
                     $signature_url,
                     array(
-                        'limit_response_size' => 10 * 1024, // 10KB should be large enough for quite a few signatures.
+                        'limit_response_size' => 10 * KB_IN_BYTES, // 10KB should be large enough for quite a few signatures.
                     )
                 );
@@ -1162 +1163 @@
         $expected_raw_md5 = base64_decode( $expected_md5 );
     } else {
-        return false; // unknown format
+        return false; // Unknown format.
     }
 
@@ -1211 +1212 @@
     }
 
-    // Check for a edge-case affecting PHP Maths abilities
+    // Check for a edge-case affecting PHP Maths abilities.
     if (
         ! extension_loaded( 'sodium' ) &&
@@ -1251 +1252 @@
         }
 
-        // This cannot be performed in a reasonable amount of time
+        // This cannot be performed in a reasonable amount of time.
         // https://github.com/paragonie/sodium_compat#help-sodium_compat-is-slow-how-can-i-make-it-fast
         if ( ! $sodium_compat_is_fast ) {
@@ -1479 +1480 @@
         }
 
-        if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory
+        if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory.
             continue;
         }
@@ -1516 +1517 @@
     foreach ( $needed_dirs as $dir ) {
         // Check the parent folders of the folders all exist within the creation array.
-        if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, We know this exists (or will exist)
+        if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, we know this exists (or will exist).
             continue;
         }
-        if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, Skip it
+        if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, skip it.
             continue;
         }
@@ -1550 +1551 @@
         }
 
-        if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files
+        if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files.
             continue;
         }
@@ -1616 +1617 @@
     $uncompressed_size = 0;
 
-    // Determine any children directories needed (From within the archive)
+    // Determine any children directories needed (From within the archive).
     foreach ( $archive_files as $file ) {
-        if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory
+        if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory.
             continue;
         }
@@ -1642 +1643 @@
     foreach ( $needed_dirs as $dir ) {
         // Check the parent folders of the folders all exist within the creation array.
-        if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, We know this exists (or will exist)
+        if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, we know this exists (or will exist).
             continue;
         }
-        if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, Skip it
+        if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, skip it.
             continue;
         }
@@ -1666 +1667 @@
     unset( $needed_dirs );
 
-    // Extract the files from the zip
+    // Extract the files from the zip.
     foreach ( $archive_files as $file ) {
         if ( $file['folder'] ) {
@@ -1672 +1673 @@
         }
 
-        if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files
+        if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files.
             continue;
         }
@@ -1731 +1732 @@
             }
 
-            // generate the $sub_skip_list for the subdirectory as a sub-set of the existing $skip_list
+            // Generate the $sub_skip_list for the subdirectory as a sub-set of the existing $skip_list.
             $sub_skip_list = array();
             foreach ( $skip_list as $skip_item ) {
@@ -1749 +1750 @@
 
 /**
- * Initialises and connects the WordPress Filesystem Abstraction classes.
+ * Initializes and connects the WordPress Filesystem Abstraction classes.
  *
  * This function will include the chosen transport and attempt connecting.
@@ -1801 +1802 @@
     $wp_filesystem = new $method( $args );
 
-    //Define the timeouts for the connections. Only available after the construct is called to allow for per-transport overriding of the default.
+    /*
+     * Define the timeouts for the connections. Only available after the constructor is called
+     * to allow for per-transport overriding of the default.
+     */
     if ( ! defined( 'FS_CONNECT_TIMEOUT' ) ) {
         define( 'FS_CONNECT_TIMEOUT', 30 );
@@ -1814 +1818 @@
 
     if ( ! $wp_filesystem->connect() ) {
-        return false; //There was an error connecting to the server.
+        return false; // There was an error connecting to the server.
     }
 
@@ -1855 +1859 @@
  */
 function get_filesystem_method( $args = array(), $context = '', $allow_relaxed_file_ownership = false ) {
-    $method = defined( 'FS_METHOD' ) ? FS_METHOD : false; // Please ensure that this is either 'direct', 'ssh2', 'ftpext' or 'ftpsockets'
+    // Please ensure that this is either 'direct', 'ssh2', 'ftpext', or 'ftpsockets'.
+    $method = defined( 'FS_METHOD' ) ? FS_METHOD : false;
 
     if ( ! $context ) {
@@ -1874 +1879 @@
         if ( $temp_handle ) {
 
-            // Attempt to determine the file owner of the WordPress files, and that of newly created files
+            // Attempt to determine the file owner of the WordPress files, and that of newly created files.
             $wp_file_owner   = false;
             $temp_file_owner = false;
@@ -1883 +1888 @@
 
             if ( $wp_file_owner !== false && $wp_file_owner === $temp_file_owner ) {
-                // WordPress is creating files as the same owner as the WordPress files,
-                // this means it's safe to modify & create new files via PHP.
+                /*
+                 * WordPress is creating files as the same owner as the WordPress files,
+                 * this means it's safe to modify & create new files via PHP.
+                 */
                 $method                                  = 'direct';
                 $GLOBALS['_wp_filesystem_direct_method'] = 'file_owner';
             } elseif ( $allow_relaxed_file_ownership ) {
-                // The $context directory is writable, and $allow_relaxed_file_ownership is set, this means we can modify files
-                // safely in this directory. This mode doesn't create new files, only alter existing ones.
+                /*
+                 * The $context directory is writable, and $allow_relaxed_file_ownership is set,
+                 * this means we can modify files safely in this directory.
+                 * This mode doesn't create new files, only alter existing ones.
+                 */
                 $method                                  = 'direct';
                 $GLOBALS['_wp_filesystem_direct_method'] = 'relaxed_ownership';
@@ -1906 +1916 @@
     }
     if ( ! $method && ( extension_loaded( 'sockets' ) || function_exists( 'fsockopen' ) ) ) {
-        $method = 'ftpsockets'; //Sockets: Socket extension; PHP Mode: FSockopen / fwrite / fread
+        $method = 'ftpsockets'; // Sockets: Socket extension; PHP Mode: FSockopen / fwrite / fread.
     }
 
@@ -1999 +2009 @@
     $submitted_form = wp_unslash( $_POST );
 
-    // Verify nonce, or unset submitted form field values on failure
+    // Verify nonce, or unset submitted form field values on failure.
     if ( ! isset( $_POST['_fs_nonce'] ) || ! wp_verify_nonce( $_POST['_fs_nonce'], 'filesystem-credentials' ) ) {
         unset(
@@ -2011 +2021 @@
     }
 
-    // If defined, set it to that, Else, If POST'd, set it to that, If not, Set it to whatever it previously was(saved details in option)
+    // If defined, set it to that. Else, if POST'd, set it to that. If not, set it to whatever it previously was (saved details in option).
     $credentials['hostname'] = defined( 'FTP_HOST' ) ? FTP_HOST : ( ! empty( $submitted_form['hostname'] ) ? $submitted_form['hostname'] : $credentials['hostname'] );
     $credentials['username'] = defined( 'FTP_USER' ) ? FTP_USER : ( ! empty( $submitted_form['username'] ) ? $submitted_form['username'] : $credentials['username'] );
     $credentials['password'] = defined( 'FTP_PASS' ) ? FTP_PASS : ( ! empty( $submitted_form['password'] ) ? $submitted_form['password'] : '' );
 
-    // Check to see if we are setting the public/private keys for ssh
+    // Check to see if we are setting the public/private keys for ssh.
     $credentials['public_key']  = defined( 'FTP_PUBKEY' ) ? FTP_PUBKEY : ( ! empty( $submitted_form['public_key'] ) ? $submitted_form['public_key'] : '' );
     $credentials['private_key'] = defined( 'FTP_PRIKEY' ) ? FTP_PRIKEY : ( ! empty( $submitted_form['private_key'] ) ? $submitted_form['private_key'] : '' );
 
-    // Sanitize the hostname, Some people might pass in odd-data:
-    $credentials['hostname'] = preg_replace( '|\w+://|', '', $credentials['hostname'] ); //Strip any schemes off
+    // Sanitize the hostname, some people might pass in odd data.
+    $credentials['hostname'] = preg_replace( '|\w+://|', '', $credentials['hostname'] ); // Strip any schemes off.
 
     if ( strpos( $credentials['hostname'], ':' ) ) {
@@ -2034 +2044 @@
     if ( ( defined( 'FTP_SSH' ) && FTP_SSH ) || ( defined( 'FS_METHOD' ) && 'ssh2' == FS_METHOD ) ) {
         $credentials['connection_type'] = 'ssh';
-    } elseif ( ( defined( 'FTP_SSL' ) && FTP_SSL ) && 'ftpext' == $type ) { //Only the FTP Extension understands SSL
+    } elseif ( ( defined( 'FTP_SSL' ) && FTP_SSL ) && 'ftpext' == $type ) { // Only the FTP Extension understands SSL.
         $credentials['connection_type'] = 'ftps';
     } elseif ( ! empty( $submitted_form['connection_type'] ) ) {
         $credentials['connection_type'] = $submitted_form['connection_type'];
-    } elseif ( ! isset( $credentials['connection_type'] ) ) { //All else fails (And it's not defaulted to something else saved), Default to FTP
+    } elseif ( ! isset( $credentials['connection_type'] ) ) { // All else fails (and it's not defaulted to something else saved), default to FTP.
         $credentials['connection_type'] = 'ftp';
     }
@@ -2047 +2057 @@
             ) ) {
         $stored_credentials = $credentials;
-        if ( ! empty( $stored_credentials['port'] ) ) { //save port as part of hostname to simplify above code.
+        if ( ! empty( $stored_credentials['port'] ) ) { // Save port as part of hostname to simplify above code.
             $stored_credentials['hostname'] .= ':' . $stored_credentials['port'];
         }
@@ -2076 +2086 @@
         $types['ftp'] = __( 'FTP' );
     }
-    if ( extension_loaded( 'ftp' ) ) { //Only this supports FTPS
+    if ( extension_loaded( 'ftp' ) ) { // Only this supports FTPS.
         $types['ftps'] = __( 'FTPS (SSL)' );
     }

trunk/src/wp-admin/includes/image-edit.php

@@ -200 +200 @@
             <?php
 
-            // On some setups GD library does not provide imagerotate() - Ticket #11536
+            // On some setups GD library does not provide imagerotate() - Ticket #11536.
             if ( wp_image_editor_supports(
                 array(
@@ -602 +602 @@
                     $h    = $size['height'];
 
-                    $scale = 1 / _image_get_preview_ratio( $w, $h ); // discard preview scaling
+                    $scale = 1 / _image_get_preview_ratio( $w, $h ); // Discard preview scaling.
                     $image->crop( $sel->x * $scale, $sel->y * $scale, $sel->w * $scale, $sel->h * $scale );
                 } else {
-                    $scale = 1 / _image_get_preview_ratio( imagesx( $image ), imagesy( $image ) ); // discard preview scaling
+                    $scale = 1 / _image_get_preview_ratio( imagesx( $image ), imagesy( $image ) ); // Discard preview scaling.
                     $image = _crop_image_resource( $image, $sel->x * $scale, $sel->y * $scale, $sel->w * $scale, $sel->h * $scale );
                 }
@@ -956 +956 @@
 
         if ( $target == 'thumbnail' || $target == 'all' || $target == 'full' ) {
-            // Check if it's an image edit from attachment edit screen
+            // Check if it's an image edit from attachment edit screen.
             if ( ! empty( $_REQUEST['context'] ) && 'edit-attachment' == $_REQUEST['context'] ) {
                 $thumb_url         = wp_get_attachment_image_src( $post_id, array( 900, 600 ), true );

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

@@ -25 +25 @@
 function wp_crop_image( $src, $src_x, $src_y, $src_w, $src_h, $dst_w, $dst_h, $src_abs = false, $dst_file = false ) {
     $src_file = $src;
-    if ( is_numeric( $src ) ) { // Handle int as attachment ID
+    if ( is_numeric( $src ) ) { // Handle int as attachment ID.
         $src_file = get_attached_file( $src );
 
@@ -118 +118 @@
     }
 
-    // Remove sizes that already exist. Only checks for matching "size names".
-    // It is possible that the dimensions for a particular size name have changed.
-    // For example the user has changed the values on the Settings -> Media screen.
-    // However we keep the old sub-sizes with the previous dimensions
-    // as the image may have been used in an older post.
+    /*
+     * Remove sizes that already exist. Only checks for matching "size names".
+     * It is possible that the dimensions for a particular size name have changed.
+     * For example the user has changed the values on the Settings -> Media screen.
+     * However we keep the old sub-sizes with the previous dimensions
+     * as the image may have been used in an older post.
+     */
     $missing_sizes = array_diff_key( $possible_sizes, $image_meta['sizes'] );
 
@@ -230 +232 @@
     }
 
-    // Default image meta
+    // Default image meta.
     $image_meta = array(
         'width'  => $imagesize[0],
@@ -319 +321 @@
             }
 
-            // Rotate the image
+            // Rotate the image.
             $rotated = $editor->maybe_exif_rotate();
 
@@ -340 +342 @@
     }
 
-    // Initial save of the new metadata.
-    // At this point the file was uploaded and moved to the uploads directory
-    // but the image sub-sizes haven't been created yet and the `sizes` array is empty.
+    /*
+     * Initial save of the new metadata.
+     * At this point the file was uploaded and moved to the uploads directory
+     * but the image sub-sizes haven't been created yet and the `sizes` array is empty.
+     */
     wp_update_attachment_metadata( $attachment_id, $image_meta );
 
@@ -387 +391 @@
     if ( isset( $image_meta['sizes'] ) && is_array( $image_meta['sizes'] ) ) {
         foreach ( $image_meta['sizes'] as $size_name => $size_meta ) {
-            // Only checks "size name" so we don't override existing images even if the dimensions
-            // don't match the currently defined size with the same name.
-            // To change the behavior, unset changed/mismatched sizes in the `sizes` array in image meta.
+            /*
+             * Only checks "size name" so we don't override existing images even if the dimensions
+             * don't match the currently defined size with the same name.
+             * To change the behavior, unset changed/mismatched sizes in the `sizes` array in image meta.
+             */
             if ( array_key_exists( $size_name, $new_sizes ) ) {
                 unset( $new_sizes[ $size_name ] );
@@ -403 +409 @@
     }
 
-    // Sort the image sub-sizes in order of priority when creating them.
-    // This ensures there is an appropriate sub-size the user can access immediately
-    // even when there was an error and not all sub-sizes were created.
+    /*
+     * Sort the image sub-sizes in order of priority when creating them.
+     * This ensures there is an appropriate sub-size the user can access immediately
+     * even when there was an error and not all sub-sizes were created.
+     */
     $priority = array(
         'medium'       => null,
@@ -734 +742 @@
             }
 
-            if ( ! empty( $iptc['2#110'][0] ) ) { // credit
+            if ( ! empty( $iptc['2#110'][0] ) ) { // Credit.
                 $meta['credit'] = trim( $iptc['2#110'][0] );
-            } elseif ( ! empty( $iptc['2#080'][0] ) ) { // creator / legacy byline
+            } elseif ( ! empty( $iptc['2#080'][0] ) ) { // Creator / legacy byline.
                 $meta['credit'] = trim( $iptc['2#080'][0] );
             }
 
-            if ( ! empty( $iptc['2#055'][0] ) && ! empty( $iptc['2#060'][0] ) ) { // created date and time
+            if ( ! empty( $iptc['2#055'][0] ) && ! empty( $iptc['2#060'][0] ) ) { // Created date and time.
                 $meta['created_timestamp'] = strtotime( $iptc['2#055'][0] . ' ' . $iptc['2#060'][0] );
             }
 
-            if ( ! empty( $iptc['2#116'][0] ) ) { // copyright
+            if ( ! empty( $iptc['2#116'][0] ) ) { // Copyright.
                 $meta['copyright'] = trim( $iptc['2#116'][0] );
             }
 
-            if ( ! empty( $iptc['2#025'][0] ) ) { // keywords array
+            if ( ! empty( $iptc['2#025'][0] ) ) { // Keywords array.
                 $meta['keywords'] = array_values( $iptc['2#025'] );
             }
@@ -774 +782 @@
 
             if ( empty( $meta['title'] ) && $description_length < 80 ) {
-                // Assume the title is stored in ImageDescription
+                // Assume the title is stored in ImageDescription.
                 $meta['title'] = trim( $exif['ImageDescription'] );
             }

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

@@ -104 +104 @@
     }
 
-    // Construct the object array
+    // Construct the object array.
     $object = array(
         'post_title'     => wp_basename( $upload['file'] ),
@@ -114 +114 @@
     );
 
-    // Save the data
+    // Save the data.
     $id = wp_insert_attachment( $object, $upload['file'] );
 
@@ -137 +137 @@
  */
 function wp_get_popular_importers() {
-    include( ABSPATH . WPINC . '/version.php' ); // include an unmodified $wp_version
+    include( ABSPATH . WPINC . '/version.php' ); // Include an unmodified $wp_version.
 
     $locale            = get_user_locale();
@@ -185 +185 @@
 
     return array(
-        // slug => name, description, plugin slug, and register_importer() slug
+        // slug => name, description, plugin slug, and register_importer() slug.
         'blogger'     => array(
             'name'        => __( 'Blogger' ),

trunk/src/wp-admin/includes/list-table.php

@@ -22 +22 @@
 function _get_list_table( $class, $args = array() ) {
     $core_classes = array(
-        //Site Admin
+        // Site Admin.
         'WP_Posts_List_Table'                         => 'posts',
         'WP_Media_List_Table'                         => 'media',
@@ -35 +35 @@
         'WP_Plugins_List_Table'                       => 'plugins',
 
-        // Network Admin
+        // Network Admin.
         'WP_MS_Sites_List_Table'                      => 'ms-sites',
         'WP_MS_Users_List_Table'                      => 'ms-users',
         'WP_MS_Themes_List_Table'                     => 'ms-themes',
 
-        // Privacy requests tables
+        // Privacy requests tables.
         'WP_Privacy_Data_Export_Requests_List_Table'  => 'privacy-data-export-requests',
         'WP_Privacy_Data_Removal_Requests_List_Table' => 'privacy-data-removal-requests',

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

@@ -16 +16 @@
 function media_upload_tabs() {
     $_default_tabs = array(
-        'type'     => __( 'From Computer' ), // handler action suffix => tab text
+        'type'     => __( 'From Computer' ), // Handler action suffix => tab text.
         'type_url' => __( 'From URL' ),
         'gallery'  => __( 'Gallery' ),
@@ -227 +227 @@
     $caption = preg_replace_callback( '/<[a-zA-Z0-9]+(?: [^<>]+>)*/', '_cleanup_image_add_caption', $caption );
 
-    // Convert any remaining line breaks to <br>.
+    // Convert any remaining line breaks to <br />.
     $caption = preg_replace( '/[ \n\t]*\n[ \t]*/', '<br />', $caption );
 
@@ -389 +389 @@
     }
 
-    // Construct the attachment array
+    // Construct the attachment array.
     $attachment = array_merge(
         array(
@@ -405 +405 @@
     unset( $attachment['ID'] );
 
-    // Save the data
+    // Save the data.
     $attachment_id = wp_insert_attachment( $attachment, $file, $post_id, true );
 
@@ -491 +491 @@
     unset( $attachment['ID'] );
 
-    // Save the attachment metadata
+    // Save the attachment metadata.
     $attachment_id = wp_insert_attachment( $attachment, $file, $post_id, true );
 
@@ -520 +520 @@
 
     wp_enqueue_style( 'colors' );
-    // Check callback name for 'media'
+    // Check callback name for 'media'.
     if (
         ( is_array( $content_func ) && ! empty( $content_func[1] ) && 0 === strpos( (string) $content_func[1], 'media' ) ) ||
@@ -850 +850 @@
     if ( isset( $_POST['html-upload'] ) && ! empty( $_FILES ) ) {
         check_admin_referer( 'media-form' );
-        // Upload File button was clicked
+        // Upload File button was clicked.
         $id = media_handle_upload( 'async-upload', $_REQUEST['post_id'] );
         unset( $_FILES );
@@ -1422 +1422 @@
     }
 
-    // Merge default fields with their errors, so any key passed with the error (e.g. 'error', 'helps', 'value') will replace the default
-    // The recursive merge is easily traversed with array casting: foreach ( (array) $things as $thing )
+    /*
+     * Merge default fields with their errors, so any key passed with the error
+     * (e.g. 'error', 'helps', 'value') will replace the default.
+     * The recursive merge is easily traversed with array casting:
+     * foreach ( (array) $things as $thing )
+     */
     $form_fields = array_merge_recursive( $form_fields, (array) $errors );
 
@@ -1597 +1601 @@
     }
 
-    $display_title = ( ! empty( $title ) ) ? $title : $filename; // $title shouldn't ever be empty, but just in case
+    $display_title = ( ! empty( $title ) ) ? $title : $filename; // $title shouldn't ever be empty, but just in case.
     $display_title = $parsed_args['show_title'] ? "<div class='filename new'><span class='title'>" . wp_html_excerpt( $display_title, 60, '&hellip;' ) . '</span></div>' : '';
 
@@ -1711 +1715 @@
     if ( isset( $_GET['post_id'] ) ) {
         $calling_post_id = absint( $_GET['post_id'] );
-    } elseif ( isset( $_POST ) && count( $_POST ) ) {// Like for async-upload where $_GET['post_id'] isn't set
+    } elseif ( isset( $_POST ) && count( $_POST ) ) {// Like for async-upload where $_GET['post_id'] isn't set.
         $calling_post_id = $post->post_parent;
     }
@@ -1876 +1880 @@
     }
 
-    // Merge default fields with their errors, so any key passed with the error (e.g. 'error', 'helps', 'value') will replace the default
-    // The recursive merge is easily traversed with array casting: foreach ( (array) $things as $thing )
+    /*
+     * Merge default fields with their errors, so any key passed with the error
+     * (e.g. 'error', 'helps', 'value') will replace the default.
+     * The recursive merge is easily traversed with array casting:
+     * foreach ( (array) $things as $thing )
+     */
     $form_fields = array_merge_recursive( $form_fields, (array) $args['errors'] );
 
@@ -2133 +2141 @@
     );
 
-    // Currently only iOS Safari supports multiple files uploading but iOS 7.x has a bug that prevents uploading of videos
-    // when enabled. See #29602.
+    /*
+     * Currently only iOS Safari supports multiple files uploading,
+     * but iOS 7.x has a bug that prevents uploading of videos when enabled.
+     * See #29602.
+     */
     if (
         wp_is_mobile() &&
@@ -2701 +2712 @@
             }
         }
-        // If available type specified by media button clicked, filter by that type
+        // If available type specified by media button clicked, filter by that type.
         if ( empty( $_GET['post_mime_type'] ) && ! empty( $num_posts[ $type ] ) ) {
             $_GET['post_mime_type']                        = $type;

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

@@ -209 +209 @@
         $i++;
 
-        if ( 0 == $order ) { // dashboard is always shown/single
+        if ( 0 == $order ) { // Dashboard is always shown/single.
             $menu[0][4] = add_cssclass( 'menu-top-first', $top[4] );
             $lastorder  = 0;
@@ -215 +215 @@
         }
 
-        if ( 0 === strpos( $top[2], 'separator' ) && false !== $lastorder ) { // if separator
+        if ( 0 === strpos( $top[2], 'separator' ) && false !== $lastorder ) { // If separator.
             $first                 = true;
             $c                     = $menu[ $lastorder ][4];
@@ -228 +228 @@
         }
 
-        if ( $mc == $i ) { // last item
+        if ( $mc == $i ) { // Last item.
             $c                 = $menu[ $order ][4];
             $menu[ $order ][4] = add_cssclass( 'menu-top-last', $c );
@@ -246 +246 @@
 }
 
-uksort( $menu, 'strnatcasecmp' ); // make it all pretty
+uksort( $menu, 'strnatcasecmp' ); // Make it all pretty.
 
 /**
@@ -311 +311 @@
 }
 
-// Prevent adjacent separators
+// Prevent adjacent separators.
 $prev_menu_was_separator = false;
 foreach ( $menu as $id => $data ) {
     if ( false === stristr( $data[4], 'wp-menu-separator' ) ) {
 
-        // This item is not a separator, so falsey the toggler and do nothing
+        // This item is not a separator, so falsey the toggler and do nothing.
         $prev_menu_was_separator = false;
     } else {
 
-        // The previous item was a separator, so unset this one
+        // The previous item was a separator, so unset this one.
         if ( true === $prev_menu_was_separator ) {
             unset( $menu[ $id ] );
         }
 
-        // This item is a separator, so truthy the toggler and move on
+        // This item is a separator, so truthy the toggler and move on.
         $prev_menu_was_separator = true;
     }