WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
01/18/2020 12:52:28 AM (6 years ago)
Author:
SergeyBiryukov
Message:

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

Props passoniate.
Fixes #49215, #49216.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r47060 r47084  
    2222    '404.php'               => __( '404 Template' ),
    2323    'link.php'              => __( 'Links Template' ),
    24     // Archives
     24    // Archives.
    2525    'index.php'             => __( 'Main Index Template' ),
    2626    'archive.php'           => __( 'Archives' ),
    … …  
    3232    'search.php'            => __( 'Search Results' ),
    3333    'date.php'              => __( 'Date Template' ),
    34     // Content
     34    // Content.
    3535    'singular.php'          => __( 'Singular Template' ),
    3636    'single.php'            => __( 'Single Post' ),
    … …  
    3838    'front-page.php'        => __( 'Homepage' ),
    3939    'privacy-policy.php'    => __( 'Privacy Policy Page' ),
    40     // Attachments
     40    // Attachments.
    4141    'attachment.php'        => __( 'Attachment Template' ),
    4242    'image.php'             => __( 'Image Attachment Template' ),
    … …  
    4444    'audio.php'             => __( 'Audio Attachment Template' ),
    4545    'application.php'       => __( 'Application Attachment Template' ),
    46     // Embeds
     46    // Embeds.
    4747    'embed.php'             => __( 'Embed Template' ),
    4848    'embed-404.php'         => __( 'Embed 404 Template' ),
    … …  
    5050    'header-embed.php'      => __( 'Embed Header Template' ),
    5151    'footer-embed.php'      => __( 'Embed Footer Template' ),
    52     // Stylesheets
     52    // Stylesheets.
    5353    'style.css'             => __( 'Stylesheet' ),
    5454    'editor-style.css'      => __( 'Visual Editor Stylesheet' ),
    5555    'editor-style-rtl.css'  => __( 'Visual Editor RTL Stylesheet' ),
    5656    'rtl.css'               => __( 'RTL Stylesheet' ),
    57     // Other
     57    // Other.
    5858    'my-hacks.php'          => __( 'my-hacks.php (legacy hacks support)' ),
    5959    '.htaccess'             => __( '.htaccess (for rewrite rules )' ),
    60     // Deprecated files
     60    // Deprecated files.
    6161    'wp-layout.css'         => __( 'Stylesheet' ),
    6262    'wp-comments.php'       => __( 'Comments Template' ),
    … …  
    456456        }
    457457
    458         // Compare based on relative paths
     458        // Compare based on relative paths.
    459459        if ( 0 !== validate_file( $file, array_keys( $allowed_files ) ) ) {
    460460            return new WP_Error( 'disallowed_theme_file', __( 'Sorry, that file cannot be edited.' ) );
    … …  
    508508        $transient    = 'scrape_key_' . $scrape_key;
    509509        $scrape_nonce = strval( rand() );
    510         set_transient( $transient, $scrape_nonce, 60 ); // It shouldn't take more than 60 seconds to make the two loopback requests.
     510        // It shouldn't take more than 60 seconds to make the two loopback requests.
     511        set_transient( $transient, $scrape_nonce, 60 );
    511512
    512513        $cookies       = wp_unslash( $_COOKIE );
    … …  
    645646    }
    646647
    647     // Use the basename of the given file without the extension as the name for the temporary directory
     648    // Use the basename of the given file without the extension as the name for the temporary directory.
    648649    $temp_filename = basename( $filename );
    649650    $temp_filename = preg_replace( '|\.[^.]*$|', '', $temp_filename );
    … …  
    654655    }
    655656
    656     // Suffix some random data to avoid filename conflicts
     657    // Suffix some random data to avoid filename conflicts.
    657658    $temp_filename .= '-' . wp_generate_password( 6, false );
    658659    $temp_filename .= '.tmp';
    … …  
    736737    $file = apply_filters( "{$action}_prefilter", $file );
    737738
    738     // You may define your own function and pass the name in $overrides['upload_error_handler']
     739    // You may define your own function and pass the name in $overrides['upload_error_handler'].
    739740    $upload_error_handler = 'wp_handle_upload_error';
    740741    if ( isset( $overrides['upload_error_handler'] ) ) {
    … …  
    749750    // Install user overrides. Did we mention that this voids your warranty?
    750751
    751     // You may define your own function and pass the name in $overrides['unique_filename_callback']
     752    // You may define your own function and pass the name in $overrides['unique_filename_callback'].
    752753    $unique_filename_callback = null;
    753754    if ( isset( $overrides['unique_filename_callback'] ) ) {
    … …  
    823824        $proper_filename = empty( $wp_filetype['proper_filename'] ) ? '' : $wp_filetype['proper_filename'];
    824825
    825         // Check to see if wp_check_filetype_and_ext() determined the filename was incorrect
     826        // Check to see if wp_check_filetype_and_ext() determined the filename was incorrect.
    826827        if ( $proper_filename ) {
    827828            $file['name'] = $proper_filename;
    … …  
    870871            $move_new_file = @move_uploaded_file( $file['tmp_name'], $new_file );
    871872        } else {
    872             // use copy and unlink because rename breaks streams.
     873            // Use copy and unlink because rename breaks streams.
    873874            // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
    874875            $move_new_file = @copy( $file['tmp_name'], $new_file );
    … …  
    10021003 */
    10031004function download_url( $url, $timeout = 300, $signature_verification = false ) {
    1004     //WARNING: The file is not automatically deleted, The script must unlink() the file.
     1005    // WARNING: The file is not automatically deleted, the script must unlink() the file.
    10051006    if ( ! $url ) {
    10061007        return new WP_Error( 'http_no_url', __( 'Invalid URL Provided.' ) );
    … …  
    10831084        if ( ! $signature ) {
    10841085            // Retrieve signatures from a file if the header wasn't included.
    1085             // WordPress.org stores signatures at $package_url.sig
     1086            // WordPress.org stores signatures at $package_url.sig.
    10861087
    10871088            $signature_url = false;
    … …  
    11051106                    $signature_url,
    11061107                    array(
    1107                         'limit_response_size' => 10 * 1024, // 10KB should be large enough for quite a few signatures.
     1108                        'limit_response_size' => 10 * KB_IN_BYTES, // 10KB should be large enough for quite a few signatures.
    11081109                    )
    11091110                );
    … …  
    11621163        $expected_raw_md5 = base64_decode( $expected_md5 );
    11631164    } else {
    1164         return false; // unknown format
     1165        return false; // Unknown format.
    11651166    }
    11661167
    … …  
    12111212    }
    12121213
    1213     // Check for a edge-case affecting PHP Maths abilities
     1214    // Check for a edge-case affecting PHP Maths abilities.
    12141215    if (
    12151216        ! extension_loaded( 'sodium' ) &&
    … …  
    12511252        }
    12521253
    1253         // This cannot be performed in a reasonable amount of time
     1254        // This cannot be performed in a reasonable amount of time.
    12541255        // https://github.com/paragonie/sodium_compat#help-sodium_compat-is-slow-how-can-i-make-it-fast
    12551256        if ( ! $sodium_compat_is_fast ) {
    … …  
    14791480        }
    14801481
    1481         if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory
     1482        if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory.
    14821483            continue;
    14831484        }
    … …  
    15161517    foreach ( $needed_dirs as $dir ) {
    15171518        // Check the parent folders of the folders all exist within the creation array.
    1518         if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, We know this exists (or will exist)
     1519        if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, we know this exists (or will exist).
    15191520            continue;
    15201521        }
    1521         if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, Skip it
     1522        if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, skip it.
    15221523            continue;
    15231524        }
    … …  
    15501551        }
    15511552
    1552         if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files
     1553        if ( '__MACOSX/' === substr( $info['name'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files.
    15531554            continue;
    15541555        }
    … …  
    16161617    $uncompressed_size = 0;
    16171618
    1618     // Determine any children directories needed (From within the archive)
     1619    // Determine any children directories needed (From within the archive).
    16191620    foreach ( $archive_files as $file ) {
    1620         if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory
     1621        if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Skip the OS X-created __MACOSX directory.
    16211622            continue;
    16221623        }
    … …  
    16421643    foreach ( $needed_dirs as $dir ) {
    16431644        // Check the parent folders of the folders all exist within the creation array.
    1644         if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, We know this exists (or will exist)
     1645        if ( untrailingslashit( $to ) == $dir ) { // Skip over the working directory, we know this exists (or will exist).
    16451646            continue;
    16461647        }
    1647         if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, Skip it
     1648        if ( strpos( $dir, $to ) === false ) { // If the directory is not within the working directory, skip it.
    16481649            continue;
    16491650        }
    … …  
    16661667    unset( $needed_dirs );
    16671668
    1668     // Extract the files from the zip
     1669    // Extract the files from the zip.
    16691670    foreach ( $archive_files as $file ) {
    16701671        if ( $file['folder'] ) {
    … …  
    16721673        }
    16731674
    1674         if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files
     1675        if ( '__MACOSX/' === substr( $file['filename'], 0, 9 ) ) { // Don't extract the OS X-created __MACOSX directory files.
    16751676            continue;
    16761677        }
    … …  
    17311732            }
    17321733
    1733             // generate the $sub_skip_list for the subdirectory as a sub-set of the existing $skip_list
     1734            // Generate the $sub_skip_list for the subdirectory as a sub-set of the existing $skip_list.
    17341735            $sub_skip_list = array();
    17351736            foreach ( $skip_list as $skip_item ) {
    … …  
    17491750
    17501751/**
    1751  * Initialises and connects the WordPress Filesystem Abstraction classes.
     1752 * Initializes and connects the WordPress Filesystem Abstraction classes.
    17521753 *
    17531754 * This function will include the chosen transport and attempt connecting.
    … …  
    18011802    $wp_filesystem = new $method( $args );
    18021803
    1803     //Define the timeouts for the connections. Only available after the construct is called to allow for per-transport overriding of the default.
     1804    /*
     1805     * Define the timeouts for the connections. Only available after the constructor is called
     1806     * to allow for per-transport overriding of the default.
     1807     */
    18041808    if ( ! defined( 'FS_CONNECT_TIMEOUT' ) ) {
    18051809        define( 'FS_CONNECT_TIMEOUT', 30 );
    … …  
    18141818
    18151819    if ( ! $wp_filesystem->connect() ) {
    1816         return false; //There was an error connecting to the server.
     1820        return false; // There was an error connecting to the server.
    18171821    }
    18181822
    … …  
    18551859 */
    18561860function get_filesystem_method( $args = array(), $context = '', $allow_relaxed_file_ownership = false ) {
    1857     $method = defined( 'FS_METHOD' ) ? FS_METHOD : false; // Please ensure that this is either 'direct', 'ssh2', 'ftpext' or 'ftpsockets'
     1861    // Please ensure that this is either 'direct', 'ssh2', 'ftpext', or 'ftpsockets'.
     1862    $method = defined( 'FS_METHOD' ) ? FS_METHOD : false;
    18581863
    18591864    if ( ! $context ) {
    … …  
    18741879        if ( $temp_handle ) {
    18751880
    1876             // Attempt to determine the file owner of the WordPress files, and that of newly created files
     1881            // Attempt to determine the file owner of the WordPress files, and that of newly created files.
    18771882            $wp_file_owner   = false;
    18781883            $temp_file_owner = false;
    … …  
    18831888
    18841889            if ( $wp_file_owner !== false && $wp_file_owner === $temp_file_owner ) {
    1885                 // WordPress is creating files as the same owner as the WordPress files,
    1886                 // this means it's safe to modify & create new files via PHP.
     1890                /*
     1891                 * WordPress is creating files as the same owner as the WordPress files,
     1892                 * this means it's safe to modify & create new files via PHP.
     1893                 */
    18871894                $method                                  = 'direct';
    18881895                $GLOBALS['_wp_filesystem_direct_method'] = 'file_owner';
    18891896            } elseif ( $allow_relaxed_file_ownership ) {
    1890                 // The $context directory is writable, and $allow_relaxed_file_ownership is set, this means we can modify files
    1891                 // safely in this directory. This mode doesn't create new files, only alter existing ones.
     1897                /*
     1898                 * The $context directory is writable, and $allow_relaxed_file_ownership is set,
     1899                 * this means we can modify files safely in this directory.
     1900                 * This mode doesn't create new files, only alter existing ones.
     1901                 */
    18921902                $method                                  = 'direct';
    18931903                $GLOBALS['_wp_filesystem_direct_method'] = 'relaxed_ownership';
    … …  
    19061916    }
    19071917    if ( ! $method && ( extension_loaded( 'sockets' ) || function_exists( 'fsockopen' ) ) ) {
    1908         $method = 'ftpsockets'; //Sockets: Socket extension; PHP Mode: FSockopen / fwrite / fread
     1918        $method = 'ftpsockets'; // Sockets: Socket extension; PHP Mode: FSockopen / fwrite / fread.
    19091919    }
    19101920
    … …  
    19992009    $submitted_form = wp_unslash( $_POST );
    20002010
    2001     // Verify nonce, or unset submitted form field values on failure
     2011    // Verify nonce, or unset submitted form field values on failure.
    20022012    if ( ! isset( $_POST['_fs_nonce'] ) || ! wp_verify_nonce( $_POST['_fs_nonce'], 'filesystem-credentials' ) ) {
    20032013        unset(
    … …  
    20112021    }
    20122022
    2013     // 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)
     2023    // 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).
    20142024    $credentials['hostname'] = defined( 'FTP_HOST' ) ? FTP_HOST : ( ! empty( $submitted_form['hostname'] ) ? $submitted_form['hostname'] : $credentials['hostname'] );
    20152025    $credentials['username'] = defined( 'FTP_USER' ) ? FTP_USER : ( ! empty( $submitted_form['username'] ) ? $submitted_form['username'] : $credentials['username'] );
    20162026    $credentials['password'] = defined( 'FTP_PASS' ) ? FTP_PASS : ( ! empty( $submitted_form['password'] ) ? $submitted_form['password'] : '' );
    20172027
    2018     // Check to see if we are setting the public/private keys for ssh
     2028    // Check to see if we are setting the public/private keys for ssh.
    20192029    $credentials['public_key']  = defined( 'FTP_PUBKEY' ) ? FTP_PUBKEY : ( ! empty( $submitted_form['public_key'] ) ? $submitted_form['public_key'] : '' );
    20202030    $credentials['private_key'] = defined( 'FTP_PRIKEY' ) ? FTP_PRIKEY : ( ! empty( $submitted_form['private_key'] ) ? $submitted_form['private_key'] : '' );
    20212031
    2022     // Sanitize the hostname, Some people might pass in odd-data:
    2023     $credentials['hostname'] = preg_replace( '|\w+://|', '', $credentials['hostname'] ); //Strip any schemes off
     2032    // Sanitize the hostname, some people might pass in odd data.
     2033    $credentials['hostname'] = preg_replace( '|\w+://|', '', $credentials['hostname'] ); // Strip any schemes off.
    20242034
    20252035    if ( strpos( $credentials['hostname'], ':' ) ) {
    … …  
    20342044    if ( ( defined( 'FTP_SSH' ) && FTP_SSH ) || ( defined( 'FS_METHOD' ) && 'ssh2' == FS_METHOD ) ) {
    20352045        $credentials['connection_type'] = 'ssh';
    2036     } elseif ( ( defined( 'FTP_SSL' ) && FTP_SSL ) && 'ftpext' == $type ) { //Only the FTP Extension understands SSL
     2046    } elseif ( ( defined( 'FTP_SSL' ) && FTP_SSL ) && 'ftpext' == $type ) { // Only the FTP Extension understands SSL.
    20372047        $credentials['connection_type'] = 'ftps';
    20382048    } elseif ( ! empty( $submitted_form['connection_type'] ) ) {
    20392049        $credentials['connection_type'] = $submitted_form['connection_type'];
    2040     } elseif ( ! isset( $credentials['connection_type'] ) ) { //All else fails (And it's not defaulted to something else saved), Default to FTP
     2050    } elseif ( ! isset( $credentials['connection_type'] ) ) { // All else fails (and it's not defaulted to something else saved), default to FTP.
    20412051        $credentials['connection_type'] = 'ftp';
    20422052    }
    … …  
    20472057            ) ) {
    20482058        $stored_credentials = $credentials;
    2049         if ( ! empty( $stored_credentials['port'] ) ) { //save port as part of hostname to simplify above code.
     2059        if ( ! empty( $stored_credentials['port'] ) ) { // Save port as part of hostname to simplify above code.
    20502060            $stored_credentials['hostname'] .= ':' . $stored_credentials['port'];
    20512061        }
    … …  
    20762086        $types['ftp'] = __( 'FTP' );
    20772087    }
    2078     if ( extension_loaded( 'ftp' ) ) { //Only this supports FTPS
     2088    if ( extension_loaded( 'ftp' ) ) { // Only this supports FTPS.
    20792089        $types['ftps'] = __( 'FTPS (SSL)' );
    20802090    }
Note: See TracChangeset for help on using the changeset viewer.