Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (7 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/kses.php

    r46959 r47122  
    10531053                        return '';
    10541054                }
    1055                 // prevent multiple dashes in comments
     1055                // Prevent multiple dashes in comments.
    10561056                $string = preg_replace( '/--+/', '-', $string );
    1057                 // prevent three dashes closing a comment
     1057                // Prevent three dashes closing a comment.
    10581058                $string = preg_replace( '/-$/', '', $string );
    10591059                return "<!--{$string}-->";
    … …  
    11201120        }
    11211121
    1122         // Split it
     1122        // Split it.
    11231123        $attrarr = wp_kses_hair( $attr, $allowed_protocols );
    11241124
    11251125        // Go through $attrarr, and save the allowed attributes for this element
    1126         // in $attr2
     1126        // in $attr2.
    11271127        $attr2 = '';
    11281128        foreach ( $attrarr as $arreach ) {
    … …  
    11321132        }
    11331133
    1134         // Remove any "<" or ">" characters
     1134        // Remove any "<" or ">" characters.
    11351135        $attr2 = preg_replace( '/[<>]/', '', $attr2 );
    11361136
    … …  
    12051205
    12061206        if ( is_array( $allowed_attr[ $name_low ] ) ) {
    1207                 // there are some checks
     1207                // There are some checks.
    12081208                foreach ( $allowed_attr[ $name_low ] as $currkey => $currval ) {
    12091209                        if ( ! wp_kses_check_attr_val( $value, $vless, $currkey, $currval ) ) {
    … …  
    12421242        $uris     = wp_kses_uri_attributes();
    12431243
    1244         // Loop through the whole attribute list
     1244        // Loop through the whole attribute list.
    12451245
    12461246        while ( strlen( $attr ) != 0 ) {
    … …  
    12591259
    12601260                        case 1:
    1261                                 if ( preg_match( '/^\s*=\s*/', $attr ) ) { // equals sign
     1261                                if ( preg_match( '/^\s*=\s*/', $attr ) ) { // Equals sign.
    12621262                                        $working = 1;
    12631263                                        $mode    = 2;
    … …  
    12661266                                }
    12671267
    1268                                 if ( preg_match( '/^\s+/', $attr ) ) { // valueless
     1268                                if ( preg_match( '/^\s+/', $attr ) ) { // Valueless.
    12691269                                        $working = 1;
    12701270                                        $mode    = 0;
    … …  
    13471347
    13481348                                break;
    1349                 } // switch
    1350 
    1351                 if ( $working == 0 ) { // not well formed, remove and try again
     1349                } // End switch.
     1350
     1351                if ( $working == 0 ) { // Not well-formed, remove and try again.
    13521352                        $attr = wp_kses_html_error( $attr );
    13531353                        $mode = 0;
    13541354                }
    1355         } // while
     1355        } // End while.
    13561356
    13571357        if ( $mode == 1 && false === array_key_exists( $attrname, $attrarr ) ) {
    1358                 // special case, for when the attribute list ends with a valueless
    1359                 // attribute like "selected"
     1358                // Special case, for when the attribute list ends with a valueless
     1359                // attribute like "selected".
    13601360                $attrarr[ $attrname ] = array(
    13611361                        'name'  => $attrname,
    … …  
    14061406        }
    14071407
    1408         // Split it
     1408        // Split it.
    14091409        $attrarr = wp_kses_hair_parse( $attr );
    14101410        if ( false === $attrarr ) {
    … …  
    14451445        . ')'
    14461446        . '(?:'               // Attribute value.
    1447         .     '\s*=\s*'       // All values begin with '='
     1447        .     '\s*=\s*'       // All values begin with '='.
    14481448        .     '(?:'
    1449         .         '"[^"]*"'   // Double-quoted
     1449        .         '"[^"]*"'   // Double-quoted.
    14501450        .     '|'
    1451         .         "'[^']*'"   // Single-quoted
     1451        .         "'[^']*'"   // Single-quoted.
    14521452        .     '|'
    1453         .         '[^\s"\']+' // Non-quoted
    1454         .         '(?:\s|$)'  // Must have a space
     1453        .         '[^\s"\']+' // Non-quoted.
     1454        .         '(?:\s|$)'  // Must have a space.
    14551455        .     ')'
    14561456        . '|'
    … …  
    14931493        switch ( strtolower( $checkname ) ) {
    14941494                case 'maxlen':
    1495                         // The maxlen check makes sure that the attribute value has a length not
    1496                         // greater than the given value. This can be used to avoid Buffer Overflows
    1497                         // in WWW clients and various Internet servers.
     1495                        /*
     1496                         * The maxlen check makes sure that the attribute value has a length not
     1497                         * greater than the given value. This can be used to avoid Buffer Overflows
     1498                         * in WWW clients and various Internet servers.
     1499                         */
    14981500
    14991501                        if ( strlen( $value ) > $checkvalue ) {
    … …  
    15031505
    15041506                case 'minlen':
    1505                         // The minlen check makes sure that the attribute value has a length not
    1506                         // smaller than the given value.
     1507                        /*
     1508                         * The minlen check makes sure that the attribute value has a length not
     1509                         * smaller than the given value.
     1510                         */
    15071511
    15081512                        if ( strlen( $value ) < $checkvalue ) {
    … …  
    15121516
    15131517                case 'maxval':
    1514                         // The maxval check does two things: it checks that the attribute value is
    1515                         // an integer from 0 and up, without an excessive amount of zeroes or
    1516                         // whitespace (to avoid Buffer Overflows). It also checks that the attribute
    1517                         // value is not greater than the given value.
    1518                         // This check can be used to avoid Denial of Service attacks.
     1518                        /*
     1519                         * The maxval check does two things: it checks that the attribute value is
     1520                         * an integer from 0 and up, without an excessive amount of zeroes or
     1521                         * whitespace (to avoid Buffer Overflows). It also checks that the attribute
     1522                         * value is not greater than the given value.
     1523                         * This check can be used to avoid Denial of Service attacks.
     1524                         */
    15191525
    15201526                        if ( ! preg_match( '/^\s{0,6}[0-9]{1,6}\s{0,6}$/', $value ) ) {
    … …  
    15271533
    15281534                case 'minval':
    1529                         // The minval check makes sure that the attribute value is a positive integer,
    1530                         // and that it is not smaller than the given value.
     1535                        /*
     1536                         * The minval check makes sure that the attribute value is a positive integer,
     1537                         * and that it is not smaller than the given value.
     1538                         */
    15311539
    15321540                        if ( ! preg_match( '/^\s{0,6}[0-9]{1,6}\s{0,6}$/', $value ) ) {
    … …  
    15391547
    15401548                case 'valueless':
    1541                         // The valueless check makes sure if the attribute has a value
    1542                         // (like `<a href="blah">`) or not (`<option selected>`). If the given value
    1543                         // is a "y" or a "Y", the attribute must not have a value.
    1544                         // If the given value is an "n" or an "N", the attribute must have a value.
     1549                        /*
     1550                         * The valueless check makes sure if the attribute has a value
     1551                         * (like `<a href="blah">`) or not (`<option selected>`). If the given value
     1552                         * is a "y" or a "Y", the attribute must not have a value.
     1553                         * If the given value is an "n" or an "N", the attribute must have a value.
     1554                         */
    15451555
    15461556                        if ( strtolower( $checkvalue ) != $vless ) {
    … …  
    15481558                        }
    15491559                        break;
    1550         } // switch
     1560        } // End switch.
    15511561
    15521562        return $ok;
    … …  
    17441754        $string = str_replace( '&', '&amp;', $string );
    17451755
    1746         // Change back the allowed entities in our entity whitelist
     1756        // Change back the allowed entities in our entity whitelist.
    17471757        $string = preg_replace_callback( '/&amp;([A-Za-z]{2,8}[0-9]{0,2});/', 'wp_kses_named_entities', $string );
    17481758        $string = preg_replace_callback( '/&amp;#(0*[0-9]{1,7});/', 'wp_kses_normalize_entities2', $string );
    … …  
    19922002 */
    19932003function kses_init_filters() {
    1994         // Normal filtering
     2004        // Normal filtering.
    19952005        add_filter( 'title_save_pre', 'wp_filter_kses' );
    19962006
    1997         // Comment filtering
     2007        // Comment filtering.
    19982008        if ( current_user_can( 'unfiltered_html' ) ) {
    19992009                add_filter( 'pre_comment_content', 'wp_filter_post_kses' );
    … …  
    20022012        }
    20032013
    2004         // Post filtering
     2014        // Post filtering.
    20052015        add_filter( 'content_save_pre', 'wp_filter_post_kses' );
    20062016        add_filter( 'excerpt_save_pre', 'wp_filter_post_kses' );
    … …  
    20212031 */
    20222032function kses_remove_filters() {
    2023         // Normal filtering
     2033        // Normal filtering.
    20242034        remove_filter( 'title_save_pre', 'wp_filter_kses' );
    20252035
    2026         // Comment filtering
     2036        // Comment filtering.
    20272037        remove_filter( 'pre_comment_content', 'wp_filter_post_kses' );
    20282038        remove_filter( 'pre_comment_content', 'wp_filter_kses' );
    20292039
    2030         // Post filtering
     2040        // Post filtering.
    20312041        remove_filter( 'content_save_pre', 'wp_filter_post_kses' );
    20322042        remove_filter( 'excerpt_save_pre', 'wp_filter_post_kses' );
    … …  
    20622072function safecss_filter_attr( $css, $deprecated = '' ) {
    20632073        if ( ! empty( $deprecated ) ) {
    2064                 _deprecated_argument( __FUNCTION__, '2.8.1' ); // Never implemented
     2074                _deprecated_argument( __FUNCTION__, '2.8.1' ); // Never implemented.
    20652075        }
    20662076
Note: See TracChangeset for help on using the changeset viewer.